用 Skills 注入过程知识：SKILL.md + 渐进式披露实战

上一节我们分清了 Skills 和 MCP ——一个教方法、一个给连接。方向定了，这节就该动手了。你大概已经有这样的体感：每次让 Agent 帮你审 PR，它都漏掉同一类问题；每次让它写提交信息，格式都跟你团队的规范对不上。你不得不在 prompt 里把那套要求重复打一遍，打到第十次开始烦。

这正是 Skills 要解决的事——把"这类活该怎么做"沉淀成一个文件，Agent 以后自己会照着做，你再也不用复述。这一节带你从零写一个真能跑的 SKILL.md，并讲透它背后那套让你装 100+ 个技能也不撑爆上下文的渐进式披露机制。

这篇适合谁：已经知道 Skills 是"教方法"、但还没亲手写过 SKILL.md 的人。读完你手里会有一个能跑的技能、一份可抄模板，和一套判断"为什么我的技能没触发"的排查思路。

---

先看一个真实的 SKILL.md 长什么样

别被名字唬住。一个 Skill 的全部，就是一个叫 SKILL.md 的纯文本文件。它分两段：上面一段 YAML frontmatter 写元数据，下面一段 markdown 正文写"怎么做"。

下面是一个真能用的"审 PR 清单"技能，你现在就可以照抄：

---
name: pr-review-checklist
description: 当用户要求审查/review 一个 Pull Request、检查代码改动、或问"这个 PR 能不能合"时使用。按团队固定清单逐项过：安全、测试、命名、回滚。
---

# 审 PR 清单

你在审查一个 Pull Request。**逐项**过下面这份清单，每项给出"通过 / 有问题 / 不适用"，有问题的要指出具体文件和行号。最后给一句总结：能合 / 改完再合 / 打回。

## 1. 安全
- 有没有把密钥、token、密码硬编码进代码？
- 用户输入有没有做校验？有没有 SQL 拼接、命令拼接的注入风险？
- 新加的依赖是不是可信来源？

## 2. 测试
- 改了逻辑有没有配套测试？
- 边界情况（空值、超长、并发）覆盖了吗？
- 本地能不能跑通 `pnpm test`？（跑不了就标出来让人工补）

## 3. 命名与可读
- 函数/变量名是不是见名知意？有没有 `data2`、`tmp` 这种？
- 有没有注释掉的死代码、调试用的 console 没删？

## 4. 回滚与影响面
- 这个改动如果上线出问题，能不能一键回滚？
- 改了数据库 schema 吗？有没有迁移脚本？
- 影响到的调用方都改到了吗？

## 输出格式
先列清单逐项结论，再给一句话总结。**别客套**，直接说哪里有问题。

就这么多。没有代码、没有服务、没有配置。frontmatter 决定"这技能什么时候被想起来"，正文决定"被想起来之后怎么干活"。 把这两句记牢，下面全是细节。

---

三个层次：渐进式披露为什么装得下 100+ 个

你可能会问:我装了几十个技能,每个正文都几千字,全塞进上下文不就爆了?

答案是它们根本不会全部塞进去。Skills 的精髓叫渐进式披露(progressive disclosure),信息分三层加载,用到哪层加载哪层:

1. 第一层 · 元数据常驻:只有每个技能的 name + description(加起来大约 100 token)一直挂在上下文里。相当于书架上每本书的书脊——你一眼扫过去知道有哪些书,但没翻开任何一本。
2. 第二层 · 命中才加载正文:当 Agent 判断当前任务跟某个技能的 description 对上了,才把那个技能的完整正文(一般控制在 5k token 以内)读进来。书从架上抽下来、翻开。
3. 第三层 · bundle 文件按需才读:正文里如果引用了额外的脚本、长参考文档(放在同一个文件夹里),只有真走到那一步才去打开。书里夹的附录,要查了才翻。

算笔账你就懂了:装 100 个技能,常驻成本是 100 × 100 = 1 万 token 的"书脊"——这点开销现代模型的上下文完全扛得住。而没命中的 99 个技能,它们那几千字的正文一个字都没进上下文。

这就是为什么有经验的人敢给 Agent 装一两百个技能:没命中的技能几乎不花钱。这跟把所有说明书摊在桌上完全是两回事——更像一个塞满书的图书馆,你只为你真正翻开的书付阅读成本。

