Skill 的本质：为什么一个 Markdown 文件能改变 AI 的行为？

这是「Claude Code Skills 完全指南」系列的第一篇。本系列共 10 篇，构成一套完整的知识体系。

写在前面

你大概率已经听说了 Claude Code Skills。也许你已经安装了几个。也许你在终端里输入 /frontend-design，看到 Claude 的输出确实变了，感到了一丝惊喜。

然后呢？

你不知道它为什么变了。你不知道它是怎么变的。你不知道如果它没有生效，该从哪里排查。你甚至不确定——那些你安装但从没用过的 Skills，是不是正在拖慢 Claude 的表现。

这些问题的答案，都藏在一个最基础的问题里：

一个 Markdown 文件，到底是如何改变一个 AI 模型的行为的？

理解这件事，是你构建、选择、调试所有 Skill 的起点。不理解它，后面的一切——Description 设计、模式选择、编排架构——都是在沙子上盖楼。

一、Skill 到底是什么？—— 最精确的定义

先清除一些常见的误解。

Skill 不是插件。它不是一段可以独立运行的程序。它不会给 Claude 添加新的"能力"，就像你不能通过给一个人念一段说明书让他突然会弹钢琴一样。

那它是什么？

Skill 本质上是结构化文档——Markdown 文件——教会 Claude Code 如何执行特定的业务操作。当你说出一句话，Claude 识别意图，加载对应的 Skill，然后按照其中的多步骤工作流来完成任务。

用一位技术分析者的话说得更直白：Skills 就是文字提示词。经过精心组织的文字提示词——但本质上还是文字提示词。

这听起来似乎平平无奇。但恰恰是这种"平平无奇"中藏着深刻的设计智慧。要理解这一点，我们需要先搞清楚 Skill 的物理结构。

一个 Skill 的完整形态

每个 Skill 是一个包含 SKILL.md 作为入口点的目录。它可以包含可选的支持文件——供 Claude 填充的模板、展示预期格式的示例输出、Claude 可以执行的脚本，或详细的参考文档。

一个典型的 Skill 目录长这样：

text

my-skill/
├── SKILL.md           # 主指令文件（必需）
├── templates/         # 模板文件
│   └── report.md
├── references/        # 参考资料
│   └── style-guide.md
├── examples/          # 示例输出
│   └── sample.md
└── scripts/           # 可执行脚本
    └── validate.sh

而 SKILL.md 自身由两部分组成：YAML frontmatter（在 --- 标记之间），告诉 Claude 什么时候使用该 Skill；以及 Markdown 正文，提供 Claude 在 Skill 被调用时遵循的指令。

一个最简示例：

YAML

---
name: explain-code
description: Explains code with visual diagrams and analogies.
  Use when explaining how code works, teaching about a codebase,
  or when the user asks "how does this work?"
---

Markdown

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

name 字段成为 /slash-command（输入 /explain-code 即可手动触发），description 帮助 Claude 决定何时自动加载它。

就是这样。没有 API 注册，没有编译步骤，没有运行时，没有依赖管理。一个文件夹，一个 Markdown 文件，放在正确的位置，就是一个完整的 Skill。

这引出了本文最核心的问题：如此简单的结构，凭什么能产生如此显著的行为改变？

二、核心原理：渐进式披露

2.1 为什么不能一次性把所有知识塞给 Claude？

在解释 Skill 怎么工作之前，我们需要先理解 Skill 被设计出来要解决的那个问题。

Agent 的上下文窗口空间不是免费的，填满它会带来复合成本。上下文窗口中的每一个 token 都从三个方面消耗你的资源：实际成本——显而易见的，你在按 token 付费，无论是直接的 API 使用还是间接的额度消耗；延迟——更多输入 token 意味着更慢的响应，这在注意力机制下扩展性很差；质量——最后，长上下文窗口还会导致质量下降。

这是一个你必须刻在脑子里的公式：信息越多 ≠ 效果越好。相反，无关信息是一种主动的伤害。

在其他条件相同的情况下，当上下文窗口充满聚焦、相关的内容（包括示例、相关文件、工具调用和工具结果）时，LLM 在任务上的表现会更好，远好于上下文窗口中有大量无关内容的情况。

一个不那么抽象的说法：对 Claude Code 的系统提示分析表明，它包含大约 50 条独立指令。根据你使用的模型不同，这已经占据了 agent 可靠遵循的指令总量的近三分之一——而这还是在加入 rules、plugins、skills 或用户消息之前。

也就是说，Claude 能同时"记住"和"遵循"的指令数量是有限的。每多一条无关指令，都在稀释它对真正重要的指令的关注。

