子代理和 Skills 怎么写？3 个实用例子
技术系列第 3 篇，也是收官篇。前两篇装好了"说明书"和"门锁"，这篇解决最后一个问题：当任务太多、角色太杂，主对话装不下的时候，怎么把活分出去。
一、先分清四个东西
用 Claude Code 时间长了，常见两个毛病：一是上下文越聊越满，翻过的大文件、跑过的长输出全堆在对话里，越到后面越迟钝；二是角色混杂，刚才还在写代码，转眼又要它当审查员，自己审自己，难免放水。
解法是让不同的活有不同的"容器"。先把四个容易混淆的东西摆在一起：
- CLAUDE.md：常驻的说明书，每次会话都会读
- 斜杠命令：你手动触发的提示词模板，放在
.claude/commands/*.md - 子代理：独立上下文的助手，有自己的窗口、可限定的工具
- Skills：按需自动调用的能力包，一个目录、一份 SKILL.md
子代理和 Skills 最容易讲不清。看一张图：主对话就像你本人，子代理是你请的专门助手——它有自己的工位（独立上下文），干完活只把结论带回来，过程中的细节不会挤占你的脑子。
二、例子 1：代码审查员子代理
完整文件，保存为 .claude/agents/code-reviewer.md：
---
name: code-reviewer
description: 代码审查员。在完成一个功能或修复后使用。对照改动做
质量与安全审查，按严重级别输出报告。主动使用。
tools: Read, Grep, Glob, Bash
---
你是资深代码审查员。工作方式：
1. 先运行 git diff 查看本次改动，再按需读取相关文件
2. 只审查，不修改任何文件
3. 按严重级别输出：
- 必须修复：安全漏洞、逻辑错误、数据丢失风险
- 建议：边界条件、错误处理、明显性能问题
- 可选：命名、重复代码
4. 每条注明文件和行号，没有问题就直说没有
三处值得抄：tools 只给只读工具，它想改也改不了；description 写清"什么时候用"，Claude 才会在合适的时机主动委派；"只审查不修改"写进正文，防止它顺手改代码。平时不用特意叫，改完一段代码它就可能被派来；也可以明确说"让 code-reviewer 审一遍"。
三、例子 2：测试排查员子代理
测试挂了最烦：报错一大屏，改哪儿都不确定。让专门的助手先去查，保存为 .claude/agents/test-debugger.md：
---
name: test-debugger
description: 测试失败排查员。在测试报错且原因不明时使用。负责定位
原因并给出最小修复建议。测试失败时主动使用。
tools: Read, Grep, Glob, Bash
---
你是测试排查员。流程：
1. 先运行失败的测试，复现报错
2. 用 Grep 定位相关代码，区分三种情况：
代码有 bug / 测试已过时 / 环境有问题
3. 给出最小修复建议。禁止修改测试来迁就代码；
若认为测试本身错了，说明理由，由主对话决定
4. 输出：原因 → 证据（文件:行号） → 建议的最小改动
红线只有一条：不许偷偷改测试让它们变绿。这条写进系统提示，它就只能老老实实查原因。会话里输入 /agents 能看到这两个子代理是否已经加载。
四、例子 3：release-notes 技能
技能和子代理不同：它不是一个人，而是一个目录。建 .claude/skills/release-notes/，里面放两个文件：
release-notes/
├── SKILL.md
└── template.md
SKILL.md：
---
name: release-notes
description: 把 git log 整理成发布说明。当用户要求写更新日志、
release notes、版本说明时使用。
---
# 步骤
1. 运行 git log --oneline <上一版本号>..HEAD 获取提交
2. 按模板整理；无法归类的提交放入"其他"
3. 只依据提交记录，不要推测功能细节
具体格式参考本目录下 template.md
template.md 就是你的发布说明格式：新增、修复、优化、破坏性变更四栏。
用法：对 Claude 说"根据上个版本生成发布说明"，它匹配到 description 就会读这个技能。技能的好处是渐进加载：平时只有一个 description 占着上下文，用到时才读正文和模板，比把格式规则全写进 CLAUDE.md 省得多。
五、description 决定生死
三个例子里最值钱的一行，都是 frontmatter 里的 description。它是 Claude 派活的依据：写得好，该出手时就出手；写得差，要么永远不被调用，要么动不动乱入。
四条写法：
- 写清做什么 + 什么时候用，别只写名字
- 带上触发词：用户会说"审查""排查""发布说明"，就写进去
- 写明主动使用，否则它可能只等你点名
- 有边界：写明"只做 X，不做 Y"
六、没被调用？按这个查
- description 太泛或太抽象 → 加场景和触发词
- 文件放错位置 → 子代理在
.claude/agents/，技能在.claude/skills/<名字>/SKILL.md - 好像没生效 → 新开会话再试，或用
/agents确认已加载 - 名字和内置工具冲突 → 换个更具体的名字
具体字段和加载细节以官方文档为准，版本之间可能有差异。
七、安全提醒
技能和子代理里可以写脚本、可以授权工具，等于给 Claude 加能力。用第三方的之前，把每个文件读一遍：命令能不能信任、工具权限是否最小化、有没有让你输入密钥的步骤。自己的配置也遵守最小权限：审查员只给只读工具，排查员不给写权限。
系列总结
三篇凑成一套：CLAUDE.md 是说明书，Hooks 是门锁，子代理和 Skills 是分身。从今天开始的最小路径：先写一份 20 行的 CLAUDE.md，再加一个 Stop 提醒的 hook，最后把你最常叮嘱的事变成子代理或技能。一套下来，Claude Code 才算真正"记得住事、守得住规矩、分得出去活"。
