Skills 入门：SKILL.md 是什么，渐进式披露怎么省 token

Skills 是把"怎么做某类活"的过程知识写成一个 SKILL.md 文件，让 AI 编程工具在需要时按需加载执行的扩展机制。

这句话乍听有点抽象，但它解决的是一个你一定踩过的坑：你教会 Claude Code 按你的风格写提交信息了，下次开新对话，它又忘了。你把团队的 PR 审查规范打进了 prompt，但它自由发挥了半张嘴。你只是想让它按你那套固定流程做一件反复出现的事，却每次都要重新交代。

这不是它不够聪明。是你把"要它怎么做"的知识放在了一个会消失的地方——对话上下文。

Skills 把这套知识存进文件，到时候自己来。

---

为什么需要 Skills：知识没法复用的痛

用 AI 编程工具一段时间之后，每个人都会遇到同一种挫败感：

有些活它会干，而且干得挺好。但"怎么干"的规矩是你这轮 prompt 里说的，下轮就没了。团队的命名规范、每种报错的处理模板、上线前的自检清单、写测试时的惯用结构……这些东西你说了一遍，它做了一次，然后下次又得从头说。

你可能尝试过把规矩写进系统提示词（CLAUDE.md）。这有用，但有个天花板：系统提示词是全局的，它不管这轮是不是在做相关的事，都一直占着上下文。 如果你把所有"活法"都写进去，它会很快变成一坨谁都不想维护的大文本，而且长期压着上下文，每轮都在消耗 token。

Skills 是另一种思路：按活分档，按需加载。

---

Skills 怎么工作：渐进式披露三层

渐进式披露（Progressive Disclosure）是 Skills 最核心的机制，讲清楚它，你才能真正理解为什么装 100+ 个不会撑爆。

信息分三层，用到哪层加载哪层：

第一层：元数据常驻（约 100 token / 个）

每个技能的 name 和 description 这两个字段，一直挂在上下文里。只有它们。这相当于书架上每本书的书脊——你扫一眼就知道架上有什么，但没有翻开任何一本书。

第二层：命中才加载正文（通常控制在 5k token 以内）

Agent 处理一个任务时，拿任务内容去匹配每个技能的 description。匹配上了，才把这个技能的完整正文加进当前上下文。相当于从书架上抽出那本书、翻开读。

第三层：bundle 文件按需才读

如果技能正文里引用了同文件夹内的脚本或附加文档，只有真正执行到那一步才会打开它们。书里夹的附录，要查了才翻。

算一笔账：你装了 80 个技能，常驻成本是 80 × 100 ≈ 8000 token 的"书脊"——这点量现代模型的上下文窗口轻松扛住。那 80 个技能里，假设这轮任务只命中了 2 个，进上下文的正文就是那 2 个的内容，剩下 78 个一个字都没进来。

这跟"把所有说明书摊在桌上"完全是两件事。更像一个图书馆：书可以很多，你只为你真正翻开的书付阅读成本。

---

SKILL.md 长什么样：最小例子

一个 Skill 就是一个文件夹里的 SKILL.md。结构固定：上面是 YAML frontmatter，写 name 和 description；下面是 markdown 正文，写"这类活具体怎么一步步做"。

下面是一个真能用的最小例子——让 Claude Code 帮你按固定格式写提交信息：

---
name: commit-message-formatter
description: 当用户要求写/生成/提交一条 git commit 信息时使用。按约定格式输出：类型(作用域): 一句话描述，不超过 72 字符，正文说明为什么改。
---

# 写提交信息

你在生成一条 git commit 信息。

## 格式规则

- 标题行：`<type>(<scope>): <描述>`，不超过 72 字符
- type 只用这几个：feat / fix / docs / style / refactor / test / chore
- scope 是改动涉及的模块，没有就省略括号
- 标题行用祈使句（"添加"而非"添加了"）
- 空一行后写正文，解释**为什么**改，不是改了什么（改了什么 diff 自己说）

## 输出

只输出 commit 信息本身，不要多余解释。如果信息不够确定 type 或 scope，问清楚再写，不要乱猜。

就这样。没有代码、没有服务、没有配置。

这个文件放进工具约定的技能目录（以 Claude Code 为例是 ~/.claude/skills/commit-message-formatter/SKILL.md），重新启动工具，以后你说"帮我写个提交信息"，它就照这个格式来——不用你每次再交代。

有几个细节值得注意：

• description 是触发的关键，不是介绍性文字。写成"当用户……时使用"的句式，把用户真实会说的话列进去。写成名词短语（"提交信息工具"）很难触发。
• 正文是说明书，不是自我介绍。只写"要干什么、怎么干"，越具体越好。"写好提交信息"这种话不如"标题行不超过 72 字符"有用。
• 文件夹名建议 = name 字段，保持一致，方便排查。

---

Skills 和 MCP 怎么选：一句话区别

你现在知道了 Skills 是"教方法"——把"怎么做某类活"的过程知识打包成文件。

