agent-development

Claude Code 插件的 Agent 开发

概述

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

关键概念：

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

Agent 文件结构

完整格式

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

## When to invoke

[Two to four representative scenarios written as prose, e.g.:]
- **[Scenario name].** [What the situation looks like and what the agent should do.]
- **[Scenario name].** [Same.]

**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。这是最关键的字段 —— 只要 Agent 被注册，它就会被加载到上下文中，以便运行框架决定何时派发。

必须包含：

1. 触发条件（"Use this agent when..."）
2. 对典型触发场景的简短散文式总结
3. 指向 Agent 正文中 "When to invoke" 部分的指引，以获取详细的具体场景

格式：

Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.

最佳实践：

• 在散文式总结中列出 2-4 个触发场景
• 同时覆盖主动触发（助手自行调用）和被动触发（用户请求）
• 覆盖同一意图的不同表述方式
• 明确说明何时不应使用该 Agent
• 将详细场景放在正文的 "When to invoke" 下，以散文描述的要点列表形式呈现

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 使用一致的颜色
• 蓝色/青色：分析、审查
• 绿色：以成功为导向的任务
• 黄色：警示、验证
• 红色：关键、安全
• 洋红色：创意、生成

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]

最佳实践

✅ 应该：

• 使用第二人称（"You are..."、"You will..."）
• 明确说明职责
• 提供分步骤流程
• 定义输出格式
• 包含质量标准
• 处理边界情况
• 保持在 10,000 个字符以内

❌ 不应该：

• 使用第一人称（"I am..."、"I will..."）
• 表述含糊或过于通用
• 省略流程步骤
• 不定义输出格式
• 跳过质量指导
• 忽略错误情况

创建 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
   - A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions and a short prose summary of trigger scenarios

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
  "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 [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
model: inherit
color: blue
---

You are an agent that [does X].

## When to invoke

- **[Scenario A].** [Description.]
- **[Scenario B].** [Description.]

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

Output: [What to provide]

Frontmatter 字段摘要

字段	是否必填	格式	示例
name	是	小写-连字符	code-reviewer
description	是	散文式触发条件	Use when... Typical triggers include...
model	是	inherit/sonnet/opus/haiku	inherit
color	是	颜色名称	blue
tools	否	工具名称数组	["Read", "Grep"]

最佳实践

建议：

• ✅ 在描述中以散文形式列出 2-4 个触发场景
• ✅ 在 "When to invoke" 正文部分以散文式项目符号详述具体工作场景
• ✅ 编写具体的触发条件
• ✅ 除非有特定需求，否则模型使用 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 个触发场景，并在 "When to invoke" 正文部分详述
7. 使用 scripts/validate-agent.sh 进行校验
8. 使用真实场景测试触发
9. 在插件 README 中记录该 Agent

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