为什么需要 Skills 这个东西

用 Claude Code 或者 Cursor 写了一段时间代码的人大概都有同一种感受：模型本身没问题，它的通用能力常常让人惊讶，但一旦要它按公司内部的流程办事——比如按团队的 commit 规范写一条 commit message、按特定的 PPT 模板出一份项目周报、按财务系统的字段填一份报销单，它就突然变回一个刚入职三天的实习生。它不是不会写，而是不知道这边是怎么干这件事的。

这个"懂通用能力但不懂组织上下文"的鸿沟，就是 Anthropic 在 2025 年 10 月开始填的坑。他们给出的答案叫 Agent Skills。

时间线

2025 年 10 月 16 日：Skills 诞生

Anthropic 工程博客发了一篇标题直白的文章，《Equipping agents for the real world with Agent Skills》，署名 Barry Zhang、Keith Lazuka、Mahesh Murag。文末附了一句"who all really like folders"，几乎算得上这个项目的精神原型。

文章把 Skill 定义得很朴素：一个 Skill 就是一个文件夹，里面有一个 SKILL.md，外加可选的脚本、参考文档和资源文件。SKILL.md 开头是一段 YAML frontmatter，至少要有 name 和 description 两个字段。agent 启动时会把所有已安装 Skill 的 name 和 description 预加载进系统提示词，判断哪个任务该触发哪个 Skill。

这个设计的灵魂是渐进式披露（Progressive Disclosure），分三级：

  • 第一层是 metadata。所有 Skill 的 name + description 常驻上下文，模型需要的只是一份目录，知道有哪些能力可选。
  • 第二层是 SKILL.md 正文。命中某个 Skill 时才读进来，理想长度 500 行以内。
  • 第三层是 bundle 进来的其他文件（references/、scripts/、assets/）。只在真正需要的时候按需加载，脚本甚至可以直接执行而不用先读进上下文。

官方举的例子是 PDF Skill。Claude 本身很会读 PDF，但不太会填 PDF 表单。填表的细节逻辑放在单独的 forms.md 里，Claude 只有在真要填表时才去读。抽取表单字段这种确定性操作则写成一个 Python 脚本放进 scripts/，Claude 直接执行就行，比让模型用 token 一个字段一个字段对着 PDF 抠要便宜得多。

同一篇文章里还埋了一句话：

Looking further ahead, we hope to enable agents to create, edit, and evaluate Skills on their own.

这句话后来兑现了一半，就是下面要讲的 skill-creator。

2025 年 12 月 18 日：Skills 升级为开放标准

时隔两个月，Anthropic 把 Agent Skills 升级为开放标准，规范站点 agentskills.io 上线。Skills 从一个 Claude 产品的内部机制，变成了一个跨平台的文件格式标准。

Simon Willison 在 当天的博客 里给了一个挺精准的概括：这个规范小得可以几分钟读完，且有意留白。比如 metadata 字段直接写"客户端可以用来存储规范未定义的其他属性"，allowed-tools 字段被明确标记为 experimental。主页上打出来的采用方名单有 OpenCode、Cursor、Amp、Letta、goose、GitHub、VS Code，一天之后 OpenAI Codex 也加了进去。

这家公司一年里先是把 MCP 做成了事实标准，接着又把 Skills 做成了事实标准，在刻意扮演行业基础设施制定者的角色，而不是把这些东西攥在手里做护城河。

2026 年 3 月 3 日：skill-creator 的重做

真正让 Skills 好用起来的那一脚是半年后踢的。2026 年 3 月，Anthropic 更新了官方的 skill-creator，也就是那个"帮你写 Skill 的 Skill"，并发了一篇标题明确的博客《Improving skill-creator: Test, measure, and refine Agent Skills》。因为这一版变化幅度够大，社区直接把它叫做 Claude Skills 2.0。

这一版没有再造新概念，只解决了一个具体的老问题：Skill 写出来以后，过去几乎没有办法判断它到底有没有起作用。常见场景是这样的：写一个 Skill，随便跑两个 prompt 试试，觉得差不多就收工了。几周后模型小版本更新，或者自己改了两行 SKILL.md，某天突然发现输出变差，但很难定位是哪一步引入的回归，因为根本没有 baseline。

新版 skill-creator 把软件工程那套东西搬了进来，加了三件事。

2026 版 skill-creator 到底改了什么

Eval：从凭感觉到能对比

写完 Skill 草稿以后，skill-creator 会主动让作者凑 2~5 个真实的测试 prompt，然后对每个 prompt 同时跑两份，一份加载了当前 Skill，一份裸跑 Claude。跑完之后脚本会把结果聚合成一个 benchmark（pass rate、耗时、token 消耗，带上均值和标准差），再打开一个浏览器里的 eval viewer 左右对照地展示两份输出。