MCP（Model Context Protocol） 解决的是另一件事：给 Agent 连上外部系统，让它能读写你的数据库、操作 Jira、调私有 API。

一句话记住：Skills 教用法，MCP 给连接。Skills 是学会一件事，MCP 是够得着一个地方。

实践中的优先级：先用 Skills，MCP 按需再上。

这是因为 MCP 工具定义是常驻的——接一个 server，它暴露的所有工具说明一直挂着，不管你这轮用不用得上。一套 5 个 server 开场，光工具定义就可能吃掉相当大一块上下文预算。而 Skills 的元数据只有 100 token 每个，没命中就是零成本。

大多数"让 AI 编程工具更能干"的需求，本质上是"教它一套方法"，而不是"接一个新系统"——这些都该走 Skills。只有真正绕不开外部系统的访问，才上 MCP。

关于两者更详细的对比和判断清单，见 Skills 和 MCP：两种扩展方式怎么选。

---

为什么 Skills 是日常扩展的主力

你可能有个疑问：工具本身不是已经很能干了吗，为什么还需要 Skills？

一个原因是有些活你做得比工具更专业。你团队的 PR 规范、你项目的错误处理约定、你常用的测试写法——这些是你的积累，工具没有。Skills 是你把这些积累注入工具的渠道。

另一个原因是复用。写一次，所有项目用。换了机器，把 ~/.claude/skills/ 目录复制过去，你所有的"老手直觉"就跟过来了。如果遵循 agentskills.io 这个开放标准，同一套技能还能在不同工具之间通用，不绑死某一家。

还有一个更深层的原因：它让你系统性地提升而不是反复重来。每次你发现某类活有套路、有规范，花十分钟写成 SKILL.md，下次就不用重新交代了。日积月累，工具对你项目的理解会越来越精准——这才是 AI 编程工具从"帮手"变成"老搭档"的路径。

想再进一步，可以看 上下文是一切：引用规则——那一节讲的是上下文机制的底层逻辑，懂了它你会更清楚 Skills 为什么这样设计。

---

怎么上手：最简三步

第一步：找一件你最近反复让 Claude Code 做、每次都要重新交代要求的活。比如"按某格式整理会议纪要"、"按团队规范审代码改动"。

第二步：建文件夹，放 SKILL.md：

mkdir -p ~/.claude/skills/你的技能名
# 在里面放 SKILL.md，内容参考上面的例子

第三步：重启工具，用一句自然语言触发它，确认它按你的规则来了，而不是自由发挥。

如果没触发，九成是 description 写成了"这是什么"而不是"什么时候用"——改成"当用户……时使用"的句式再试。具体排查步骤见 写第一个 Skill：一个文件夹。

---

常见问题

Q：Skills 和在 CLAUDE.md 里写规则有什么区别？

CLAUDE.md 是全局常驻的——不管这轮在做什么事，内容都在上下文里。适合放全局偏好、项目约定这类通用信息。Skills 是按活分档的，只有命中时才进上下文，适合放"这类具体活怎么做"的方法。两者互补，各有用处：CLAUDE.md 管"基本设定"，Skills 管"各项专业技能"。

Q：正文可以写多长？没有上限吗？

技术上没有强制上限，但好的实践是把正文控制在 5000 token 以内。更长的内容考虑用 bundle 文件（放进同一文件夹，正文里指路），只在真正用到时才加载。正文越短越精准，触发时加载的开销也越小。

Q：一个技能可以触发另一个技能吗？

可以在正文里引导 Agent 在某个步骤去调用另一个技能，但这是 Agent 的行为，不是 Skills 系统的硬性串联。如果你的工作流需要多步串联，技能编排：一条 Skill 串多步 那节专门讲这个。

Q：技能文件夹里除了 SKILL.md 还能放什么？

可以放脚本（.py、.sh 等）和参考文档（.md 等），这些叫 bundle 文件。在正文里指路，Agent 按需读取，它们平时不进上下文。这是渐进式披露的第三层，适合把"偶尔才用的长内容"挪出常驻区。

Q：Skills 会跟着项目走还是跟着用户走？

两者都支持。放在 ~/.claude/skills/ 是用户级，换项目照样有；放在项目根目录约定的 skills/ 文件夹下是项目级，只这个项目有。团队共享的技能可以放进仓库，人人能用，见 Skills 可以指：团队共享与 agentskills 标准。

---

小结

Skills 是 AI 编程工具日常扩展的主力路径，原理并不复杂：一个 SKILL.md 文件，frontmatter 里的 name + description 决定何时触发（常驻约 100 token），markdown 正文写怎么做（命中才加载）。渐进式披露让你能装 100+ 个技能而不爆上下文——没命中的几乎零成本。

它和 MCP 不是竞争关系：Skills 教方法，MCP 给连接；日常先用 Skills，MCP 按需上。

如果你有一件反复让工具做但每次都得重新交代的活，现在就可以花十分钟把它写成 SKILL.md。

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。