Claude 代码技能：模型实际调用的 SKILL.md 文件详解

最后更新: June 28, 2026

Claude Code Skill 是一个包含 SKILL.md 文件的文件夹，当任务与它匹配时，代理才会将其拉入上下文。我创建了第一个 skill，目的是不再将相同的 200 字数据库迁移清单粘贴到每个会话中。现在，这个文件每周为我节省大约一小时的时间。

下面是简短版本，然后是实际的结构解析：什么是 skill、如何编写 SKILL.md 的 frontmatter 和正文、模型何时决定调用一个 skill，以及在什么情况下使用 skill 是过度设计（overkill）而不是简单的提示词（prompt）。如果你已经在使用 Claude Code，你可以在五分钟内发布你的第一个 skill。

快速答案：什么是 Claude Code Skill？

Skill 是一种可重用、由模型调用的能力，以 SKILL.md 的形式存储（以及可选的辅助脚本）。与总是加载的系统提示词不同，skill 是在模型决定它与你的请求相关时按需加载的。你编写一个名称、一段关于何时使用它的描述，以及正文指令。描述是最重要的字段，因为这是模型用来决定是否触发 skill 的依据。Skill 本地存储在 .claude/skills/ 或从注册表发布，因此一个团队可以分享一种规范化的执行迁移、代码审查或发布的方式。

如果你想了解更多关于 CLI 本身的内容，请参阅我的 Claude Code ultimate guide for 2026。关于 skill 如何与始终开启的子代理（sub-agents）不同，请阅读 how I automated my workflow with Claude Code sub-agents。

Skill 实际是什么？它由什么构成？

Skill 是一个目录。它所需的最小内容是一个 SKILL.md 文件。可选地，它可以捆绑脚本、模板或参考文档与 skill 一起传输。Anthropic 的 agent-skills 文档将 skill 描述为一套打包的指令和资源，模型可以在相关时加载它们（docs.anthropic.com/en/docs/agents-and-tools/agent-skills）。

我将 skill 视为模型的一个命名、版本化的子程序。使其与长提示词不同的有三点：

1. 它具有选择性（opt-in）。只有当任务似乎符合描述时，模型才会加载它。
2. 它具有范围限定（scoped）。你可以附加的文件和脚本只对该能力才有意义。
3. 它具有可分享性（shareable）。这个文件夹可以在项目和团队成员之间移植。

CLI 本身是开源的，skill 的规范也在 GitHub 上有文档记录（github.com/anthropics/claude-code），我在这里检查每次发布行为是否有变化。

如何构建 SKILL.md 文件？

该文件包含两个部分：YAML frontmatter 和 Markdown 正文。frontmatter 告诉模型何时运行；正文告诉它做什么。这是我使用的结构。

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

正文是纯 Markdown。我保留了三个部分：一个单行目标、一个编号的流程，以及一个明确的“停止并确认”门控点。name 必须与文件夹名称匹配。description 应该为模型撰写，而不是为人类撰写，所以它应该像一个触发条件一样阅读。

我直接进行了测试。最初使用“帮助处理数据库”这样模糊的描述，该 skill 会对不相关的 SQL 问题也触发。在我将其重写为“Use when the user asks to create, modify, or roll back a database migration”（当用户要求创建、修改或回滚数据库迁移时使用）之后，调用精度从大约 60% 提高到了可靠的水平。描述正在执行路由功能，所以把你的编辑时间花在上面。

何时应该将某物转化为 skill？

这是我收到的最多问题。我的规则是：如果我在两周内粘贴了相同的指令块三次以上，并且它超过了一个段落的长度，那么它就应该成为一个 skill。下面是我实际使用的决策矩阵。

第二个轴是成本。每个加载的 skill 都会向上下文增加 tokens，因此一个庞大、总是相关的指令块作为项目级别的内存或自定义命令比作为 skill 更合适。Skill 最适用于**条件相关（conditionally relevant）**的专业知识。

