agent-identifier

Claude Code 插件的 Agent 开发

概述

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

核心概念：

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

何时使用

用户提出以下要求时，请使用此技能：

• 创建 Agent
• 添加 Agent
• 编写子 Agent
• 定义 Agent frontmatter
• 决定何时使用 description 示例
• 配置 Agent 工具、颜色或模型行为
• 设计自主 Agent 结构、触发条件或系统提示词

何时不使用

以下情况请勿使用此技能：

• 斜杠命令设计
• Hook 配置
• MCP 服务设置
• 一般性的插件布局问题（应使用 plugin-structure）

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（必填）

用于在 UI 中标识 Agent 的颜色。

选项： 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]

最佳实践

✅ 应该：

• 使用第二人称撰写（“你是……”“你将……”）
• 明确说明职责
• 提供分步流程
• 定义输出格式
• 包含质量标准
• 处理边缘情况
• 控制在 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 示例

实用脚本

script/ 中的开发工具：

• 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

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