Skills 与子代理

这一课你将能做到

1. 创建一个符合规范的 Skill（SKILL.md + frontmatter），让 Claude 在匹配场景自动加载团队 SOP
2. 用 /agents 创建子代理（subagent），把 code review、大规模排查类任务委派到独立上下文执行
3. 判断「写进 CLAUDE.md / 做成 Skill / 交给子代理 / 用 MCP」四条路径的适用边界

为什么要学

团队里总有些重复出现的「套路」：发版前检查清单、接口设计规范、SQL 审查要点。写进每次提问？太累。全塞 CLAUDE.md？上下文爆炸。Skill 解决的正是「按需加载的知识包」：平时只占一行描述，当任务匹配时才展开完整手册。子代理解决的则是「脏活累活别污染主上下文」：让一个独立会话去翻遍十个文件、跑全套检查，只把结论带回来。两者都是 Claude Code 规模化协作的核心机制。

人话：Skill 是「按岗位发的操作手册」，平时揣兜里（只占一行），干到对应活才掏出来（全文加载）；子代理是你带的「专项实习生」，脏活他干，只向你汇报结论。

先建立图像

主会话（你的对话）
│
├─ 匹配到 Skill → 展开加载 SKILL.md 全文（像按需 import）
│
└─ Task 工具 → 启动子代理
     ├─ 独立上下文窗口（主会话历史它看不见）
     ├─ 自己读文件/跑命令（消耗自己的上下文）
     └─ 结束时只返回一份总结报告给主会话

Skill 与相关机制的分工：

机制	本质	触发方式	适合装什么
CLAUDE.md	常驻记忆	每次会话自动注入	全局命令与规范
Slash command	提示模板	你手动 /xxx 调用	固定动作（如一键 review）
Skill	按需知识包	模型按描述自动匹配	领域 SOP、操作手册
MCP	外部能力	模型按需调用工具	连接外部系统

跟着做

步骤 1：创建你的第一个 Skill

项目内建目录 .claude/skills/sql-review/，创建 SKILL.md：

---
name: sql-review
description: 审查 SQL 与 MyBatis 映射文件时使用。检查索引命中、大事务、
  N+1 查询、隐式类型转换。当任务涉及 SQL 优化、慢查询分析、mapper 文件
  变更时主动应用。
---

# SQL 审查手册

## 审查清单（按序执行）
1. WHERE 条件字段是否有索引，EXPLAIN 是否 type=ALL
2. 单条 SQL 影响行数超过 1 万的，必须分批
3. 循环内查询即 N+1，改为批量 IN 或 JOIN
4. 字符串列与数字比较的隐式转换必须显式化

## 输出格式
按 文件:行号 列出问题，每条给出改写示例。

description 是触发开关：它决定模型在什么任务下掏出这本手册，务必写清「什么时候用」。

步骤 2：验证自动触发

新会话（或 /clear 后）输入：

帮我看看 OrderMapper.xml 里这几个查询有没有性能问题

观察它应用了手册里的审查项。若未触发，说明 description 与任务措辞差异过大——这是最常见故障，见卡点急救。

步骤 3：用 /agents 创建子代理

/agents

交互界面选创建，或直接手写 .claude/agents/code-reviewer.md：

---
name: code-reviewer
description: 代码审查专家。在完成一段功能编写、或用户要求 review 时
  主动使用。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是资深 Java 评审。审查当前改动时：
1. 用 git diff 获取变更
2. 按正确性 > 安全 > 性能 > 可读性排序输出问题
3. 每条问题给文件:行号与修复建议
4. 不修改任何代码，只输出报告

步骤 4：委派与观察

用 code-reviewer 审查刚才的改动

主会话弹出 Task 工具调用 → 子代理独立运行（它自己读 diff、翻代码）→ 结束后主会话只收到报告。注意：子代理跑得再久，主会话上下文只增加报告那一段。

步骤 5：项目级与个人级

• 项目级：.claude/skills/、.claude/agents/ 进 git，全团队共享。
• 个人级：~/.claude/skills/、~/.claude/agents/，跨项目可用、不共享。

讲清楚要点

