Claude Skill 构建完整指南：从入门到精通
如果你已经写过几次 Skill，很容易把注意力放在 SKILL.md、frontmatter、references/、assets/ 这些外层结构上。Anthropic 这份完整指南真正有价值的地方，是把 Skill 从“提示词格式”重新定义成“工作流封装”。它关心的不是文件摆得像不像样，而是这套能力能不能被稳定触发、按预期执行、并且随着反馈持续迭代。
所以我读完后的核心判断是：Skill 不是给模型多塞一段说明，而是把你的最佳实践拆成三层资产管理好。第一层是触发条件，决定它该不该被调起；第二层是步骤和门禁，决定它执行时会不会跑偏；第三层是脚本、模板和参考资料，决定它能不能既稳定又节省上下文。
文档一开始就把 Skill 说得很清楚：它是一个可移植的文件夹，最少包含 SKILL.md，必要时再配 scripts/、references/ 和 assets/。但这个文件夹结构只是容器，不是重点。重点在于 Skill 要解决的，是“把反复出现的工作方法封装成稳定能力”，而不是“写一段很长的指令”。
这也是为什么文档反复强调 Progressive Disclosure。frontmatter 常驻、SKILL.md 在相关时加载、参考资料按需读取，这套分层的价值并不是形式优雅，而是让模型只在需要的时候吃到需要的信息。对长工作流和重知识型 Skill 来说，这直接决定了 token 成本和执行稳定性。
另一个容易被忽视的点是可组合和可移植。官方默认同一时间可能会有多个 Skill 并存，也默认同一个 Skill 可以被 Claude.ai、Claude Code 和 API 路径复用。也就是说，Skill 从一开始就不是“某个界面里的宏”，而是一种能力打包格式。
文档里最值得拿回去实践的，不是 frontmatter 字段说明，而是它要求你先定义 2 到 3 个具体用例。每个用例都要写清楚 Trigger、Steps 和 Result。这一步非常关键，因为 Skill 写得再漂亮，如果你说不清它在什么输入下触发、会走哪些步骤、最后交出什么结果，它就没有工程边界。
文档同时给了一组很实用的评估指标：触发率、工具调用效率、失败率和重复运行的一致性。它甚至明确提示这些更像目标值，而不是硬 SLA。我觉得这反而更真实，因为 Skill 的主要问题通常不是“功能不存在”，而是触发不稳定、输出不一致、用户需要频繁纠偏。
从这个角度看，Skill 设计更像产品设计，而不是文件格式设计。你不是在写一份 prompt，而是在定义一个可以被观察、被评估、被调参的运行单元。
官方对 frontmatter、正文和外部资产分别给了很清晰的责任边界，这点值得直接照搬。
第一层是触发层，也就是 frontmatter。这里最关键的不是字段齐全，而是 description 是否同时说清楚它做什么、何时该触发、用户会用哪些语言来表达需求。文档强调不要写得抽象，不要只写实现词汇，也不要出现 <、> 这类会引入 system prompt 风险的字符。这一层决定的是 undertrigger 和 overtrigger。
第二层是执行层，也就是 SKILL.md 正文。文档建议把步骤、校验门禁、示例和故障处理明确写出来，并把关键约束前置。这里的核心不是“让说明更完整”，而是让模型知道什么时候能继续、什么时候必须停下来、失败了该怎么转向。
第三层是证据层，也就是 references/、模板和脚本。官方反复强调，确定性校验优先写进 scripts/，长文档和规范放进 references/ 按需加载。这个分工很重要，因为自然语言擅长说明，但不擅长保证校验过程稳定；真正关键的检查，应该程序化。
这份文档后半部分关于测试、排障和分发，其实都在服务同一个观点：Skill 发布成功不代表 Skill 可用。真正该观察的是三个问题。
第一，它该触发的时候有没有触发，不该触发的时候有没有乱入。第二，它执行时有没有稳定完成目标，而不是每次都需要人手纠偏。第三，它相对“没有 Skill”到底节省了什么，是 token、工具调用轮次，还是用户解释成本。
文档给出的修复顺序也很实用：先改 description 处理触发问题，再改正文结构和错误处理稳定执行，必要时把校验移进脚本，最后再做有无 Skill 的对比回归。这是一个很工程化的顺序，因为它优先解决入口和主流程，而不是先打磨措辞。
Anthropic 这份“完整指南”真正教你的，不是怎么把 SKILL.md 写合法，而是怎么把一套工作方法做成能被触发、能被执行、也能被验证的资产。如果只学到了目录结构和 frontmatter 写法，基本还停留在包装层；如果把触发、门禁和证据三层责任分开管理，Skill 才算开始进入工程化状态。
我会用一个很简单的标准检验自己有没有真的吃透这份文档：当一个 Skill 出问题时，我能不能立刻判断它是触发层的问题、执行层的问题，还是证据层的问题。如果能，说明这份指南已经从“格式说明”变成了工程方法；如果不能，多半还在把 Skill 当 prompt 文件写。