Claude Code skills：技能如何运作，SKILL.md 是什么，智能体何时加载它

Claude Code 中的 skills 是什么

Skill（技能）是一个包含 SKILL.md 文件的文件夹，其中记录了针对某一类任务的说明：如何部署项目、如何进行代码评审、如何发布版本。从会话开始，智能体就知道这项技能的存在，但只有当任务确实需要时，才会完整读取它。

Claude Code skills 解决了一个长期维护 CLAUDE.md 的人都熟悉的问题：说明文件越来越长。一份 80 行的部署流程每周只用一次，但它会占用每个会话的上下文——哪怕只是修改 README 中的一个错别字。技能把这类流程移出常驻上下文，并在需要时再加载。

一项技能由什么组成

最简单的技能只需要一个文件夹和一个文件。项目级技能放在仓库中，个人技能放在用户的主目录下：

.claude/skills/deploy/SKILL.md      # 项目技能，通过 git 与团队共享
~/.claude/skills/review/SKILL.md    # 个人技能，适用于所有项目

在 SKILL.md 旁边可以放置辅助文件：模板、脚本、参考资料。只有当主文本引用它们，并且确实需要时，智能体才会打开这些文件：

.claude/skills/deploy/
├── SKILL.md           # 主要说明
├── checklist.md       # 详细检查清单，按链接读取
└── rollback.sh        # 回滚脚本

Frontmatter：name 与 description

文件开头是位于 --- 行之间的 YAML 代码块。最重要的两个字段是：name——技能的简短名称；description——说明该技能做什么、何时使用。

---
name: deploy
description: 通过 FTP 将网站部署到主机。在需要把修改上传到服务器、检查与服务器的差异或回滚部署时使用。
---

# 部署

1. 先做试运行：`./deploy.sh -n`。
2. 检查文件列表：其中不应包含密钥和测试脚本。
3. 上传：`./deploy.sh`。
4. 打开修改过的页面，确认它们返回 200。

回滚请参见此文件夹中的 rollback.sh。

frontmatter 下面是普通的 Markdown：步骤、命令、限制条件、指向相邻文件的链接。编写时请像给第一次做这项工作的新同事写说明一样。

智能体何时加载技能

会话开始时，上下文中只包含每个可用技能的名称和描述。每项技能只占几行，因此可以保留几十项。当用户的请求或当前步骤与描述相符时，智能体会调用该技能——只有这时，SKILL.md 的完整内容才会进入上下文。

由此得出最重要的实用规则：技能依据描述被触发。在智能体决定打开技能之前，它看不到技能正文。如果 description 写的是“辅助技能”，智能体就不知道何时需要它。如果写的是“网站部署；在需要把修改上传到服务器或回滚部署时使用”，它就会知道。

除了自动选择，还可以通过斜杠和名称显式调用技能，例如 /deploy。当您确切知道需要哪种流程，又不想依赖智能体自行把请求与描述对应起来时，这很方便。

如何编写 description 才能让技能被触发

• 做什么——用一句带动词的话概括：“部署网站”“提交前评审修改”。
• 何时使用——列出用户实际提出这类任务时的说法：“上传到服务器”“发布”“回滚”。
• 何时不使用——如果技能容易与相邻技能混淆：“仅用于网站部署，不用于部署机器人”。
• 避免“实用的技能”“有助于工作”之类的空泛表述——它们不传递任何有效信息。

渐进式披露

技能基于渐进式披露（progressive disclosure）的原则：信息分层提供，每一层只在需要时加载。

这与用一张简短的导航图代替一大篇说明文件的思路相同：简要的地图始终在手边，细节通过链接获取。不同之处在于，技能把这种按需加载变成了标准机制，而不是寄希望于智能体自己打开需要的文档。另一个优点是：第三层的脚本智能体可以直接执行，而无需把整段代码载入上下文。

Skills、CLAUDE.md 与斜杠命令的区别

这三种机制都向智能体传递说明，但加载的时机不同，对上下文的开销也不同。

选择的实用规则很简单。如果某条说明几乎每个任务都需要，它应放在 CLAUDE.md 中。如果它只在某一类任务中需要，那就是一项技能。如果您每次都要输入同一段很长的请求，那它就是做成命令或手动调用技能的候选。

