Claude Code Agent 开发规范 agent-identifier 怎么写出一个合格的 Subagent

Claude Code 的”灵魂设计”——教你写一个真正能自主干活的 Agent

最近在玩 Claude Code 的插件开发，发现了一个被很多人忽略但巨重要的 Skill——agent-identifier。它是 Anthropic 官方出的 Agent 开发规范，堪称 Subagent 的”设计手册”。今天给大家拆解一下，怎么用它写出真正靠谱的子 Agent。

它解决什么问题？

很多人在 Claude Code 里创建 Agent 时会遇到这些问题：触发时机不对（该触发的时候不触发，不该触发的时候乱触发）、Agent 之间职责不清、输出格式混乱……这些问题本质上是缺少一套规范的 Agent 定义格式。

agent-identifier 就是来解决这个的。它把 Agent 的定义拆成两部分：YAML frontmatter（元数据）和System Prompt（系统指令），格式清晰得像写代码一样。

核心结构长这样

先看 frontmatter 的关键字段：

• name：Agent 名字，必须小写+连字符，比如 code-reviewer、test-generator
• description：触发条件，这是最最关键的字段！要写清楚”什么时候该调用我”，并附 2-4 个 <example> 示例
• model：用什么模型，推荐 inherit（继承父级），除非这个 Agent 有特殊模型需求
• color：UI 里显示的颜色，蓝色分析、绿色成功、红色安全
• tools：权限控制，比如只读分析用 ["Read", "Grep", "Glob"]

description 才是灵魂

很多人随便写 description，这是最大的误区。官方要求 description 必须包含：

• 触发条件（”Use this agent when…”）
• 2-4 个具体示例，展示在什么场景下 Claude 应该激活这个 Agent
• 每个示例要有 Context、user 请求、assistant 响应，以及 <commentary> 解释为什么这个 Agent 适合这个场景

举个例子：

Use this agent when user asks to review code changes. Examples: <example> Context: Developer submitted a PR user: "请 review 这个 PR" assistant: "我来启动代码审查 Agent" <commentary> This is a clear code review request </commentary> </example>

System Prompt 怎么写

Body 部分是你的 Agent 的”灵魂”。推荐结构：

• 角色定义：你是谁，你的专业领域
• 核心职责：用编号列表列出主要任务
• 分析流程：处理任务的步骤（1、2、3……）
• 输出格式：你返回的内容要是什么结构
• 质量标准：做得好与不好的判断依据
• 边界情况：遇到特殊 case 怎么处理

最佳实践

• description 里的示例要覆盖不同表达方式，同一个意图用不同说法
• 工具权限遵循”最小权限原则”——只给 Agent 必须的工具
• System Prompt 长度控制在 500-3000 字符，太多会干扰，太少会不够用
• 创建完成后用官方脚本 validate-agent.sh 验证格式

总结

agent-identifier 这个 Skill 本质上是一套 Agent 开发的最佳实践规范。它告诉我们：好的 Subagent 不是随便写个 system prompt 就完事了，而是要从触发条件、示例、工具权限、输出格式等多个维度精心设计。

如果你在用 Claude Code 或者开发 Agent 系统，这个 Skill 值得认真研究一下。

GitHub 仓库链接

GitHub: https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills/agent-development