我编写 skill 的具体案例：我们的发布流程要求更新 changelog、递增三个版本文件、打 tag，并向 Slack 发布摘要。我将其写成了一个 skill，现在我只需说“cut a release”（进行一次发布），模型就会按顺序运行整个清单。没有使用 skill 的具体案例：对配置文件的一次性重构。那个仍然保持为 prompt。

模型调用 skill 的模式如何运作？

让 skill 感觉神奇的模式是：你不会主动调用它们。你描述工作内容，然后模型会读取所有可用 skill 的描述，并拉取匹配的那个。这记录在官方 Claude Code 文档中（docs.anthropic.com/en/docs/claude-code）。

流程如下：

1. 你用自然语言输入一个请求。
2. 模型看到每个已安装 skill 的 name 和 description。
3. 它根据你的请求评分相关性。
4. 获胜 skill 的正文（和捆绑文件）进入上下文。
5. 模型执行指令。

实际后果是：你必须像为模型撰写搜索引擎条目一样编写 description。以动词和触发范围开头。比较这两个描述：

• 弱： "A skill for handling git things." （一个用于处理 git 事务的 skill。）
• 强： "Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite." （当用户要求在当前分支上压缩、变基或拆分提交时使用。在执行任何重写之前生成交互式计划。）

后者指明了触发动词和保护范围。这使得调用变得可靠。如果你使用工具将 skill 连接起来，Claude Code MCP integration guide 介绍了外部工具服务器如何与 skill 捆绑包并存。关于连接它们的底层协议，请参阅 MCP and the model context。

如何触发和调试 skill？

触发大部分是自动的，但我有三种刻意的技术用于控制和调试。

• 明确指出。 说“use the safe-migration skill”（使用 safe-migration skill）会强制它运行。当描述模糊时非常有用。
• 列出已安装的 skills。 要求模型列出可用的 skill 及其描述。这是我确认新 skill 已注册的方式。
• 检查追踪记录（trace）。 当 skill 错误触发时，我会阅读是哪个描述匹配了，然后收紧触发措辞。

当 skill 没有触发时，原因几乎总是描述的问题，而不是文件位置的问题。我会重写第一句话，使其以“Use when...”开头，并添加具体的动词。这能解决九成以上的问题。

这是我按顺序执行的调试清单：

Skill vs 子代理 vs 斜杠命令

这三者是重叠的，人们经常混淆它们。我用一个简单的划分来区分它们。

• Skill: 模型调用的指令加可选文件。最适用于条件性专业知识。
• Sub-agent: 一个独立的 Claude Code 实例执行隔离工作。最适用于并行、长时间运行的任务。我的 sub-agent automation write-up 在此深入探讨。
• Slash command: 你故意输入的快捷命令。最适用于你总是需要按需使用的功能。

Skill 是这三者中唯一由模型选择的。这就是它们的超能力，也是它们的风险：一个描述不当的 skill 会悄无声息地浪费上下文。

如何分享 skills 和使用注册表？

skill 只是一个文件夹，所以原则上分享非常简单。我将该文件夹放入 repo 的 .claude/skills/ 下并提交。团队成员克隆时就会获得它。对于跨团队共享，社区维护着注册表，官方工具则指向公共位置。

我的实际设置：

1. 将项目特定的 skill 保存在 repo 中，进行版本控制。
2. 将个人 skill 保存在 dotfiles repo 中，并通过 symlink 链接到 .claude/skills/。
3. 在外部分享时固定 skill 版本，因为描述的更改可能会悄无声息地改变行为。

关于分享的诚实警告：skill 编码了对你技术栈的假设。一个为 Drizzle 编写的迁移 skill，如果其描述没有限定范围，在 Prisma 项目中会自信地产生错误的输出。始终在描述中说明框架和保护措施（guardrails），并在执行破坏性操作前添加“停止并确认”步骤。我是在一次共享 skill 对错误分支运行了破坏性重写后学到的教训，所以要将每个共享的 skill 都视为不可信的，直到其描述证明否则为止。

图片鸣谢

• Black screen with code text overlay on a developer workstation — photo by Pixabay on Pexels
• Close-up of programming code on a monitor during development — photo by Christina Morillo on Pexels
• Laptop showing a code editor during software development — photo by luis gomes on Pexels