字段细节(YAML 支持哪些键、bundle 文件夹的具体约定)各家工具略有差异,以官方文档为准。但"frontmatter 触发 + 正文怎么做 + 渐进式披露三层"这套核心结构是 agentskills.io 开放标准的通用形态,跨工具一致。

---

动手:把上面那个技能跑起来

光看不练记不住。跟着做一遍,过程中我会告诉你每一步你应该看到什么——对不上就是哪里错了。

第一步:建对目录,放对文件。

技能要放在工具约定的技能目录下,每个技能单独一个文件夹,文件夹里放 SKILL.md。以 Claude Code 为例,放在 ~/.claude/skills/ 下(具体目录以官方文档为准):

mkdir -p ~/.claude/skills/pr-review-checklist
# 把上面那段内容存成 SKILL.md

你应该看到:~/.claude/skills/pr-review-checklist/SKILL.md 这个文件存在,内容就是上面那段(frontmatter + 正文)。注意是文件夹名 = 技能名,文件名固定叫 SKILL.md。

第二步:让 Agent 认出它。

重启或重载你的 Agent。多数工具会在启动时扫描技能目录,把每个 SKILL.md 的 name + description 读进元数据层。

你应该看到:在工具的技能列表里(Claude Code 可以查看已加载的 skills),出现了 pr-review-checklist。如果没出现,八成是 frontmatter 的 YAML 写错了(见下面故障表第一行)。

第三步:触发它。

正常跟 Agent 对话,说一句跟 description 对得上的话:

帮我审一下这个 PR:<贴上 diff 或给个分支>

你应该看到:Agent 不是自由发挥地随口点评,而是逐项走"安全 / 测试 / 命名 / 回滚"四栏,每项给结论、指到具体文件,最后来一句"能合 / 改完再合 / 打回"。如果它走了你清单的结构,说明技能命中并加载了正文——成了。

如果它还是自由发挥,没按你的四栏来,那就是没触发——这是新手最常撞的墙,根因几乎都在 description 上。下一节专门讲它。

---

决定成败的一行:好 description 怎么写

整个技能里,最该花心思的不是正文,是 frontmatter 里那行 description。因为它是 Agent 决定"要不要加载这个技能"的唯一依据——常驻在上下文里的只有它和 name,正文还没进来呢。description 写得糊,技能就该触发的时候不触发,白写。

一份好 description 的清单,逐条对照:

• 写清"什么时候用",不是"这是什么"。✗一个审查 PR 的技能 ✓当用户要求审查/review 一个 PR、检查代码改动、或问"这个 PR 能不能合"时使用。前者是自我介绍,后者是触发条件——Agent 要的是后者。
• 把用户真实的说法都列进去。用户可能说"审 PR"、"review 一下"、"看看这代码能不能合"、"帮我把把关"。这些同义触发词都写进 description,命中率立刻上去。
• 划清边界,避免误触发。如果你还有一个"写代码"技能,就在审查技能里点明"用于审查已有改动,不用于从零写新功能",免得两个技能抢着触发。
• 具体 + 带关键词,但别写成正文。description 是"触发说明书",不是"操作手册"。怎么做,留给正文。description 控制在一两句、几十个字最佳。
• 第三人称、动宾清楚。"当……时使用,做……"这种句式最稳,比一句名词短语强得多。

口诀:name 是文件名,description 是"何时触发"的广告语,正文才是"怎么做"的说明书。 三者各管一段,别串台。

---

进阶:给技能配 bundle 文件

正文写不下、或者有现成脚本想复用,就动用第三层。在技能文件夹里多放几个文件,正文里指路让 Agent 按需读:

~/.claude/skills/pr-review-checklist/
├── SKILL.md              ← 主文件,正文里引用下面两个
├── security-deep.md      ← 安全深查的长清单(平时不加载)
└── check_secrets.py      ← 扫密钥的脚本(要用时才跑)

正文里这样引(示意):

## 1. 安全
按上面四问快速过。如果改动涉及鉴权/加密/外部输入,
**额外**读 `security-deep.md` 走深度清单,并可运行 `check_secrets.py` 扫硬编码密钥。

