Agent Skills 与 SKILL.md：实测渐进式披露

第 14 章为本课程后半部分定下规则——连接、重试和取消都用 TypeScript——并声明了五个例外。本章就是其中之一，原因不是偏好。

skill 是一个 Markdown 文件。 不是配置程序的文件，也不是被程序编译的文件：它是模型会去阅读的文档，就像它阅读你输入的消息一样。给本章指定一门编程语言，就意味着没有理解这种格式，而这种误解正是关于 skills 最常见的一种。下面的内容全是 Markdown 和 YAML，外加一个很小的 shell 脚本；这个脚本存在的目的，恰恰是展示代码在 skill 里应该放在哪里、不应该放在哪里。

这里有一条真实指令：某家公司如何撰写发布说明。这是一套流程，不是偏好——它有有序步骤、分类法、语气、模板，以及一个收集原始材料的脚本。

像大多数团队那样，把所有内容都塞进 system prompt，第 16 章的算术就会接管。system prompt 是前缀，而前缀在每一次调用里都要付费。用 o200k_base 测量本章所写的文件夹：

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

使用时便宜 24 倍，不使用时便宜 37 倍。费率沿用第 16 章：每百万输入 token $2.00。

现在说诚实的反驳，因为跳过它的章节就会变成广告。prompt caching 基本抹平了金钱差距。 system prompt 是稳定的，而且位于最前面，这使它成为最理想的缓存候选；按缓存输入每百万 $0.20 计算，同样的 68,640 个 token 成本是 $0.0168，而不是 $0.1373。仍然是 skill 的三倍，但不再是数量级差异。

金钱从来不是最强的论点。真正的论点是这个：

缓存会让永久前缀更便宜。它不会让前缀更小。

到第 40 轮时，system-prompt 版本仍然有 1,716 个 token 的发布说明策略待在窗口里，即使对话主题已经完全是别的事；它仍在争夺 第 24 章所说的模型 attention 预算。skill 版本只有 46 个。缓存错了东西，你买到的只是对干扰项的折扣。

写成公式，令 $n$ 为轮数，$L_1$ 为元数据，$L_2$ 为正文，$L_3$ 为整个包，$R$ 为实际读取的打包文件集合：

本章全部内容，就是第二项乘以 $n$，与把它乘以一或零之间的区别。

skill 是一个目录。规范短到可以完整写出来：

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md 必须以 YAML frontmatter 开头，并且正好有两个必填字段：name 和 description。¹ 还有四个可选字段，并且没有定义其他字段：

下面是完整的 release-notes skill，正文不到三十行：

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

读一下那段正文是什么。它不是策略——它是一个带操作顺序的目录。策略存在于它点名但没有内联的三个文件里。第一步还把工作交给脚本，因为脚本的代码根本不会进入 context window：进入的只有它的输出。²

加载模型有一个名字，也有三个阶段。规范给出这些阶段时附带了 token 预算：¹

1. 元数据，约 100 个 token：name 和 description，每个已安装 skill 在启动时都会加载。
2. 指令，建议低于 5,000 个 token：SKILL.md 正文，在 skill 被激活时加载。
3. 资源，按需加载：打包文件，只有在某样东西需要它们时才加载。

参考文档在同一张表里放了第四列——何时加载、token 成本、内容——而关键是第三行：访问之前没有成本。³ 总结整章的一句话也在那里：

文件在被访问之前不会消耗 context，因此 Skills 可以包含完整的 API 文档、大型数据集或大量示例。未使用的打包内容没有 context 惩罚。³

本章开头的实测表，就是用五个并非为本文而写的 skills 检查这一说法。两行值得对照阅读。

next-best-practices 有 966 个 token 的正文，链接到 19 个文件，这些文件共 19,374 个 token。让它修复 hydration error，agent 会读取正文加上 hydration-error.md：20,340 个 token 中只读 1,409 个，相差 14 倍，另外 18 个文件从未打开。

next-cache-components 有 2,334 个 token 的正文，并且没有任何打包文件。它是一个有效 skill，也写得很好，但它没有 level 3 可供披露。这是这项技术的诚实边界：渐进式披露只有在有东西可以推迟时才省钱。一个知识无法拆分的 skill，在激活时就要支付整个正文的成本，剩下唯一杠杆就是不要激活它。

Level 1 是基于一句话做出的路由决策。skill 的其他任何东西都不会影响它是否会被打开——不是正文质量，不是示例，不是脚本。所以 description 不是文档。它是查询表面，而且可能写错。

规范用一个好例子和一个坏例子说明了这一点，而坏例子只有四个词：description: Helps with PDFs.¹ 这值得测量，而不是直接接受。

六个 skills，每个都有一个合理的 description，说明它做什么以及何时使用。二十四个请求，每个 skill 四个，用真人会说的方式表达，而且从不点名 skill。模型在 system prompt 中看到六行，必须回答一个名称或 NONE。使用 greedy decoding，因此结果可复现。然后用同样二十四个请求和同样六个 skills 再跑一次，只是把 description 削减到只剩主题。

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

