RollRollRoll Writing Great Skills
Skill 的价值是从随机系统中约束出可预测性：每次运行遵循相同过程，而不是产生相同输出。下面所有手段都服务于这一根原则。
正文中的粗体术语均在 术语表 中定义。需要判断概念边界或诊断失败模式时，读取对应条目。
调用方式
在两种方式之间明确选择：
- 模型调用型 Skill 保留模型可见的描述，让 agent 能自主触发，也让其他 Skill 能调用。代价是描述在每轮占用上下文负载。省略
disable-model-invocation，并在描述中写清真正不同的触发分支。 - 用户调用型 Skill 只由人类显式选择，模型和其他 Skill 都不能主动调用。它不占模型上下文，却增加用户必须记住它的认知负载。设置
disable-model-invocation: true，并把描述写成人类可读的一行摘要。
只有模型必须自主发现，或其他 Skill 必须调用时，才选择模型调用型。用户调用型数量多到难以记忆时，用一个用户调用型的路由 Skill列出各 Skill 的用途，而不是把它们全部改成模型调用型。
编写描述
模型调用型 Skill 的描述同时说明“它是什么”和“哪些分支应触发它”。逐句压缩：
- 把最能支配行为的引导词放在前面。
- 每个真实分支只保留一个触发条件；同一分支的同义改写属于重复。
- 删除正文已经承担的身份说明，只保留触发条件，以及其他 Skill 需要调用它时的可达性说明。
描述中的每个词都永久增加上下文负载，因此比正文更需要剪枝。
信息层级
Skill 由步骤和参考资料组成，两者可以单独存在，也可以混合。按照 agent 需要信息的即时程度排列：
- Skill 内步骤：
SKILL.md中按顺序执行的动作。每一步都以可检查的完成判据结束；需要穷尽时，判据要明确要求覆盖全部对象，防止过早完成。 - Skill 内参考资料：运行时按需查询的定义、规则和事实。平级规则可以保持平铺，不必强造顺序。
- 披露的参考资料：移出
SKILL.md、通过上下文指针按条件加载的文件，或位于 Skill 外的外部参考资料。
把只服务部分分支的内容移到指针后，形成渐进式披露；所有分支都需要的内容保留在正文。指针的措辞决定 agent 何时读取目标，必读资料若经常漏读，先强化指针，再考虑移回正文。
层级决定信息放多深，共置决定同一层里哪些内容放在一起。让一个概念的定义、规则和例外相邻出现，避免读到半个概念。
判断是否拆分
粒度越细，付出的负载越高。只在以下切分能改善可预测性时拆分：
- 按调用拆分：当新 Skill 有独立引导词、应被单独触发，或必须由其他 Skill 调用时，拆成模型调用型 Skill。独立可达性的价值必须足以抵偿新增上下文负载。
- 按顺序拆分：当当前步骤的完成判据难以进一步锐化，而且观察到可见的后续步骤持续诱发过早完成时，用真正的上下文边界隐藏后续步骤。
先锐化完成判据；只有失败真实存在且判据仍不可避免地模糊时，才用拆分解决。
剪枝
让每个行为含义只有一个单一事实来源。
逐行检查相关性：它现在是否仍影响 Skill 的目标行为？再逐句执行无效指令测试：如果删掉后模型默认仍会做同样的事，这句话就没有承担行为作用，应整句删除。
定期清除已经失效的沉积。如果每一行都仍然有效且唯一，但主体依旧难以阅读，就是蔓延；沿信息层级披露参考资料，或按分支和顺序拆分。
使用引导词
引导词是模型预训练中已经存在、能以很少 token 激活一整片行为的概念，例如“苏格拉底式”“红灯”“迷雾”。优先选择已有概念；自造词需要额外定义，收益更低。
引导词同时提高两处可预测性：
- 在正文中锚定执行，让 agent 每次看到它都调用相近的行为先验。
- 在描述中锚定调用；当用户提示、文档和代码也使用同一词时，Skill 更容易被正确触发。
寻找反复解释同一行为的段落，把它们压缩成一个足够强的引导词。每次压缩都必须通过无效指令测试：弱到不改变默认行为的词没有价值。
诊断失败模式
- 过早完成：步骤在真正达标前结束。先让完成判据变得清晰、可检查；只有判据本质上模糊且确实发生抢跑时，才隐藏后续步骤。
- 重复：同一含义存在多个权威位置。合并为单一事实来源；引导词可以重复 token，但不要重复解释。
- 沉积：旧规则因为只增不删而累积。用相关性检查移除失效层。
- 蔓延：内容全部有效却仍然过长。用信息层级、分支或顺序切分降低单次加载量。
- 无效指令：一句话没有改变模型默认行为。删除它，或换成真正能改变行为的强引导词。
- 否定式引导：禁令把不希望出现的行为带进上下文。直接描述目标行为；确实需要硬约束时，同时给出要采取的正向动作。
完成一次编写或审查时，逐项应用上述原则，并确认每个保留的描述触发、步骤、参考资料和失败模式处理都有可解释的行为作用。