这就是 Skill 的设计出发点：不是给 Claude 更多信息，而是在正确的时间给它正确的信息。

2.2 三级加载模型

构建 Skills 最重要的概念是渐进式披露（Progressive Disclosure）——只展示足够的信息帮助 Agent 决定下一步做什么，然后在它们需要时再揭示更多细节。

具体来说，Skills 通过三个层级渐进式加载上下文：Skill 摘要（元数据）、正文（详细指令）和引用文件（补充上下文），每个层级只在被需要时才触发。

让我画一张图来说清楚这三个层级：

text

┌─────────────────────────────────────────────────────────────┐
│                    第 1 级：元数据                             │
│                                                              │
│  始终加载 · 约 100 token · 所有 Skill 的 name + description   │
│                                                              │
│  作用：Claude 在每次会话开始时扫描这些元数据，                    │
│        用它们来判断哪些 Skill 与当前任务相关                     │
├─────────────────────────────────────────────────────────────┤
│                    第 2 级：完整指令                            │
│                                                              │
│  按需加载 · < 5,000 token · SKILL.md 的 Markdown 正文         │
│                                                              │
│  作用：当 Claude 判断某个 Skill 相关时，才读取完整指令            │
├─────────────────────────────────────────────────────────────┤
│                    第 3 级：支持文件                            │
│                                                              │
│  按需加载 · 大小不限 · 脚本、模板、参考文档                      │
│                                                              │
│  作用：只有当 SKILL.md 中的指令明确引用时，                      │
│        Claude 才会读取这些文件                                  │
└─────────────────────────────────────────────────────────────┘

这种渐进式披露架构非常高效：元数据加载阶段（约 100 token），Claude 扫描可用 Skills 以识别相关匹配；完整指令（< 5,000 token）仅在 Claude 判定该 Skill 适用时才加载；捆绑的资源和文件只在需要时加载。这种设计允许多个 Skills 同时可用而不会压垮 Claude 的上下文窗口。

用 Anthropic 官方的比喻来说：Claude 像你翻阅一本入职指南一样浏览你的 Skill，精确地获取每个任务所需的部分。

2.3 一个完整的加载过程演示

以一个 PDF 处理 Skill 为例，完整的加载过程如下：启动阶段，系统提示中包含简要信息："PDF Processing - Extract text and tables from PDF files, fill forms, merge documents"。用户请求："Extract the text from this PDF and summarize it"。Claude 调用：读取 SKILL.md，完整指令加载到上下文中。Claude 判断：表单填充不需要，所以 FORMS.md 不被读取。Claude 执行：使用 SKILL.md 中的指令完成任务。

注意那个关键细节：当用户询问关于营收的问题时，Claude 读取 SKILL.md，看到对 reference/finance.md 的引用，然后调用 bash 去读取那个文件。sales.md 和 product.md 留在文件系统上，消耗零上下文 token。

零上下文 token——这就是渐进式披露的核心价值。你可以安装 30 个 Skill，但如果当前任务只涉及 1 个，另外 29 个的完整指令和支持文件完全不会占用你宝贵的上下文空间。

2.4 关键设计含义

这种架构导致了一个被大多数人忽略的事实：

你的 Skill 能否被使用，完全取决于第 1 级——那大约 100 个 token 的 name 和 description。

这也意味着你的 description 承担了发现环节的全部重任。如果它很模糊，比如"helps with documents"，Claude 就不知道什么时候该调用它。要写得具体："Use when working with PDF files and need to extract text and tables." 默认情况下，Claude 自主决定何时使用一个 Skill，基于任务内容和 Skill 的 description。

Description 的写法将是本系列第 2 篇的完整主题。但现在你只需要记住一件事：description 不是给人读的说明，它是给模型读的触发器。

三、Skill 如何在底层改变 Claude 的行为？

理解了三级加载模型，接下来我们需要深入更底层的机制：Skill 的指令到底是如何被"注入"到 Claude 的行为中的？

3.1 上下文注入：一种精心设计的"欺骗"

Skill 选择机制在代码层面没有算法路由或意图分类。Claude Code 不使用 embedding、分类器或模式匹配来决定调用哪个 Skill。相反，系统将所有可用 Skills 格式化为文本描述，嵌入 Skill 工具的提示中，让 Claude 的语言模型自行做决定。这是纯 LLM 推理。没有正则表达式，没有关键词匹配，没有基于 ML 的意图检测。决策发生在 Claude 的 transformer 前向传播过程中，不是在应用代码里。