先读区间，正如 第 4 章坚持的那样，也正如 第 29 章会再次坚持的那样：它们重叠，而二十四个案例不能仅凭总体数给两个系统排序。真正定论的是配对比较，而它是 第 15 章的工具：在两个分支意见不一致的十个案例中，九个归丰富 description，一个归稀薄 description。这在常用阈值下成立。

现在读最后一行，那才是真正发现。使用稀薄 description 时，模型在二十四个请求中的九个回答了 NONE。不是选错 skill：而是没有 skill。下面四个是原文逐字摘录：

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

一个完美的 sql-review skill 已安装，带有正文、示例和清单，却连续三次在它本来要回答的三个问题上从未被打开。对一个 level 1 永远到达不了的 skill，level 2 和 level 3 都无关紧要。

修复成本：214 个 token，也就是 295 和 81 的差值，分摊在六个 skills 上。这是 第 18 章的发现从另一侧抵达。在那里，只改工具的 description，就把日期格式化从 24 个里对 2 个变成 24 个全对。这里，只改 skill 的 description，就把激活从 24 个里 10 个提升到 18 个。两种情况下，系统里最便宜的修复都是一句话；两种情况下，这句话都必须命名触发条件，而不只是主题：不是这个东西是什么，而是用户刚刚说了什么时它适用。

本章按自己的标准还欠一个警告。这是一个 5 亿参数模型，frontier model 的路由表现远好于 75%。请读取机制，而不是数量级：无论哪个模型阅读，路由信号都只有一句话；而任何模型都无法基于你没有写进那句话的信息做选择。

第二种失败与第一种相反。skill 被找到了，level 也正确拆分了，然后 agent 还是把它全读了。

vercel-react-best-practices 是一个真正构建得很好的 skill。它 1,670 个 token 的正文是一张包含八类的优先级表，以及一个点名 70 个规则文件的速查表，每个文件一行。规则就在旁边的磁盘上：70 个文件，最小 132 个 token，中位数 319，最大 1,052。问它一个关于 barrel imports 的问题，诚实成本是正文加一个文件——不到 2,400 个 token，而整个包是 53,670。

然后正文最后一行写着：

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md 是 26,362 个 token。它是 70 个规则文件的拼接版：规则之和是 25,784，差值来自它们之间的标题。所以这个 skill 给了 agent 一个选择：读一个中位数 319 个 token 的规则，或者读同样内容的全部版本，价格是前者的 83 倍——而且它用一句没有标明成本、也没有说明何时该这么做的话提供了这个选择。

这不是 bug，文件也没有错；编译好的文档对人类确实有用，对被要求审计整个代码库的 agent 也有用。它是一个带 level-2 邀请的 level-3 文件，这个教训也超出了这一个 skill：从 SKILL.md 指向外部的每条路径，都应该说明它的成本以及何时值得使用，因为模型无法知道某个文件名比它上面的那个文件名贵 83 倍。

同一个文件夹还给了一个关于陈旧性的较小教训。正文说「8 个类别中的 70 条规则」并列出了 70 条；rules/ 目录有 72 个文件，其中两个是脚手架（_template.md 和 _sections.md）；旁边的 metadata.json 则说「40+ rules」。同一集合在一个文件夹中有三个计数，一个正确，一个只是算术结果，一个是早期版本遗留。skill 是文档，而文档会像一条已经从旁边代码漂移开的代码注释一样腐烂——区别是，这份文档由一台不会皱眉的机器阅读。

开放规范定义了六个 frontmatter 字段。参考实现 Claude Code 接受二十个。² 有五组值得按名称了解，因为它们正是这种格式不再只是文档的地方：

参数（arguments、argument-hint）允许人传入会被替换进正文的值，这使 skill 可作为 slash command 使用。作用域（paths）把激活限制在匹配某个 glob 的文件上。dynamic context injection 则是改变心智模型的那一项：形如 !`git diff HEAD` 的一行会在正文发送前运行，其输出会被替换进文本。文档是模板，其中一部分在读取时计算。

现在是陷阱，而且同一份文档也明说了：在 Claude Code 之外——在网页产品中、通过 Skills API、打包时——只允许六个规范字段，任何其他字段在上传时都是硬错误。² 所以，一个在某个产品里完美可用的 skill，会在同一供应商的另一个产品里安装失败，而且失败点是 frontmatter，而不是任何你能通过阅读 prose 测出来的地方。如果你打算让 skill 可移植，六个字段就是全部预算。如果你不打算，就在 compatibility 里说明，它正是为此而存在的。

四种东西经常被混为一谈，而这种混淆不是词汇洁癖：选错了，要么每一轮都花钱，要么失去你以为拥有的保证。

加粗的两行就是全部区别。skill 是被读取的；工具是被调用的。 skill 是进入 context window 的 prose，会和窗口里的其他所有内容争夺 attention；模型可以遵循它、误读它或忽略它，而系统里没有任何东西会注意到。工具则是一次离开模型之手的调用：你的代码接收参数、验证参数、检查权限并做决定。第 18 章把这描述为模型提出、你的代码处置，而这条分界线正是 skill 不具备的。

