花十小时打磨的 Skill，永远胜过十分钟随手写的

我以为写一个 Skill 就是把 SKILL.md 扔进文件夹，十分钟搞定，完事儿。这套路挺管用，直到我发现同样的错误在每次调用里反复出现，而且我根本没法判断这个 Skill 到底有没有按我想的方式运行。

后来 Thariq——Anthropic 负责构建 Claude Code 的工程师之一——发了一段话，彻底改变了我的认知：“用好 Skills 本身就是一种技能。”

这句话之所以戳到我，是因为它和我看到的现实完全吻合。一个随手写的 markdown 文件和一个结构完善的 Skill 文件夹之间的差距，真实地体现在输出质量上，不只是理论层面的说法。

Skill 是文件夹，不是文件

最常见的误解是：一个 Skill 等于一个 SKILL.md 文件。实际上，Skill 是一个文件夹，里面包含脚本、参考代码、配置文件，以及将这些内容串联起来的 markdown 文件。

Anthropic 内部采用的是他们所说的”渐进式披露”方式。不是把所有内容塞进一个提示词，而是把文件按层级组织，让 Claude 在需要的时候才读取需要的内容。references/api.md 里放的是函数签名，Claude 按需调取；assets/ 目录里是输出模板，这样提示词就不用去描述格式了；验证脚本让 Claude 在返回结果之前先自检输出。

打开 skill-creator 仓库 就能看到这个原则在实际中的样子。agents/、references/、scripts/ 这几个目录和 SKILL.md 并排放着。构建 Skill 的工具本身就是按 Skill 的方式构建的。

Gotchas 比正文内容更重要

Thariq 说，Gotchas 这个章节是 Skill 里”信息密度最高的内容”。不是主体指令，不是示例，是 Gotchas。

这和我的实际经验完全对得上。我写了一个没有 Gotchas 章节的 Skill，结果同一个错误连续出现了三次。我一加上那条具体记录这个失败模式的说明，问题就再也没出现过。

道理很直接。Claude 对你在正文里写的大部分内容早就知道了。告诉它怎么写 TypeScript、怎么格式化 JSON，不过是在重复它本来就能做好的事。但告诉它在你这个具体场景里不该做什么，才是真正的新信息。

Thariq 的帖子里有几条原则我发现很靠谱：不要陈述废话，因为多余的指令实际上会拉低性能；不要用过于具体的步骤把 Claude 框死，那样会削弱它的应变能力；还有，description 字段不是给人看的文档，它是 Claude 用来判断什么时候触发这个 Skill 的输入。

Skill Creator 把”感觉能用”变成”有据可查”

两周前 Skill Creator 的更新改变了我对 Skill 质量的理解方式。你定义测试提示词，设定预期结果，工具来验证这个 Skill 是否真的产出了正确的结果。这就是给提示词写单元测试。

我给一个用了好几周的 Skill 加上了评估。我以为肯定能过的两个测试用例，立刻就挂了。修改的内容不多，但应用之后输出质量明显提升了。

有一个有用的区分：Skill 分两种。能力提升型 Skill 是教 Claude 做它本来做不好的事；偏好编码型 Skill 是把团队特定的工作流或标准固化下来。前者有天然的保质期，因为模型迭代最终会让它变得多余。后者只要工作流还在，就一直有价值。评估能帮你发现能力提升型 Skill 变成死重的那个时刻。

工具支持基准模式，可以跨模型更新追踪通过率和 token 用量；支持多 Agent 并行执行，避免测试时的上下文污染；还有一个比较 Agent，能对有 Skill 和没有 Skill 的输出做盲测 A/B 对比。

复利回报

我见过几百个 Skill，自己维护着几十个，有一个规律始终成立：Skill 的价值来自迭代，不来自初稿。

文件夹结构是你塑造 Claude 上下文窗口的方式。Gotchas 把你的失败转化成可复用的知识。评估衡量这些知识是否还有效。

写一个 SKILL.md 要十分钟。把真实失败整理成 Gotchas、构建评估用例、加入验证脚本，加起来要接近十小时。但这个投入每次 Skill 运行时都在回报你。今晚就动手搭一个。到明天早上，它已经做完了你不需要亲自做的工作。