当 Claude 决定使用某个 Skill 后：

系统遵循一个简单的工作流：加载一个 Markdown 文件（SKILL.md），将其展开为详细指令，作为新的用户消息注入到对话上下文中，修改执行环境（可用工具、模型选择），然后在这个丰富的环境中继续对话。

这里有一个极其重要的细节：Skill 的指令被注入为"用户消息"。

这意味着，从 Claude 的"视角"来看，它就像突然收到了一条来自用户的、非常详细和专业的请求，告诉它应该按照什么步骤、什么标准、什么格式来完成接下来的工作。模型并不"知道"这是一个 Skill——它只是在处理一段高质量的、高度结构化的上下文信息。

3.2 这就是为什么"过程"和"知识"必须分开

理解了注入机制，就能理解一条关键的 Skill 设计原则：

良好结构化的 Claude Code Skill 的基本原则是将"做什么"和"知道什么"分离。过程（Process）= Claude 应该遵循的有序步骤来完成任务——这属于 SKILL.md。上下文（Context）= Claude 正确执行这些步骤所需的背景信息、规则、领域知识、示例和参考数据——这属于 reference 文件。

为什么非要分开？

因为当 SKILL.md 专注于过程时，Claude 确切地知道该如何处理它。但当它同时充当知识库时，模型必须自行判断哪些部分是指令、哪些是背景——而它并不总能做出正确判断。

这是一条反直觉但极其实用的规则：SKILL.md 要写得像食谱，不像百科全书。

食谱告诉你"第一步打鸡蛋，第二步加面粉"——这是过程。关于面粉的品种、鸡蛋的营养成分、烤箱的工作原理——这些知识放在别处，只在需要时查阅。

3.3 也解释了为什么有些 Skill "没什么用"

理解了上述原理，你就能理解一个重要的实验结果。

Vercel 的测评显示，一个压缩到 8KB 的文档索引直接嵌入 AGENTS.md（即始终加载到上下文中），实现了 100% 的通过率，而 Skills 即使在明确指示 agent 使用它们的情况下，也最高只达到 79%。没有那些指示时，Skills 的表现与完全没有文档时一模一样。

更具体地说：在 56% 的使用默认 Skill 配置的评测场景中，agent 根本没有调用 Next.js 文档 Skill。Agent 拥有获取信息的途径，却选择了不使用。结果是 53% 的通过率，与基线完全一致。

这说明了什么？

这与大量关于 LLM 校准的研究一致——模型系统性地高估了自己的知识。

换句话说：Claude 倾向于认为自己已经知道答案，所以不去查阅 Skill。 这不是 Skill 的 bug，这是 LLM 的本性。

但这并不意味着 Skills 没有价值。它意味着你需要理解 Skills 真正擅长什么。

四、Skill 真正的价值：两种类型，两种用法

Anthropic 在今年三月更新了官方指南，首次明确将 Skills 分为两类。这个分类框架是理解"什么时候该用 Skill、什么时候不该用"的关键。

4.1 能力提升型 Skill（Capability Uplift）

能力提升型 Skill 帮助 Claude 做一些基础模型要么做不到、要么做不一致的事。Anthropic 的文档创建 Skills 就是好例子。它们编码了某些技术和模式，使输出质量优于单纯的提示。

典型场景：精确的 PDF 文本定位、特定格式的图表生成、需要遵循严格规范的代码生成。

但这类 Skill 有一个重要特性：能力提升型 Skill 可能随着模型改进而变得不那么必要。Evals（评测）会告诉你那一天何时到来。

4.2 编码偏好型 Skill（Encoded Preference）

编码偏好型 Skill 记录的是 Claude 本身已经能做每一步的工作流，但 Skill 按照你团队的流程将它们串联起来。例如：一个按照设定标准审查 NDA 的 Skill，或一个从各个 MCP 拉取数据来起草周报的 Skill。

编码偏好型 Skill 更持久，但其价值取决于它对你实际工作流的忠实程度。Evals 验证的就是这种忠实度

4.3 为什么这个区分很重要？

因为 Vercel 那个"Skills 不如 AGENTS.md"的实验，测试的恰好是第一类——参考知识检索：API 语法、函数签名、特定框架版本的使用模式。测评评估的是参考知识检索——agent 需要知道特定框架版本的 API 语法、函数签名和使用模式。这类信息是事实性的、静态的、体积小——恰好是压缩性好、适合常驻上下文的知识。

但 Skills 真正闪光的场景是第二类——编排你的工作流。

五、真实案例：有 Skill 和无 Skill 的鸿沟