1. Skill 的核心是渐进式披露：常驻成本 = description 那几行；使用成本 = 触发时全文加载。这让它可以在不撑爆上下文的前提下装下大量 SOP。
2. description 质量 = 触发准确率：要写「触发场景 + 覆盖内容」，像写搜索引擎的描述。含糊的 description（"辅助开发"）等于没写。
3. 子代理的价值是上下文隔离：主会话保持干净（只收结论），探索的中间噪声都留在子代理里。代价是它看不到主会话历史，委派时要把背景一次说全。
4. frontmatter 可限定子代理的工具与模型：如只读类审查代理给 tools: Read, Grep, Glob（物理上改不了代码），批量机械活可指定更省的 model 档。
5. 子代理不是并发银弹：有启动开销，简单任务直接做更快。典型适用：大范围代码检索/排查、成批文件的机械修改、独立视角的审查。

你可能会懵的地方

• Skill 没有被触发怎么办？ 三查：description 是否包含任务关键词；是否新会话（已加载的旧会话不会补装）；可在指令里点名（「按 sql-review 技能审查」）强制使用。长期方案是把 description 修改到覆盖真实说法。

• Skill 和 MCP 什么关系？ 正交互补：MCP 给「能力」（能连什么系统），Skill 给「知识」（这类活怎么干好）。如：MCP 连上 Sentry（能力），Skill 写「线上故障排查 SOP」（知识），配合使用。

• 子代理能修改我的代码吗？ 能，只要它的 tools 里有 Edit/Write 且权限允许。审查类建议只给只读工具，从机制上保证「只提意见不动手」。

• /agents 建的和手写文件一样吗？ 等价，/agents 是交互式生成同样格式的 markdown 文件。团队推广时建议直接维护仓库里的 .claude/agents/ 目录，进版本库可 review。

• 自定义命令（slash command）还需要吗？ 需要。固定动作（如 /review、/deploy-check）用命令手动触发更直接；Skill 胜在「模型自己知道何时用」。一套团队工具包通常两者都有。

错法对照

错法	问题	正解
description 写「帮助开发者」	永远匹配不上	写明触发场景与关键词
把所有知识堆进 CLAUDE.md	上下文常驻膨胀	高频规范进 CLAUDE.md，专项 SOP 做 Skill
委派子代理时不给背景	它不知道目标与约束	一次说清：目标、范围、输出格式
审查子代理给了 Edit 权限	评审者顺手改码，职责混淆	只读 tools，报告交主会话决策
简单单文件小改也开子代理	启动开销大于收益	大范围/机械批量/独立评审才委派

卡点急救

1. Skill 文件不被识别：检查目录名与 frontmatter（name 必填、YAML 格式正确）；重启会话加载；路径必须是 .claude/skills/<名称>/SKILL.md。
2. 子代理跑偏/输出太长：在委派语里限定输出格式（「只列前 5 个问题」）；把大任务拆成多个子任务分别委派。
3. 团队里有人触发了有人没触发：确认所有人拉取了最新 .claude/ 目录并重启会话；版本不一致是主因。

面试常问

• Agent Skills 的设计思想是什么？ 渐进式披露（progressive disclosure）：用一行元数据常驻上下文，正文按需加载，让模型能在有限上下文里掌握海量领域知识。本质是把 prompt 工程产物工程化、版本化、可分发。

• 子代理架构解决了什么问题？ 上下文隔离与关注点分离：探索型任务的中间产物（大量文件内容、失败尝试）不污染主对话；同时为并行与专业化（不同工具集/模型档）提供结构。代价是信息传递靠「最终报告」，需明确的任务边界。

• 如何在 CLAUDE.md / Skill / MCP / 子代理之间做技术选型？ 每次会话都要知道的 → CLAUDE.md；特定任务才需要的知识 → Skill；需要连接外部系统 → MCP；需要隔离上下文或并行的大块工作 → 子代理。按「常驻 vs 按需」「知识 vs 能力」两个维度判断。

自测三问

1. Skill 的 frontmatter 里哪个字段决定触发？怎么写才有效？
2. 子代理的上下文隔离带来什么好处与限制？
3. 「接口设计规范」和「连公司 Jira 查任务」分别该用什么机制实现？

小结一句话

Skill 用按需加载把团队 SOP 装进上下文，子代理用上下文隔离把脏活累活外包出去——两者合用，是从「个人提效」迈向「团队工程化」的分水岭。

延伸

• Agent Skills 官方文档
• 下一课：Hooks 事件——用确定性的脚本在工具调用前后设卡，让规范从「约定」升级为「强制」。