不要把硬性禁令移到技能中。技能可能根本不被加载，而“绝不提交密钥”这样的规则必须始终生效。这类不变量应留在 CLAUDE.md 中，并尽可能通过机制来保证：hooks、访问权限、CI 中的检查。

如何一步步创建 Claude Code 技能

1. 找出重复出现的流程。典型信号是：您已经三次向智能体解释同一件事，或者 CLAUDE.md 中有一节只在十分之一的任务中用到。
2. 创建文件夹 .claude/skills/<名称>/，并在其中放入 SKILL.md 文件。
3. 编写 frontmatter，包含 name 与 description，并明确说明何时使用该技能。
4. 描述步骤，给出具体命令和完成标准：要检查什么，什么结果算成功。
5. 把冗长的内容移到相邻文件中，并在主文本中加以引用。
6. 从 CLAUDE.md 中删除重复内容，只留下一行指引：“部署——使用 deploy 技能”。
7. 验证：在新会话中用自己的话提出任务，不提技能名称，看智能体是否会调用它。如果没有，就改写描述。

技能示例

部署技能

典型的适用对象：流程少见、冗长且有风险，出错代价高。技能中记录了步骤顺序（先试运行，再上传）、哪些内容不能上传、如何检查结果以及如何回滚。智能体在修改代码时无需把这些都记在脑子里，只有在涉及服务器时才需要。

代码评审技能

---
name: review
description: 提交前评审当前的修改。在需要检查 diff、查找修改中的错误或为提交做准备时使用。
---

# 评审修改

1. 获取 diff：`git diff` 和 `git diff --staged`。
2. 对每个修改过的文件检查：
   - 用户输入在输出时是否经过转义；
   - SQL 查询是否使用了参数化；
   - 是否残留调试输出和临时文件。
3. 运行项目的测试和代码检查工具（命令见 CLAUDE.md）。
4. 报告：列出问题，注明文件和行号，从严重到轻微排列。
   如果没有问题，就直接说明，不要编造意见。

这样的技能把“看看一切是否正常”变成一套可重复的检查，每次检查的项目都一样。

会话收尾技能

另一种有用的类型是工作结束时的固定流程：停止本地环境，删除临时文件，在进度日志中补充已完成的内容和待办事项，然后写一条详细的提交信息。这直接解决了跨会话丢失上下文的问题：下一个会话从仓库的最新状态开始，而不是靠猜测。

常见错误

• 描述过于笼统。技能存在，但智能体从不调用它。解决办法是用具体的触发词重写 description。
• 技能写成长篇大论。把整个 400 行的旧章节搬进了 SKILL.md。上下文膨胀的问题又回来了，只是晚了一些。主文本应当简短，细节放在相邻文件中。
• 与 CLAUDE.md 重复。同一个流程写在两个地方，时间一长就会不一致。真相应当只有一个来源。
• 技能相互重叠。两个描述相似的技能，智能体会随机选择。用明确的“使用/不使用”加以区分。
• 命令过时。脚本改名了，技能却仍然指向旧名称。技能是项目代码的一部分：应与流程本身在同一次提交中修改。

如何判断某个章节是否该移入技能

可以定期浏览 CLAUDE.md，对每一节问自己：在多大比例的普通任务中真正需要它？如果几乎每次都需要，它就该待在原处。如果十个任务中只有一个需要，它就是技能的候选。

第二个信号是长度。无法在一屏内放下的章节，几乎肯定描述的是流程，而不是规则。流程在执行时完整阅读更方便，而不是在整个会话中都挂在后台。

第三个信号是重复的解释。如果您一次又一次地向智能体说明同一项任务的同样细节，就把它们写进一次技能里。一周之后看看手动修正的次数是否减少：这就是检验技能是否有效的办法。

小结

Claude Code skills 是一种把流程保存在项目旁边、又不必在每个会话中为它们付出上下文代价的方式。描述始终可见，正文按需加载，辅助文件则更晚加载。CLAUDE.md 保留项目地图和严格规则，技能则负责部署、评审、发布以及其他特定类型的任务。关于说明文件的结构与渐进式披露，我们在 harness engineering 课程中结合实践进行了讲解。