📑 本页目录（点开跳转）
10 · 技能 Skills：把专长打包
⏱ 25 分钟 ｜ ⭐ 核心 ｜ 🔨 有可直接抄的模板
🎯 一句话
Skill = 一个装着「怎么做某类事」的文件夹，靠三层渐进式披露做到 「既能装下无限专长，又几乎不占上下文」。
📁 一、一个 Skill 长什么样
deploy-service/
├── SKILL.md ← 主文件（必须有）
├── checklist.md ← 附件：上线检查单
├── rollback.md ← 附件：回滚流程
└── verify.sh ← ⭐ 可执行脚本，让 Skill 自带"考卷"
SKILL.md 的结构：
---
name: deploy
description: 部署服务到生产环境，含上线检查单和回滚流程。
当用户要求部署、上线、发布、灰度时使用。
---
## 流程
1. 跑完整测试套件（`pytest -q`），必须全绿
2. 检查 checklist.md 里的每一项
3. 先灰度 5%，观察 10 分钟错误率
4. 无异常则全量；有异常按 rollback.md 回滚
## 验证
完成后运行 `./verify.sh`，它会检查健康检查端点和错误率。
不通过不算完成。
🪜 二、三层渐进式披露（Skills 的灵魂）
- ⏰ 会话一开始就加载【所有】Skill 的头
- 🎯 作用：让模型知道"有这么个技能存在"
- ⏰ 模型判断"这个任务用得上"时才读取
- ⏰ 正文里引用了、且确实需要时才读
💡 人话类比：像人的技能记忆—— 你「知道自己会做饭」（第 1 层常驻），真做时才回忆步骤（第 2 层）， 做到复杂步骤才翻菜谱（第 3 层）。
🔢 算一笔账
假设你有 20 个 Skill：
❌ 全部展开塞进上下文：20 × 3K = 60K token（预算没了）
✅ 三层披露：20 × 100 = 2K token 常驻
+ 用到的那 1 个展开 3K
= 5K token ⭐ 省了 92%
🔑 推论：因为第 3 层可以放任意大的文件和可执行脚本， 配合代码执行，一个 Skill 的复杂度上限是无界的——它可以装下一整套企业流程。
🔗 这是第 4 章渐进式披露最典型的应用。
🤔 为什么不能"用到时再全部加载"就好
❌ 一个诱人的想法：既然按需加载，那第1层也省掉，
真需要时再去扫描所有 Skill 不就行了？
⚠️ 问题在于：模型【不知道自己不知道什么】
如果第 1 层不常驻：
· 用户说"帮我上线一下"
· 模型不知道存在一个 deploy Skill
· 它会自己瞎编一套部署流程 💀
⭐ 所以第 1 层（那 100 token 的 description）是【不能省】的
它的作用不是提供知识，是【提供一个索引】
🔑 这个结构其实很眼熟： 常驻一个轻量索引 + 按需拉取详情 —— 这和第 11 章 RAG、和操作系统的虚拟内存、 和数据库的索引，是同一个设计模式。
💡 一旦你认出这个模式，很多设计决策就变简单了： 问自己「索引够不够让它知道该去拉什么」和「详情是不是真的只在需要时才拉」。
🧭 三、五个概念的边界（新手最容易糊）
| 概念 | 管什么 | 一句话 | 加载时机 |
|---|---|---|---|
| 提示词 | 眼前这一次 | 「这次帮我……」 | 本次 |
| CLAUDE.md / Projects | 你需要知道什么 | 持久的项目事实与参考资料 | 永远 |
| Skills | 怎么做事 | 可移植的程序性知识 | 判断相关时 |
| 子 Agent | 隔离执行 | 独立上下文 + 受限工具 | 被调用时 |
| MCP | 连接外部系统 | 数据和操作的通道 | 常驻（可延迟） |
🔑 一句话记忆：MCP 让 Agent 接入系统，Skills 教 Agent 用好那些系统。 两者互补不竞争。
🎯 一个判断表
| 你想做的事 | 用什么 |
|---|---|
| 「每次改完代码都跑 lint」 | Hook（确定性，第 5 章） |
| 「我们的部署流程是这 8 步」 | Skill |
| 「我们服务的架构是这样」 | CLAUDE.md（事实不是流程） |
| 「读一下 Jira 里的工单」 | MCP（连接系统） |
| 「深入调查这个报错，别污染主上下文」 | 子 Agent |
| 「这次帮我改个变量名」 | 提示词 |
✍️ 四、写好 Skill 的五条
① description 决定生死 ⭐
它是唯一常驻上下文的部分——写不好，这个技能永远沉睡。
# ❌ 太抽象，模型不知道什么时候用
description: 处理部署相关事务
# ✅ 说清"什么时候该想起我"，并包含用户可能说的词
description: 部署服务到生产环境，含上线检查单和回滚流程。
当用户要求部署、上线、发布、灰度、rollout 时使用。
自检：换个新会话，只说任务不提 Skill 名，看它会不会自己触发。
② 正文精简，细节下沉
正文超 5K token → 拆到附件（第 3 层）
正文放：流程骨架、关键决策点、什么时候读哪个附件
附件放：详细清单、模板、参考表、代码
③ 写流程，不写知识
| ✅ 属于 Skill | ❌ 应该放 CLAUDE.md |
|---|---|
| 「发版先跑测试，再打 tag，再推镜像」 | 「我们的服务架构是微服务」 |
| 「代码审查按这 6 条检查」 | 「这个项目用 Python 3.13」 |
| 「写周报用这个模板」 | 「团队有 8 个人」 |
判断：是动作序列还是事实？动作序列 → Skill。
④ ⭐ 让 Skill 自带验证脚本
这是最容易被忽略、价值最高的一条：
Skill 定义流程 → Agent 执行 → Skill 里的脚本验证 → 不过就继续改
↑
Skill 不只是说明书，还自带考卷
## 验证
完成后运行 `./verify.sh`。它会检查：
- 健康检查端点返回 200
- 近 5 分钟错误率 < 0.1%
- 新版本号已生效
**不通过不算完成，按输出的提示修复后重试。**
🔗 这就是第 5 章「给它一个能自己跑的验证」在 Skill 里的落地形态。
⑤ 保持可移植
Skill 应该换个项目也能用。写死的路径、特定的环境变量， 要么参数化，要么在正文里说明「使用前需要确认 X」。
🔨 五、动手：把你的一个流程做成 Skill
挑一个你重复教过 AI 三次以上的流程（发版、写周报格式、代码审查清单、数据清洗步骤……）：
| 步骤 | 做什么 |
|---|---|
| 1 | 写 SKILL.md：YAML 头 + 流程骨架 |
| 2 | 重点打磨 description——包含用户可能说的所有触发词 |
| 3 | 超过 5K 的细节拆成附件 |
| 4 | 如果流程有「怎样算做对」的标准，写成脚本附上 |
| 5 | 测试触发：换个会话，只说任务不提 Skill 名 |
第 5 步不通过的话，回去改 description——这是 90% 的 Skill 失效原因。
🕳️ 六、五个常见坑
| 坑 | 症状 | 修 |
|---|---|---|
| description 太抽象 ⭐ | Skill 从来不被触发 | 写清使用场景 + 用户会说的词 |
| 正文太长 | 一触发就吃掉几万 token | 拆附件，正文只留骨架 |
| 把事实写成 Skill | 该常驻的知识变成按需加载，模型不知道 | 事实进 CLAUDE.md |
| 没有验证 | Agent 说做完了，其实没做对 | 加 verify 脚本 |
| Skill 之间重叠 | 模型选错技能 | 边界划清，或合并 |
🩺 Skill 不触发时的排查顺序
这是 Skill 最高频的问题，按这个顺序查，五分钟能定位：
① 换个新会话，直接问它「你有哪些 skill 可用？」
→ 列不出来 = Skill 根本没被加载（路径/配置问题）
→ 列得出来 ↓
② 用【最直白】的话触发：「用 deploy skill 帮我上线」
→ 还是不用 = SKILL.md 正文有问题
→ 能用了 ↓
③ 换成用户会说的自然表述：「帮我发个版」
→ 不触发 = ⭐ description 的问题（90% 的情况在这）
④ 修 description：把用户可能说的词【都写进去】
「部署、上线、发布、发版、灰度、rollout、deploy」
💡 一个很多人不知道的技巧：description 里可以直接列同义词。 它不需要写得优雅，它需要写得能被匹配上—— 这一栏是给检索用的，不是给人读的。
⚖️ 什么时候【不该】做成 Skill
| 情况 | 为什么不该 | 该用什么 |
|---|---|---|
| 只用过一两次的流程 | 维护成本 > 收益 | 直接写在提示词里 |
| 必须每次都执行的 | Skill 是概率触发的 ⭐ | Hook（确定性） |
| 纯粹的事实/参考资料 | Skill 是"怎么做"不是"是什么" | CLAUDE.md |
| 流程每周都在变 | Skill 会立刻过期 | 先让流程稳定下来 |
🔑 第二行最重要：Skill 的触发是模型判断的，也就是概率性的。 「必须每次都发生」的东西放进 Skill，等于把确定性需求交给了一个可能不触发的机制。 🔗 这就是第 5 章那条铁律的又一次应用。
📚 延伸阅读
✅ 检查点
- 三层渐进式披露各是什么？各在什么时机加载？
- 20 个 Skill 用三层披露能省多少 token？
- 为什么说 Skill 的复杂度上限是无界的？
- Skills 和 MCP 的分工一句话？
- description 为什么是最重要的一行？怎么自检它写得好不好？
- 为什么第 1 层（那 100 token 的 description）不能省掉？这个结构还出现在哪些地方？
- 「我们的服务用 Python 3.13」该放哪？为什么？
- 「Skill 自带考卷」是什么意思？
- Skill 不触发时，排查的四个步骤是什么？90% 的问题出在哪一步？
- 什么情况下不该做成 Skill？最重要的那一条是什么？
👀 答案
- ①YAML 头（name+description，约 100 token，会话开始全部加载）②SKILL.md 正文（<5K，判断相关时才读）③附件（引用且需要时才读）。
- 20×3K=60K → 20×100 + 3K ≈ 5K，省约 92%。
- 第 3 层可以放任意大的文件和可执行脚本，配合代码执行能装下一整套企业流程。
- MCP 让 Agent 接入系统，Skills 教 Agent 用好那些系统。互补不竞争。
- 它是唯一常驻上下文的部分，决定模型会不会在对的时机想起这个技能。自检：换个新会话只说任务不提 Skill 名，看会不会自己触发。
- 因为模型不知道自己不知道什么——第 1 层不常驻的话，用户说"帮我上线"时模型根本不知道存在这个 Skill，会自己瞎编一套流程。它提供的不是知识，是索引。这个「常驻轻量索引 + 按需拉详情」的结构也出现在 RAG、操作系统虚拟内存、数据库索引里——是同一个设计模式。
- CLAUDE.md。它是事实不是动作序列——判断标准就是这个。
- Skill 里附一个验证脚本，正文规定"完成后必须运行且通过"。这样 Skill 不只是说明书，还提供了客观的完成标准，形成验证循环。
- ①新会话问"你有哪些 skill 可用"（列不出=没加载）②用最直白的话触发（还不用=正文有问题）③换成用户会说的自然表述 ④修 description。90% 的问题在第 ③ 步——description 没写用户会说的词。技巧：description 里直接列同义词，它是给检索用的不是给人读的。
- 只用过一两次的、必须每次都执行的、纯事实的、每周都在变的。最重要的是"必须每次执行"那条——Skill 的触发是模型判断的，也就是概率性的，确定性需求必须用 Hook。
🛑 可以停在这里
⚡ 走神救援
Skill=装着"怎么做事"的文件夹。三层披露：YAML头(100token常驻)→正文(<5K,判断相关才读)→附件(更按需)，20个Skill能省92% token；因第3层可放脚本，复杂度上限无界。⭐第1层不能省，因为模型不知道自己不知道什么——不常驻的话它会瞎编一套流程；这个「常驻轻量索引+按需拉详情」的模式和 RAG、虚拟内存、数据库索引是同一个。五概念边界：提示词管这次/CLAUDE.md管事实/Skills管动作序列/子Agent管隔离/MCP管连接——MCP接入系统，Skills教怎么用好。五条写法：description决定生死（写清触发词，自检=换会话看能否自动触发）、正文精简细节下沉、写流程不写知识、自带验证脚本(Skill=说明书+考卷)、保持可移植。⭐不触发时的排查顺序：问它有哪些skill(列不出=没加载)→用最直白的话触发(还不用=正文问题)→换自然表述→90%的问题是description没写用户会说的词（技巧：直接列同义词，那一栏是给检索用的不是给人读的）。⚠️什么时候别用Skill：必须每次执行的用Hook——Skill的触发是概率性的。
下一节 👉 11-检索与RAG.md