好处:security-deep.md 那几千字的深度清单平时一个 token 都不占,只有真碰到鉴权改动才加载。这就是渐进式披露第三层的实战价值——把"偶尔才用的重内容"挪出常驻区。

---

可抄模板:一个万能 SKILL.md 骨架

把下面这段存下来,以后写任何技能都从它改:

---
name: 技能名-用小写连字符（= 文件夹名）
description: 当用户【做某类事/问某类问题/要某种产出】时使用。一两句话写清触发条件+同义说法，别写成操作手册。
---

# 技能标题（这类活叫什么）

一句话说清：你现在在做什么、要交付什么。

## 前提 / 输入
（这个技能开始前需要什么：一段 diff、一个文件、一份数据……）

## 步骤
1. 第一步做什么
2. 第二步做什么
3. ……（步骤要具体到能照着执行，别写"分析一下"这种空话）

## 规则 / 边界
- 必须遵守的硬规矩（格式、字数、口吻）
- 不该做的事（划清和别的技能的边界）

## 输出格式
明确交付长什么样：先列……再给一句总结。要不要表格？要不要代码块？

照这个骨架,你十分钟就能把一件"反复让 Agent 做的有套路的活"固化成技能。

---

故障排查表

现象	原因	怎么破
技能压根没出现在列表里	frontmatter 的 YAML 语法错(键冒号用了全角、缩进乱、缺 ---)	检查 name:/description: 是半角冒号、三横线包裹完整;用 YAML 校验器过一遍
技能在列表里,但该用时不触发	description 写成了"这是什么"而非"何时用",或漏了用户真实说法	改成"当用户……时使用",把同义触发词都列进去
一句话同时触发好几个技能、互相打架	多个技能 description 边界不清,关键词重叠	在各自 description 里划清"用于 X、不用于 Y"
触发了,但 Agent 没照正文走	正文写得太"虚"(全是"分析一下""注意质量"),没有可执行步骤	正文改成有序、具体的步骤 + 明确输出格式
正文太长,加载后挤占上下文	把"偶尔才用的重内容"也塞进了主正文	拆成 bundle 文件,正文里"按需才读"(第三层)
改了 SKILL.md 但不生效	Agent 启动时已读入元数据,没重载	重启/重载 Agent,让它重新扫描技能目录

---

动手挑战

1. 把上面的"审 PR 清单"技能跑通:建目录、放文件、重载、用一句话触发它,确认 Agent 真按你的四栏走。
2. 挑一件你最近重复让 Agent 做、每次都要重复交代要求的活(写提交信息、整理会议纪要、按模板写周报),用上面的骨架写成你自己的第一个技能。重点打磨那行 description。
3. 故意把 description 写糊(改成一句名词短语,比如"PR 审查工具"),再试触发,亲眼看它该触发却不触发——你就彻底记住 description 有多关键了。
4. 进阶:给你的技能加一个 bundle 文件(一段长参考或一个脚本),在正文里写"按需才读",体会第三层怎么把重内容挪出常驻区。

---

小结 · 你现在掌握了什么

• 你见过真实的 SKILL.md 长什么样:frontmatter(name/description)决定何时触发,markdown 正文写怎么做,没有代码和服务。
• 你懂了渐进式披露三层:元数据常驻(~100 token/个)→ 命中才加载正文(<5k)→ bundle 按需才读,所以装 100+ 个也不撑爆——没命中的几乎不花钱。
• 你跟着跑通了一个技能,知道每一步该看到什么,也知道"没触发"几乎都是 description 的锅。
• 你手里有了一份可抄骨架和一套好 description 清单,以后把任何"有套路的活"固化成技能都不再发怵。

具体字段和目录约定以你所用工具的官方文档为准,但这套结构是跨工具通用的。

下一步:你已经会手写技能了。更狠的玩法是让 Agent 自己写技能——干完一类活自动抽象成 SKILL.md 存进技能库,越用越强。看 Agent 自己写 Skills:拆解 hermes 的技能自学习闭环 那条线,以及 AI Agent 智能体阶梯 本级后续;想看整条路的位置就对照 三支柱路线图。

👉 看看 AI 数字员工落地指南,或了解 数字员工搭建实战课。需要为企业落地方案,欢迎找我们聊 企业服务。