Claude Code 子 Agent 怎么写才对？官方 Skill 一次讲透

想让 Claude Code 调用子 Agent，但你不知道从哪下手？

最近翻到一个官方 Skill——agent-identifier，专门教你怎么正确写一个 Claude Code Agent 的配置文件。看完感觉把我之前踩的坑全对上了。

核心就一张 YAML frontmatter + 系统提示词

Agent 本质是一个 .md 文件，前半段是 YAML 元数据，后半段是系统提示词。结构长这样：

---
name: my-agent
description: Use this agent when [触发条件]. Examples: <example>...</example>
model: inherit
color: blue
tools: ["Read", "Write", "Bash"]
---
You are [角色描述]...

看起来简单，但有几个地方特别容易出错。

description 是整件事的关键

很多人把 description 写成一句话，这基本等于无效触发。官方要求 description 必须包含：

• 触发条件：「当用户说……时调用此 Agent」
• 至少 2 个 <example> 块，每个块里要有 Context + user + assistant 的完整对话示例
• <commentary> 解释，说明为什么这个场景适合用这个 Agent

说白了，description 就是在训练 Claude 什么时候该「激活」这个子 Agent。写得越具体，触发越准。

color 不是随便选的

这个细节我之前完全忽略了。官方有配色规范：

• Blue/Cyan：分析、审查类任务
• Green：成功导向的生产任务
• Yellow：校验、验证类
• Red：安全、关键操作
• Magenta：创意、生成类

同一插件里不同 Agent 尽量用不同颜色，方便在 UI 里一眼辨认。

系统提示词的万能模板

You are [角色].
**Your Core Responsibilities:**
1. [主要职责]
2. [次要职责]
**Analysis Process:**
1. [步骤一]
2. [步骤二]
**Output Format:**
- [输出结构]
**Edge Cases:**
- [边界情况处理]

写的时候用第二人称「You are…」，不要用「I am…」。另外系统提示词长度建议 500-3000 字符，太短说不清楚，太长 Claude 容易忽略重点。

怎么安装

npx skills add anthropics/agent-identifier

官方 Skill，带 65k stars 的 claude-code 背书，40 次安装验证过。

GitHub 仓库：https://github.com/anthropics/claude-code
Agent 文件路径：agents/agent-identifier/

GitHub: https://github.com/anthropics/claude-code