这里有一个关键细节：baseline 的选择是自动切换的。创建新 Skill 时 baseline 是不加载任何 Skill 的裸 Claude；迭代已有 Skill 时，skill-creator 会先把旧版本快照到 skill-snapshot/ 里，然后用旧版本当 baseline。这样每次迭代都能看到"比上一版进步了多少"，而不是只跟裸模型比。

assertion 是可选的。文件转换、数据抽取、固定流程的代码生成这种有确定答案的任务适合写断言；写作风格、设计这种主观任务就不必强上断言，直接让人看输出即可。官方源码里还埋了一条建议：能用脚本验证的就写脚本而不是肉眼看，脚本可以跨 iteration 复用，比人眼可靠。

Blind A/B：让另一个 Claude 当裁判

这是给要求更严的用户准备的。比如改了一版 Skill，想知道新版是不是"真的更好"而不是"我觉得更好"，skill-creator 可以把两份输出隐去来源，交给一个独立的 Claude 实例评判，让它自己挑出赢家并给出理由。

这个机制在实践里可以用来对比四种组合：有 Skill vs 没 Skill、旧版 vs 新版、两个做同一件事的不同 Skill、同一个 Skill 在两个不同模型上。它依赖 subagents，所以目前只在 Claude Code 和 Cowork 里可用，Claude.ai 没有。

Description Optimization：用 train/test split 防止过拟合

这一块是我觉得最见功力的地方。

Skill 描述这件事有个长期被低估的事实：描述写得不好的时候，Skill 的逻辑照样在，但模型根本不会触发它。触发机制完全走 description 字段，模型只看那段描述决定要不要激活。Anthropic 自己在文章里承认，Claude 天然有一种"低触发倾向"——即使 Skill 对当前任务明显有用，它也经常跳过不用。所以 skill-creator 里反复强调 description 要写得有点推力。

2026 年这版 skill-creator 把 description 调优做成了自动循环。先让 Claude 生成 20 条真实风格的 prompt，一半应该触发、一半不应该触发。"不应该触发"的那些是故意写得有迷惑性的，关键词沾边但其实要干的不是一回事。用户在浏览器里审阅这份 prompt 集，可以改、可以删、可以加。

20 条 prompt 会被切成 60% 训练集 + 40% 保留测试集。用的是机器学习里经典的 train/test split，目的就是防止描述过拟合到训练 prompt 上。对当前描述在训练集上跑的时候，为了对抗模型行为的随机性，每条 prompt 跑 3 次，2/3 以上命中才算触发成功。然后看哪些该触发没触发、哪些不该触发却触发了，让 Claude 基于失败样本写一个新版本的描述。最多迭代 5 轮，每轮都能看到之前所有版本，并被明确告知不要和前面几版重复，逼着它尝试实质不同的写法。

最后选 winner 的时候，用的是测试集分数而不是训练集分数。这一条是整个流程里最关键的防过拟合设计。训练集分数最高的那个版本，可能只是把训练 prompt 记住了，未必能泛化。

Anthropic 在自家 6 个内置文档类 Skill 上跑了这个优化循环，其中 5 个的触发率都有改善。description 这种看起来很"软"的东西居然能用 ML 手法来系统优化，工作量和回报的比值相当划算。

最新的 Skill 构建方法论

把 2026 年这版 skill-creator 源码（GitHub 仓库 anthropics/skills）和官方 best practices 文档 结合起来看，已经能提炼出一套相对稳定的方法论。

SKILL.md 不是容器，是目录

新手最常见的毛病是把所有知识往 SKILL.md 里塞，写出一个 2000 行的巨无霸，然后奇怪 Claude 为什么调用得这么慢。500 行是一个被反复提到的上限，官方 best practices 给的是"5000 单词以内"的更宽松说法，两个口径差不多等价。