案例 1：LangChain 的内部评测——82% vs 9%

在 LangChain 的内部评测中，Claude Code 搭配 Skills 完成任务的成功率为 82%，但没有 Skills 时，成功率骤降至 9%。

这不是 26 个百分点的差距（像 Vercel 的测试那样），而是 73 个百分点的鸿沟。为什么？

因为 LangChain 测试的不是"Claude 是否知道某个 API"，而是"Claude 能否按照正确的步骤完成一个完整的工作流"。这正是编码偏好型 Skill 的主场。

在评测中，他们追踪的指标包括：Skill 是否被调用了？Skill 不相关时是否没被调用？Agent 是否完成了任务？一个任务可能涉及多个步骤，跟踪完成步骤数有助于区分"完全失败"和"差一点就成功"。Claude Code 完成任务用了多少轮？即使 Claude Code 不用 Skills 也能完成任务，使用 Skills 可能提高效率。Claude Code 用了多长的真实时间？

案例 2：一家真实公司用 Skills 运行整个业务

一位创始人已经在 8 个并行 worktree 中用 Claude Code 构建和发布软件。他让整个公司的运营都在 Claude Code 中完成。当他说"给我们的 alpha 用户起草一封邮件"，Claude 识别意图，加载 co-comms Skill，然后按照多步骤工作流执行：检测发件人（通过 git config）、加载发件人的声音配置、拉取发给同一收件人的历史邮件用于语调校准、起草消息、保存到磁盘、等待明确审批后才发送。

纯 Skills。没有 agent 编排其他 agent。没有工作流引擎。没有任务队列。

每个 Skill 是一个包含七个部分模板的单独 Markdown 文件：frontmatter、使用时机、上下文、流程、输出格式、护栏，以及一个无需外部系统连接即可工作的独立模式。

整个系统大约 2,000 行 Markdown，分布在 12 个 Skill 文件、5 个命令、2 个 agent 和少量规则中。它通过 MCP 服务器连接 8 个外部系统——Linear、Gmail、Google Calendar、Help Scout、Notion、Sentry、Stripe 和 Granola。数据库只用了 4 张表。

2,000 行 Markdown 运行一家公司。这就是 Skill 的力量——不在于技术的复杂性，而在于将人类工作流精确地编码为 AI 可执行的指令。

案例 3：安全审查——Skill 让输出从"不可预测"变为"结构化可靠"

一位 WooCommerce 插件开发者构建了一个安全审查 Skill。他的动机：Claude 的基线安全审查"感觉……不一致"。有时非常彻底，有时只是走过场。没有可预测的结构。这是一个完美的 Skill 候选场景。

他用 A/B 评测（Skill vs 基线 Claude）进行量化测试后发现：基线 Claude 达到 90.5%——遗漏了结构化的通过检查部分和一些 WooCommerce 特有的细微之处。而且，尽管 Skill 版本更加彻底，实际上还更快。

关键洞察：Skill 的价值不只是"做对了没有"，更是"每次都以同样的方式做对"。这正是编码偏好型 Skill 的核心价值——一致性。

六、常见误区

误区 1：「Skill 就是高级版提示词，我直接在 CLAUDE.md 里写不是一样吗？」

不一样，原因有三：

第一，加载时机不同。 CLAUDE.md 进入每一个会话，所以你必须确保其内容尽可能普遍适用。而 Skill 只在相关时加载。如果你在 CLAUDE.md 里塞了数据库建模指南，它会在你做前端工作时分散 Claude 的注意力。

第二，结构化程度不同。 Skill 有独立的目录来存放模板、脚本、参考文档、示例。Skills 添加了可选特性：一个存放支持文件的目录，通过 frontmatter 控制是你还是 Claude 来调用它们，以及 Claude 在相关时自动加载它们的能力。Claude Code Skills 遵循 Agent Skills 开放标准，可跨多个 AI 工具使用。

第三，可测试性不同。 Anthropic 推出了基准测试模式，使用你的评测来运行标准化评估。这可以在模型更新后或你迭代 Skill 本身时运行。它追踪评测通过率、耗时和 token 用量。CLAUDE.md 里的一段话很难做 A/B 测试，但一个 Skill 可以。

误区 2：「装得越多越好」

回忆第 2 节的原理：元数据层虽然只有约 100 token/Skill，但 你的 CLAUDE.md 应该包含尽可能少的指令——理想情况下只包括对你的任务普遍适用的指令。同理，30 个 Skill 的元数据就是 3,000 token 的系统提示膨胀。更重要的是——

