Claude Code插件的Agent开发指南
概述
Agent是能够独立处理复杂多步骤任务的自主子进程。理解Agent的结构、触发条件和系统提示词设计,可以创建强大的自主能力。
关键概念:
- Agent是为了自主工作,而命令是为了用户发起的操作
- 带YAML frontmatter的Markdown文件格式
- 通过带有示例的description字段触发
- 系统提示词定义Agent行为
- 模型和颜色自定义
Agent文件结构
完整格式
---
name: agent-identifier
description: 当[触发条件]时使用该Agent。示例:
<example>
Context: [场景描述]
user: "[用户请求]"
assistant: "[助手应如何响应并使用该Agent]"
<commentary>
[为什么应该触发该Agent]
</commentary>
</example>
<example>
[更多示例...]
</example>
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
你是[Agent角色描述]...
**你的核心职责:**
1. [职责1]
2. [职责2]
**分析流程:**
[步骤化工作流程]
**输出格式:**
[返回内容]
Frontmatter字段
name(必填)
用于命名空间和调用的Agent标识符。
**格式:**仅限小写字母、数字、连字符 **长度:**3-50个字符 **模式:**必须以字母数字开头和结尾
好示例:
code-reviewertest-generatorapi-docs-writersecurity-analyzer
坏示例:
helper(过于通用)-agent-(以连字符开头/结尾)my_agent(不允许下划线)ag(太短,<3个字符)
description(必填)
定义Claude何时应触发该Agent。这是最关键字段。
必须包含:
- 触发条件("当...时使用该Agent")
- 多个展示用法的
<example>块 - 每个示例中的Context、user请求和assistant响应
- 解释触发原因的
<commentary>
格式:
当[条件]时使用该Agent。示例:
<example>
Context: [场景描述]
user: "[用户所说]"
assistant: "[Claude应如何响应]"
<commentary>
[该Agent为何适用]
</commentary>
</example>
[更多示例...]
最佳实践:
- 包含2-4个具体示例
- 展示主动和被动触发
- 覆盖同一意图的不同表述
- 在commentary中解释推理
- 明确说明何时不使用该Agent
model(必填)
Agent应使用的模型。
选项:
inherit- 使用与父级相同的模型(推荐)sonnet- Claude Sonnet(均衡)opus- Claude Opus(最强,成本高)haiku- Claude Haiku(快速,便宜)
**建议:**除非Agent需要特定模型能力,否则使用inherit。
color(必填)
Agent在UI中的视觉标识符。
选项:blue, cyan, green, yellow, magenta, red
指南:
- 同一插件中的不同Agent选择不同的颜色
- 相似类型的Agent使用一致的颜色
- Blue/cyan:分析、审查
- Green:面向成功的任务
- Yellow:谨慎、验证
- Red:关键、安全
- Magenta:创意、生成
tools(可选)
将Agent限制为特定工具。
**格式:**工具名称数组
tools: ["Read", "Write", "Grep", "Bash"]
**默认:**如省略,Agent可访问所有工具
**最佳实践:**将工具限制为所需的最小集合(最小权限原则)
常见工具组合:
- 只读分析:
["Read", "Grep", "Glob"] - 代码生成:
["Read", "Write", "Grep"] - 测试:
["Read", "Bash", "Grep"] - 完全访问:省略字段或使用
["*"]
系统提示词设计
Markdown正文成为Agent的系统提示词。以第二人称写作,直接对Agent讲话。
结构
标准模板:
你是专注于[领域]的[角色]。
**你的核心职责:**
1. [主要职责]
2. [次要职责]
3. [更多职责...]
**分析流程:**
1. [步骤一]
2. [步骤二]
3. [步骤三]
[...]
**质量标准:**
- [标准1]
- [标准2]
**输出格式:**
以以下格式提供结果:
- [包含内容]
- [如何组织]
**边缘情况:**
处理以下情况:
- [边缘情况1]:[如何处理]
- [边缘情况2]:[如何处理]
最佳实践
✅ 应做:
- 以第二人称写作("你是...", "你将...")
- 具体说明职责
- 提供步骤化的流程
- 定义输出格式
- 包含质量标准
- 处理边缘情况
- 保持少于10,000字符
❌ 不应做:
- 以第一人称写作("我是...", "我将...")
- 模糊或泛泛而谈
- 省略流程步骤
- 未定义输出格式
- 跳过质量指导
- 忽略错误情况
创建Agent
方法1:AI辅助生成
使用此提示模式(摘自Claude Code):
根据以下请求创建一个Agent配置:"[你的描述]"
要求:
1. 提取核心意图和职责
2. 为该领域设计专家角色
3. 创建全面的系统提示词,包含:
- 清晰的行为边界
- 具体方法
- 边缘情况处理
- 输出格式
4. 创建标识符(小写、连字符、3-50字符)
5. 编写带有触发条件的描述
6. 包含2-3个展示何时使用的<example>块
返回JSON,格式如下:
{
"identifier": "agent-name",
"whenToUse": "当...时使用该Agent。示例:<example>...</example>",
"systemPrompt": "你是..."
}
然后转换为带有frontmatter的Agent文件格式。
完整模板请参阅 examples/agent-creation-prompt.md。
方法2:手动创建
- 选择Agent标识符(3-50字符,小写,连字符)
- 编写带示例的描述
- 选择模型(通常为
inherit) - 选择视觉识别的颜色
- 定义工具(如需限制访问)
- 按上述结构编写系统提示词
- 保存为
agents/agent-name.md
验证规则
标识符验证
✅ 有效:code-reviewer, test-gen, api-analyzer-v2
❌ 无效:ag(太短), -start(以连字符开头), my_agent(下划线)
规则:
- 3-50个字符
- 仅限小写字母、数字、连字符
- 必须以字母数字开头和结尾
- 无下划线、空格或特殊字符
Description验证
**长度:**10-5,000字符 **必须包含:**触发条件和示例 **最佳:**200-1,000字符,2-4个示例
系统提示词验证
**长度:**20-10,000字符 **最佳:**500-3,000字符 **结构:**清晰的职责、流程、输出格式
Agent组织
插件Agents目录
plugin-name/
└── agents/
├── analyzer.md
├── reviewer.md
└── generator.md
agents/目录下的所有.md文件将被自动发现。
命名空间
Agent自动分配命名空间:
- 单插件:
agent-name - 带子目录:
plugin:subdir:agent-name
测试Agent
测试触发
创建测试场景以验证Agent是否正确触发:
- 编写带有特定触发示例的Agent
- 在测试中使用与示例相似的措辞
- 检查Claude是否加载了Agent
- 验证Agent提供了预期功能
测试系统提示词
确保系统提示词完整:
- 给Agent典型任务
- 检查它是否遵循流程步骤
- 验证输出格式是否正确
- 测试提示词中提到的边缘情况
- 确认达到质量标准
快速参考
最小Agent
---
name: simple-agent
description: 当...时使用该Agent。示例:<example>...</example>
model: inherit
color: blue
---
你是执行[某事]的Agent。
流程:
1. [步骤1]
2. [步骤2]
输出:[提供内容]
Frontmatter字段摘要
| 字段 | 必填 | 格式 | 示例 |
|---|---|---|---|
| name | 是 | 小写-连字符 | code-reviewer |
| description | 是 | 文本+示例 | 何时使用... ... |
| model | 是 | inherit/sonnet/opus/haiku | inherit |
| color | 是 | 颜色名称 | blue |
| tools | 否 | 工具名称数组 | ["Read", "Grep"] |
最佳实践
应做:
- ✅ 在描述中包含2-4个具体示例
- ✅ 编写具体的触发条件
- ✅ 除非有特殊需求,否则使用
inherit作为模型 - ✅ 选择合适的工具(最小权限)
- ✅ 编写清晰、结构化的系统提示词
- ✅ 彻底测试Agent触发
不应做:
- ❌ 使用没有示例的通用描述
- ❌ 省略触发条件
- ❌ 所有Agent使用相同颜色
- ❌ 授予不必要的工具访问权限
- ❌ 编写模糊的系统提示词
- ❌ 跳过测试
附加资源
参考文件
有关详细指导,请参考:
references/system-prompt-design.md- 完整的系统提示词模式references/triggering-examples.md- 示例格式和最佳实践references/agent-creation-system-prompt.md- 来自Claude Code的确切提示
示例文件
examples/目录下的工作示例:
agent-creation-prompt.md- AI辅助Agent生成模板complete-agent-examples.md- 不同用例的完整Agent示例
实用脚本
scripts/目录下的开发工具:
validate-agent.sh- 验证Agent文件结构test-agent-trigger.sh- 测试Agent是否正确触发
实施工作流程
为插件创建Agent的步骤:
- 定义Agent目的和触发条件
- 选择创建方法(AI辅助或手动)
- 创建
agents/agent-name.md文件 - 编写包含所有必填字段的frontmatter
- 遵循最佳实践编写系统提示词
- 在描述中包含2-4个触发示例
- 使用
scripts/validate-agent.sh验证 - 使用真实场景测试触发
- 在插件README中记录Agent
专注于清晰的触发条件和全面的系统提示词,以实现自主操作。