真正的写法是把 SKILL.md 当目录用：

  • 主流程、判断分支、写作风格这些每次都要看的东西放在 SKILL.md 本体
  • API 文档、长案例、扩展语法这些只在某些分支才用到的东西放 references/*.md，从 SKILL.md 里按需指向
  • 确定性计算、文件操作、格式验证这些代码能做得更准的放 scripts/
  • 输出要用到的模板、字体、图片放 assets/

当 Skill 要支持多个变体，比如一个 cloud-deploy Skill 同时覆盖 AWS、GCP、Azure，就按变体拆分 reference 文件，SKILL.md 只负责选型逻辑。Claude 只读它真正需要的那个 reference，剩下的根本不进上下文。

Description 写"什么时候该触发"，不写"它能做什么"

这是一个在各种教程里被反复强调、但依然最容易写错的字段。

本地那份 writing-skills 的 SKILL 文档里记了一个踩坑经验：如果在 description 里概述了 Skill 的工作流程，Claude 可能直接按 description 里的概述执行，而不去读 Skill 正文。原话是一个代码审查 Skill，description 里写了"进行代码审查"，结果 Claude 做了一次审查，但 Skill 正文里写的是分阶段的两次审查。等把 description 改成纯粹的触发条件（“当执行带独立任务的实施计划时使用”），不再描述流程，Claude 反而老老实实读 Skill 正文，按正文的流程走了两次审查。

背后的逻辑其实简单：description 是工作流的捷径，当它能独立工作时，模型就不再读正文了。所以写 description 有个反直觉的纪律：描述触发条件，不要描述流程。官方公式是：

What it does + Use when [trigger phrases] + Key capabilities

写完描述后用 skill-creator 的 description optimization 跑一轮，能把触发准确率再往上拉一截。

Eval-driven：把软件工程的那套抓过来用

这是 2026 版 skill-creator 真正在推的范式转变。核心动作不是"评估 Skill"，而是把评估作为默认开发环节。完整的循环长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
写 SKILL.md 草稿
  ↓
整理 2~5 条真实 prompt 进 evals/evals.json
  ↓
同一回合内并发跑 with-skill 和 baseline 两套
  ↓
启动 eval-viewer，人对着 diff 留反馈
  ↓
读 feedback.json，做下一轮修改
  ↓
新建 iteration-N+1/ 目录，重跑
  ↓
直到反馈都为空或者用户满意
  ↓
（可选）跑 description optimization
  ↓
打包成 .skill 文件交付

每一轮的结果（输出、timing、grading、benchmark）都落在 <skill-name>-workspace/iteration-<N>/eval-<ID>/ 下，可追溯、可对比。下一轮带上 --previous-workspace 参数跑时，viewer 里能看到每个 case 的上一版输出和上一版反馈。这种对照关系让迭代感非常像打磨代码，而不是修改文档。

改进时不要过拟合到几个测试用例上

这是 skill-creator 源码里最意味深长的一段（来自 Improving the skill 部分，我翻译并略作转述）：

我们在写的是要被用一百万次甚至更多的 Skill。你和用户反复在几个例子上迭代，只是因为这样推进得快，用户对这几个例子门儿清，评估起来也快。但如果这个 Skill 只在这几个例子上好使，那它就没用。与其往里加一堆细抠小细节的修正，或者堆一大坨压迫性的 MUST，不如跳出来试试不同的隐喻、不同的工作模式。反正试一次很便宜。

再往下还有一条：

如果你发现自己在写全大写的 ALWAYS 或 NEVER、或者非常僵化的结构，这就是一个黄牌信号。如果可能，换成解释原因的措辞，让模型理解为什么这件事重要。今天的 LLM 是聪明的，它们有不错的心智理论能力，给一个好的 harness，它们能超越死记硬背，真正把事情做成。

这段话在我看来比任何工程细节都重要。它实际上是在说：Skill 的写法应该更像写给一个新同事的 onboarding 文档，解释清楚"为什么"，然后信任对方的判断力。而不是写给一个只会执行规则的机器，恨不得把每一种可能的走神都堵死。

跨测试用例发现通用脚本

还有一个很好用的经验法则：跑完 eval 以后读每个 subagent 的 transcript，看它们是不是都独立写了类似的辅助脚本。如果 3 个测试 case 的 subagent 都分别写了一个 create_docx.py 或 build_chart.py，这就是个非常强的信号，这段代码应该被抽出来放进 Skill 的 scripts/ 里，写一次，以后每次调用直接用。这种模式可以省掉大量"每次重新发明轮子"的开销，对于高频被调用的 Skill 尤其明显。

一些零散的实操经验

半年用下来的一些零散经验：

  • 同时挂载的 Skill 数量不要超过 20~50 个。每轮对话 Claude 都要读所有 Skill 的 description 来判断触发，挂得太多 description 开销就会显著拖慢速度。
  • 新模型发布后重跑 benchmark。上一代模型能 100% 命中的 Skill，在新模型上行为未必一致。skill-creator 的 benchmark 基础设施天生就是为跨模型回归测试准备的。
  • 必要的确定性操作一律写脚本。Anthropic 自己的 PDF Skill 以前让 Claude 根据散文指令去填未填写的表单位置，效果很差，后来把坐标抽取逻辑写成脚本，问题直接消失。脚本对某件事的一致性是散文指令给不了的。
  • 版本化你的 Skill。在 frontmatter 里加一个 metadata.version 字段，benchmark 出问题时能快速对齐到具体版本。
  • Skill chaining 是一个隐藏的力量点。在一个 Skill 的 SKILL.md 里明确写"完成 X 以后，调用 ai-writing-guard Skill 检查一遍"，Claude 真的会链式触发下一个 Skill。这样复杂工作流可以拆成一堆职责单一的小 Skill 堆在一起，而不是写一个巨大的 SKILL.md。

参考资料