所以，六个真实案例，逐一判定：

这段历史很短，时间点异常清楚，而且几乎没人讲这一部分。

Agent Skills 于 2025 年 10 月 16 日作为某个供应商的功能发布，在那篇公告中被定义为「有组织的指令、脚本和资源文件夹，agents 可以发现并动态加载它们，以便在特定任务上表现更好」；三个 level 通过一个值得保留的类比来描述：「就像一本组织良好的手册，先从目录开始，然后是具体章节，最后是详细附录」。⁴

2025 年 12 月 18 日，同一页面更新，宣布这种格式成为开放标准，拥有自己的规范 agentskills.io，治理向贡献开放，并提供参考验证器。³ 在 2026 年 9 月 7 日阅读时，该标准的 client showcase 列出了 46 个产品——编辑器、终端、云平台和移动运行时，其中包括 Anthropic、OpenAI、Google 和 Mistral 的第一方 coding agents——每个都链接到自己的设置文档。¹

它与 MCP 的汇合是在公开环境中进行的，而且有可核查的数字：

有趣的是关闭，而不是提案本身。SEP-2076 要求在 tools、resources 和 prompts 之外增加第四个 primitive。由它形成的工作组决定答案是不：skills 搭载在已经存在的 resources primitive 上，作为 opt-in 扩展。⁵ 第 26 章在协议自己的 changelog 里测到了同样的本能：sampling、roots 和 logging 被废弃，而不是保留。一个会移除自己所提提案的标准组织表现良好；之所以要把数字摆在前面讲这个故事，是因为你在别处读到的摘要仍会把 skills 描述成 MCP primitive。

现在你可以写一个 SKILL.md，把它拆成三个能够自付成本的 level，读取别人 skill 的 frontmatter，并知道哪些字段上传到别处时无法存活；你也可以回答整章围绕的问题——system prompt、skill、工具还是服务器——并给出理由，而不是凭习惯。

但你还不能判断自己的东西是否有效。

本章中所有重要主张都是测量，最重要的那个是准确率：24 个里 18 个对 24 个里 10 个，每个都有区间，二者之间还有配对检验，因为两个重叠的总体数什么也决定不了。那个工具是借来的。skill 的 description 是路由键，正文是模型可能遵循也可能不遵循的流程；这两者的性质都只能通过多次运行并给返回结果打分来发现——这就是 golden set、你在运行前写好的 grader，以及那个问它是否每一次都有效、而不是至少一次有效的 metric。

第 29 章就是这个，它开头的数字也是本章方法所依赖的数字：一个十次里成功七次的 agent 看起来像 70%，而它的 pass^10——十次全成功的概率——是零。它还在同两百份 transcript 上测量了三个 graders，在没有重新生成一个 token 的情况下得到 0%、13% 和 26%。在你信任刚写进 description 的那句话之前，你需要一个工具告诉你：它比你替换掉的那句话更糟。

本章中的每个 token 计数，都是在 2026 年 9 月 7 日用 tiktoken 0.14.0 和 o200k_base encoding 在本地生成的：对象包括本章开头列出的五个第三方 skills，以及为本章编写的 release-notes skill，其完整文本已在上文部分复现。Level 1 按 host 渲染进 system prompt 的单行 - name: description 测量；level 2 是去掉 frontmatter 后的 SKILL.md 正文；level 3 是文件夹中的其他所有文件。成本使用第 16 章针对 gpt-5.6-terra 测得的费率：每百万输入 token $2.00、每百万缓存输入 token $0.20，并应用到这些计数上——它们是基于实测 token 的算术，不是对真实账单的观察。撰写本章没有调用任何付费 API。

激活实验在一张消费级 GPU 上以 half precision 运行 Qwen/Qwen2.5-0.5B-Instruct，使用 greedy decoding，对六个 skills 发出 24 个请求，跑两次——一次使用说明 skill 做什么以及何时适用的 description，一次把 description 削减到只剩主题，风格类似规范自己的「poor example」。区间为 95% Wilson；配对比较是在十个不一致案例上的双侧 exact sign test；Wilson 区间来自第 4 章，exact paired sign test 来自第 15 章，二者均原样复用。请把数量级理解为一个很小模型的属性，把方法理解为可迁移的。

这里测量的五个 skills 是第三方包，并非为本章所写：来自 vercel-labs/next-skills 的 next-best-practices 和 next-cache-components，以及来自 vercel-labs/agent-skills 的 vercel-composition-patterns、vercel-react-best-practices 和 vercel-react-native-skills。它们的内部计数——70 个规则文件、26,362 个 token 的 AGENTS.md、日期为 2026 年 1 月且声称「40+ rules」的 metadata.json——均于 2026 年 9 月 7 日从磁盘文件读取，是该发布版本的属性，不是对作者的批评：每一个都是任何被编辑次数多于被计数次数的文档树都会出现的那类漂移。