Agent Development

Claude Code 插件的 Agent 开发

概述

Agent 是可自主处理复杂多步骤任务的子进程。了解 Agent 的结构、触发条件和系统提示词设计，有助于创建强大的自主能力。

关键概念：

• Agent 用于自主工作，命令用于由用户发起的操作
• Markdown 文件格式，包含 YAML frontmatter
• 通过 description 字段和示例进行触发
• 系统提示词定义 Agent 的行为
• 可自定义模型和颜色

Agent 文件结构

完整格式

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter 字段

name（必填）

用于命名空间和调用的 Agent 标识符。

格式： 仅限小写字母、数字和连字符 长度： 3-50 个字符 模式： 必须以字母或数字开头和结尾

合适的示例：

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

不合适的示例：

• helper（过于笼统）
• -agent-（以连字符开头和结尾）
• my_agent（不允许使用下划线）
• ag（过短，不足 3 个字符）

description（必填）

定义 Claude 应在何时触发此 Agent。这是最关键的字段。

必须包含：

1. 触发条件（“在……时使用此 Agent”）
2. 多个展示用法的 <example> 块
3. 每个示例中的上下文、用户请求和助手响应
4. 解释 Agent 为何触发的 <commentary>

格式：

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

最佳实践：

• 包含 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 进行描述。

结构

标准模板：

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

最佳实践

✅ 应该：

• 使用第二人称写作（“你是……”“你将……”）
• 明确说明职责
• 提供分步流程
• 定义输出格式
• 包含质量标准
• 说明边缘情况
• 控制在 10,000 个字符以内

❌ 不应该：

• 使用第一人称写作（“我是……”“我将……”）
• 内容含糊或笼统
• 省略流程步骤
• 未定义输出格式
• 缺少质量指导
• 忽视错误情况

创建 Agent

方法 1：借助 AI 生成

使用此提示词模式（摘自 Claude Code）：

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

然后将其转换为带有 frontmatter 的 Agent 文件格式。

完整模板请参见 examples/agent-creation-prompt.md。

方法 2：手动创建

1. 选择 Agent 标识符（3-50 个字符，仅限小写字母和连字符）
2. 编写带有示例的描述
3. 选择模型（通常为 inherit）
4. 选择颜色以便进行视觉识别
5. 定义工具（如需限制访问权限）
6. 按照上述结构编写系统提示词
7. 保存为 agents/agent-name.md

验证规则

标识符验证

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

规则：

• 3-50 个字符
• 仅限小写字母、数字和连字符
• 必须以字母或数字开头和结尾
• 不得包含下划线、空格或特殊字符

描述验证

长度： 10-5,000 个字符
必须包含： 触发条件和示例
最佳长度： 200-1,000 个字符，包含 2-4 个示例

系统提示词验证

长度： 20-10,000 个字符
最佳长度： 500-3,000 个字符
结构： 清晰说明职责、流程和输出格式

Agent 组织

插件 Agent 目录

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

agents/ 中的所有 .md 文件都会被自动发现。

命名空间

Agent 会自动添加命名空间：

• 单个插件：agent-name
• 包含子目录：plugin:subdir:agent-name

测试 Agent

测试触发

创建测试场景，验证 Agent 是否能正确触发：

1. 编写包含具体触发示例的 Agent
2. 在测试中使用与示例类似的措辞
3. 检查 Claude 是否加载了该 Agent
4. 验证 Agent 是否提供预期功能

测试系统提示词

确保系统提示词完整：

1. 给 Agent 一项典型任务
2. 检查其是否遵循流程步骤
3. 验证输出格式是否正确
4. 测试提示词中提到的边界情况
5. 确认是否达到质量标准

快速参考

最简 Agent

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter 字段摘要

字段	必填	格式	示例
name	是	小写字母和连字符	code-reviewer
description	是	文本 + 示例	Use when... ...
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：

1. 定义 Agent 的用途和触发条件
2. 选择创建方式（AI 辅助或手动）
3. 创建 agents/agent-name.md 文件
4. 编写包含所有必需字段的 frontmatter
5. 按照最佳实践编写系统提示词
6. 在描述中加入 2-4 个触发示例
7. 使用 scripts/validate-agent.sh 进行验证
8. 使用真实场景测试触发情况
9. 在插件 README 中记录 Agent

重点关注清晰的触发条件和全面的系统提示词，以支持自主运行。