Skill 写作指南

这个指南解决什么问题

很多人把技能（Skill）写成一段更长的提示词：把所有背景知识塞进 SKILL.md，靠模型临场发挥。结果要么文件膨胀到上千行、触发和加载全乱，要么输出时好时坏——同样的需求换个问法就翻车。根因是把「写指令」和「设计决策系统」混为一谈。本指南把技能当作一个分层的决策系统来设计，给出可执行的拆解、编排和验证流程，目标是让技能「跑起来稳定」而不是「读起来合理」。

核心能力与工作方式

三层架构，职责分离：

• SKILL.md 是编排层：只做决策路由，决定「什么时候加载什么」，控制在 300 行以内（红线 500 行），用表格和决策树而不是大段文字。
• references/ 是知识层：每个文件解决一个具体问题，有明确的加载条件，包含规则、正反例、反模式和检查清单。
• scripts/ 是工具层：只封装每次执行结果必须一样的确定性操作，如格式转换或精确计算。

从零创建的六步流程：

1. 需求分析：用「专家直觉、足够复杂、反复出现」三标准判断值得做成技能。
2. 知识拆解：列出 AI 不知道但必须做对的知识点，按加载条件分组为 5–15 个 reference 文件。
3. 编排层编写：SKILL.md 只写路由，每个分支明确加载哪个 reference 或调用哪个 script。
4. 知识模块编写：按统一结构写，至少包含一组好/坏对比示例。
5. 工具决策：判断哪些操作该脚本化，参考决策树。
6. 质量验证：用评测用例和 20 项检查清单逐项核对。

优化已有技能时，先做五维诊断（触发、架构、知识、工具、质量），再对症下药：触发不准就重写 description，编排层堆砌就提取知识到 reference，输出不稳定就封装脚本。

适用边界与注意点

• 本指南面向中高复杂度的领域技能。简单任务（一步到位的格式转换）不必走完整流程。
• 自由度要匹配任务性质：做错代价越高自由度越低，正确做法越多自由度越高。创造性任务给原则，确定性任务给脚本。
• 常见反模式包括 reference 互相引用、SKILL.md 与 reference 内容重复、把触发条件写进 body（触发后才加载，已经晚了）。
• 指南内置了评审用的检查清单和反模式目录，适合在发布前做质量把关。