如何写好一个Skill：我从Anthropic指南里总结出的6个关键点

前面几篇，我一直在讲 Skill 为什么值得关注。

它不是一个孤立的新概念，而是在补 AI 应用里长期缺失的一层：
不是“会不会做某个动作”，而是“某类任务到底该怎么稳定地做”。

但如果再往前走一步，一个问题其实绕不过去：

好，Skill 值得做，那一个 Skill 到底该怎么写，才算写得好？

最近我专门看了 Anthropic 的一篇指南《The Complete Guide to Building Skills for Claude》。
这篇文档写得很系统，覆盖了 Skill 的规划、结构、测试、分发和常见问题。

它给我的一个最大感受是：

一个好 Skill，关键不在“功能多不多”，而在“它是不是足够清楚、足够稳定、足够容易被正确触发”。

换句话说，Skill 不是写给人类看的 README，也不是把一段长 Prompt 换个壳。
它其实更像一个需要被系统理解、被模型调用、被任务链路稳定路由的能力模块。

如果从这个角度看，我觉得 Anthropic 这份指南里最值得记住的，是下面这 6 个点。

1. 不要一上来写说明，先定义 2 到 3 个具体 use case

这是整份指南里我最认同的一点。

很多人写 Skill 的时候，很容易一开始就进入“我要写哪些说明”“我要列哪些步骤”的状态。
但 Anthropic 的建议恰恰相反：

先别急着写，先想清楚这个 Skill 到底是给什么任务用的。

它强调，在写 Skill 之前，最好先明确 2 到 3 个具体 use case：

• 用户想完成什么
• 会怎么表达这个需求
• 这个任务大概需要哪些步骤
• 最终结果应该长什么样

这件事为什么重要？

因为一个 Skill 一旦离开具体 use case，很容易变得越来越泛。
描述看起来很大，边界却越来越模糊。
而边界一模糊，后面的问题就都会跟着来：

• 触发不稳定
• 使用场景不清
• 说明越写越长
• 结果越来越不可控

所以我现在越来越倾向于把这件事看成 Skill 设计的第一步：

不要先想“我这个 Skill 很厉害”，先想“用户到底要用它完成哪类事”。

Skill 的起点，不应该是功能清单，而应该是任务清单。

2. frontmatter 是 Skill 里最重要的一层

Anthropic 在这份指南里反复强调一件事：

YAML frontmatter 是 Skill 最重要的部分。

这点很多人一开始可能不会太在意。
觉得 frontmatter 只是放个名字、描述、版本号，真正重要的还是后面的正文说明。

但从 Claude 的加载机制来看，事情刚好相反。

frontmatter 是 Skill 的第一层。
它不是给人读的，而是给系统判断“这个 Skill 什么时候值得加载”的。

其中最关键的字段就是 description。

这份指南对 description 的要求其实非常清楚：

• 不只是写“这个 Skill 是干什么的”
• 还要写“什么情况下该用它”
• 最好带上用户真的会说出来的触发表达
• 如果相关，也要提到文件类型、任务类型和适用范围

也就是说，一个好的 description，是一个“触发提示器”。

这一点特别值得注意。

因为很多 Skill 的问题，根本不在正文，而在 frontmatter 里就埋下了：

• 写得太泛，结果什么都像能触发
• 写得太抽象，结果该触发的时候又触发不了
• 只写“做什么”，不写“什么时候用”

所以如果只记住一条，我觉得就是：

frontmatter 不是附属信息，它决定了 Skill 会不会在对的时候被系统想到。

3. 一个好 Skill，正文一定要短、清楚、可执行

这是我看完整份指南后，感受非常强的一点。

Anthropic 对 Skill 正文的建议，其实非常务实：

• 说明要尽量简洁
• 关键规则要放前面
• 多用编号和 bullet point
• 复杂细节不要全塞进正文

这背后其实是在提醒一件很重要的事：

Skill 不是越长越专业，很多时候恰恰相反，越长越容易失控。

因为 Skill 的正文不是一篇给人类慢慢读的文档。
它是模型在任务过程中需要快速吸收并据此行动的工作说明。

如果说明写得太散、太绕、太像背景知识堆砌，模型未必真的会按你想的方式执行。

这也是为什么 Anthropic 很强调：

• 关键指令前置
• 重要规则明确标出来
• 尽量避免模糊表达

比如“注意检查一下结果”这种写法就很弱。
相比之下，像“在调用某个工具前，必须先确认 A、B、C 三项条件”就会清楚得多。

