名称：自定义代理设计 描述：使用Claude Agent SDK模式从头设计自定义代理。当构建领域特定的代理、设计具有完全SDK控制的代理或创建具有自定义工具和提示的专用代理时使用。 允许工具：Read, Grep, Glob
自定义代理设计技能
使用Claude Agent SDK模式设计领域特定的代理。
目的
指导设计自定义代理，以解决领域特定的问题，通过完全SDK控制上下文、模型、提示和工具。
何时使用
- 构建新的自定义代理
- 将通用工作流转换为专用代理
- 设计领域特定的自动化
- 创建可重复的代理模式
先决条件
- 对领域问题的清晰理解
- 访问Claude Agent SDK文档
- 理解何时自定义代理是合适的（参见@agent-evolution-path.md）
设计过程
步骤1：定义代理目的
回答这些问题：
- 这个代理解决什么具体问题？
- 它需要什么领域专业知识？
- 单一目的是什么？（一个代理，一个目的）
- 利益相关者是谁？
输出：目的陈述（2-3句话）
步骤2：选择模型
基于任务复杂性选择：
| 任务类型 | 模型 | 为什么 |
|---|---|---|
| 简单转换 | Haiku | 快速、廉价 |
| 平衡任务 | Sonnet | 良好权衡 |
| 复杂推理 | Opus | 最高质量 |
决策因素：
- 速度要求
- 质量要求
- 成本约束
- 任务复杂性
步骤3：设计系统提示
选择架构：
覆盖 (system_prompt=...)
- 当：构建新产品时
- 结果：不再是Claude Code
- 完全控制行为
附加 (append_system_prompt=...)
- 当：扩展Claude Code时
- 结果：增强的Claude Code
- 添加能力
系统提示模板：
# [代理名称]
## 目的
[身份和角色定义 - 2-3句话]
## 指令
[核心行为 - 项目符号列表]
- 行为1
- 行为2
## 约束
[代理不能做什么]
## 示例（如果需要）
[输入/输出对]
步骤4：配置工具访问
要回答的问题：
- 这个代理需要什么工具？
- 应该阻止什么工具？
- 是否需要自定义工具？
工具配置：
# 白名单方法
allowed_tools=["Read", "Write", "Bash"]
# 黑名单方法
disallowed_tools=["WebFetch", "WebSearch", "TodoWrite"]
# 无默认工具
disallowed_tools=["*"]
# 自定义工具
mcp_servers={"domain": custom_mcp_server}
allowed_tools=["mcp__domain__tool1", "mcp__domain__tool2"]
步骤5：添加治理（可选）
如果需要安全/治理：
hooks = {
"PreToolUse": [
HookMatcher(matcher="Read", hooks=[block_sensitive_files]),
HookMatcher(hooks=[log_all_tool_usage]),
]
}
步骤6：选择部署形式
| 形式 | 使用时机 |
|---|---|
| 脚本 | 一次性自动化、ADWs |
| 终端REPL | 交互式工具 |
| 后端API | UI集成 |
| 数据流 | 实时处理 |
| 多代理 | 复杂工作流 |
步骤7：创建配置
组装ClaudeAgentOptions：
options = ClaudeAgentOptions(
# 上下文
system_prompt=load_system_prompt("agent_system.md"),
# 模型
model="opus",
# 工具
allowed_tools=["Read", "Write", "custom_tool"],
disallowed_tools=["WebFetch", "WebSearch"],
# 自定义工具（如果需要）
mcp_servers={"domain": domain_mcp_server},
# 治理（如果需要）
hooks=security_hooks,
# 会话（如果需要）
resume=session_id,
)
输出格式
当设计自定义代理时，提供：
## 自定义代理设计
**名称:** [代理名称]
**目的:** [1-2句话]
**领域:** [专业知识领域]
### 配置
**模型:** [haiku/sonnet/opus] - [原因]
**系统提示架构:**
- 类型: [覆盖/附加]
- 原因: [为什么选择这个]
**工具访问:**
- 允许: [列表]
- 不允许: [列表]
- 自定义: [如果有列出]
**治理:**
- 钩子: [如果有列出]
- 安全: [考虑]
**部署:**
- 形式: [脚本/repl/api/流/多代理]
- 原因: [为什么选择这种形式]
### 系统提示
[完整系统提示内容]
### 实现注释
[任何特殊考虑]
设计检查清单
- [ ] 目的具体清晰
- [ ] 模型匹配任务复杂性
- [ ] 系统提示架构选择（覆盖 vs 附加）
- [ ] 系统提示遵循模板
- [ ] 工具访问最小（仅需所需）
- [ ] 如果需要安全，添加治理钩子
- [ ] 部署形式选择
- [ ] 配置组装
反模式
| 避免 | 为什么 | 替代 |
|---|---|---|
| 与Claude Code竞争 | 无法击败通用代理 | 专门化 |
| 通用系统提示 | 无领域优势 | 领域特定 |
| 太多工具 | 上下文开销 | 最小工具集 |
| 缺少治理 | 安全风险 | 添加钩子 |
| 当附加有效时覆盖 | 失去Claude Code优势 | 使用附加 |
交叉引用
- @agent-evolution-path.md - 何时构建自定义代理
- @core-four-custom.md - 核心四配置
- @system-prompt-architecture.md - 覆盖 vs 附加
- @custom-tool-patterns.md - 工具创建
- @model-selection skill - 模型选择指南
版本历史
- v1.0.0 (2025-12-26): 初始发布
最后更新
日期: 2025-12-26 模型: claude-opus-4-5-20251101