在详细的构建/Lint/测试分项数据中，Skill 在某些指标上实际表现不如基线（测试通过率 58% vs 63%），这说明环境中未使用的 Skill 可能引入噪音或干扰。

未使用的 Skill 不是免费的。它可能让 Claude 表现更差。

误区 3：「Skill 写好就完事了」

一位开发者坦言：几个月来，他一直在用一种只能称为"hope and pray"的方法论来构建 Claude Code Skills。写好 SKILL.md。测试一次。发布。向 LLM 之神低声祈祷。然后继续过日子。Skill 真的在该触发时触发了吗？¯_(ツ)_/¯。它真的让 Claude 的输出变好了吗？说实话……不知道。

这引出了 Skill 开发中最重要的实践——而大多数人完全跳过了它。

七、你今天就应该做的 3 件事

Anthropic 官方的最佳实践文档中有一条看似简单、实则颠覆大多数人工作流的建议：

在写大量文档之前，先创建评测。 这确保你的 Skill 解决的是真实问题而非想象的问题。具体步骤：识别差距——在没有 Skill 的情况下让 Claude 跑代表性任务，记录具体的失败或缺失的上下文；创建评测——构建三个测试这些差距的场景；建立基线——度量没有 Skill 时 Claude 的表现；写最少的指令——创建刚好足够弥补差距和通过评测的内容；迭代——执行评测，与基线对比，精炼。

基于这条原则和本文的所有分析，这是你的行动清单：

✅ 行动 1：理解你已有的 Skill

打开你安装的任何一个 Skill 的目录。找到 SKILL.md。分别阅读 frontmatter（那大约 100 token 的元数据）和 Markdown 正文（那不超过 5,000 token 的指令）。问自己：

• 这个 Skill 是能力提升型还是编码偏好型？
• description 写的是给人看的摘要，还是给模型看的触发器？
• SKILL.md 里是纯过程（步骤），还是过程和知识混在一起？

✅ 行动 2：做一次 Before/After 对比

选一个你常用的 Skill。对同一个任务，分别在有 Skill 和无 Skill 的情况下运行。截图对比输出差异。如果差异不明显——恭喜你发现了一个需要删除的 Skill。

Anthropic 的建议：不要投机性地编写 Skill。在你有真实的、重复的任务时才构建它们。最好的 Skill 解决的是你经常遇到的问题。在创建一个 Skill 之前，问：我是否已经做了这个任务至少 5 次？我还会再做至少 10 次吗？如果两个答案都是"是"，那一个 Skill 就有意义。

✅ 行动 3：清理你的 Skill 库

列出你当前安装的所有 Skills。对每一个问：

1. 我能否说出它最近一次被触发的时间？
2. 它有没有经过 Before/After 对比测试？
3. 它解决的问题，我是否每周都遇到？

如果三个问题中任何一个的答案是"否"，认真考虑卸载它。记住：未使用的 Skill 留在环境中可能引入噪音，不如保持系统干净。

八、本文的知识框架总结

text

Skill 的本质
│
├── 物理结构
│   └── 一个目录 + SKILL.md（frontmatter + markdown 正文）+ 可选支持文件
│
├── 工作原理
│   ├── 渐进式披露：三级加载（元数据 → 指令 → 支持文件）
│   ├── 上下文注入：Skill 指令作为用户消息注入对话
│   └── 路由机制：纯 LLM 推理，无算法路由
│
├── 两种类型
│   ├── 能力提升型：教 Claude 做它做不好的事（可能随模型进步而过时）
│   └── 编码偏好型：编排 Claude 已会的步骤（持久但需要保持忠实度）
│
├── 核心价值
│   ├── 不是"更多信息"→ 是"正确时间的正确信息"
│   ├── 不是"让 Claude 更聪明"→ 是"让 Claude 更一致"
│   └── 不是"一次性指令"→ 是"可版本化、可测试、可组合的知识单元"
│
└── 关键约束
    ├── description 承担全部发现职责（约 100 token 决定生死）
    ├── 未使用的 Skill 不是免费的（可能引入噪音）
    └── 写完不是终点（需要评测和迭代）

下一篇预告

理解了 Skill 的本质后，我们面对的第一个实战问题是：为什么你精心编写的 Skill 不触发？

第 2 篇将深入 description 字段的设计科学。我会展示一个基于真实测试的完整框架，告诉你如何写出让 Claude 准确识别的 description——以及为什么大多数人写的 description 本质上是写给自己看的，而不是写给模型看的。

本文是「Claude Code Skills 完全指南」系列的第 1 篇，共 10 篇。全系列目录：