所以在我看来，一个好 Skill 的正文，核心不是“写全”，而是：

让模型知道下一步该怎么做，而且别理解偏。

4. Skill 要做分层，不要把所有东西都塞进 SKILL.md

这份指南里，我觉得另一个特别重要的原则是：

Progressive Disclosure，渐进式披露。

Anthropic 把 Skill 理解成一个三层结构：

• 第一层：frontmatter
  只负责让系统知道这个 Skill 什么时候可能相关

• 第二层：SKILL.md 正文
  负责主要指令和工作流程

• 第三层：引用的脚本、参考文档、资源文件
  只在需要的时候再进一步加载

这个设计思路其实非常好，也非常工程化。

因为它天然解决了一个现实问题：

不是所有内容都值得常驻在模型上下文里。

如果你把所有规则、细节、案例、模板、参考资料都写进 SKILL.md，短期看好像很完整，长期看几乎一定会出问题：

• 上下文越来越重
• 重点越来越不突出
• 模型注意力越来越分散
• 维护成本越来越高

所以一个好 Skill，不是把所有东西都写进去，而是要知道：

• 什么信息必须前置
• 什么流程必须写清
• 什么细节应该延迟到真正需要的时候再读

这一点我觉得不只是写 Skill 的技巧，更像是一个总体原则：

Skill 的目标不是“信息尽可能多”，而是“在合适的时候给出合适的信息”。

5. 一个好 Skill，不只要能跑，还要能被正确触发

这一点很容易被忽略，但 Anthropic 其实讲得很明确。

很多人测试 Skill，关注的是：

• 它能不能正常执行
• 调工具会不会报错
• 最终结果能不能出得来

这些当然重要。
但从使用体验上看，还有一个同样关键、甚至更关键的问题：

它到底会不会在该出现的时候出现，在不该出现的时候不出现。

Anthropic 在指南里给出的一个很实用的思路是：

测试 Skill，不只要测“能不能跑”，还要测：

• 明显相关的请求，会不会自动触发
• 换一种表达方式，还能不能触发
• 不相关的话题，会不会误触发

我觉得这个提醒非常到位。

因为 Skill 不是一次性命令，而是一个会被系统路由的能力模块。
如果它总是需要手动点名才能用，那它就很难真正融进工作流；
如果它又经常误触发，那系统很快就会变得吵闹、臃肿。

所以一个好 Skill 的判断标准，不只是“会不会做”，还要加上一条：

会不会在合适的时候被想到。

这一点，和前面讲 frontmatter 的重要性，其实是完全连起来的。

6. 一个好 Skill，一定是边写边测、边测边收敛的

最后一点，也是我觉得 Anthropic 这篇指南特别成熟的地方：

它不是把 Skill 当成一个“一次写完”的东西，而是默认它一定要经历测试和迭代。

这一点非常现实。

因为 Skill 的问题，很多都不是在你写的时候暴露的，而是在真正使用时才会出现：

• 描述太泛，导致误触发
• 说明太啰嗦，导致模型抓不住重点
• 范围太大，导致任务边界不清
• 流程太理想化，导致一碰异常就乱

所以写 Skill 的过程，本质上更像是：

• 先定义一个可工作的版本
• 用真实任务去测
• 看它是触发不足，还是触发过多
• 看它是说明不清，还是范围太散
• 再不断细化、重写、拆分

这也是为什么我看完之后，对“好 Skill”这件事有了一个更明确的判断：

一个好 Skill，通常不是一开始就设计得很大，而是经过反复测试之后，边界越来越清楚、流程越来越稳定。

换句话说，写 Skill 更像是在训练一个能力模块，而不是写一份说明文档。

写在最后

看完 Anthropic 这份指南，我最大的感受其实不是“原来 Skill 有这么多格式要求”，而是另一件更本质的事：

Skill 的质量，最终取决于它是不是足够清楚、足够克制、足够容易被系统正确使用。

它不是比谁写得长，也不是比谁功能堆得多。

一个真正好用的 Skill，通常有几个共同点：

• 它服务的是明确任务，而不是模糊概念
• 它的触发条件清楚
• 它的正文简洁、可执行
• 它知道什么该前置，什么该按需加载
• 它经过真实测试，而不是只停留在“看起来写得不错”

这也是为什么我越来越觉得，Skill 这件事真正难的地方，不是“写一个文件夹”，而是把一类任务的方法，稳定地压缩进一个能被系统反复调用的能力模块里。