writing-great-skills 是一份用于编写和编辑技能（skill）的参考文档，其核心目标是让技能具备可预测性——即智能体每次运行都采用相同流程，而非产出相同结果。文档指出，可预测性是根本美德，下文所有手段都服务于它。文中加粗术语在 GLOSSARY.md 中有完整定义。
一、调用方式 技能有两种调用选择，各自付出不同成本：
- 模型调用技能保留描述，智能体可自主触发，其他技能也能触达（用户仍可手动输入名称）。它带来上下文负载——描述每轮都占据窗口。机制：省略 disable-model-invocation，并撰写面向模型的描述，包含丰富的触发措辞（如“当用户想要……、提到……”）。
- 用户调用技能从智能体可及范围中移除描述：只有用户手动输入名称才能调用，其他技能无法触达。零上下文负载，但消耗认知负载——用户自己必须记住它存在。机制：设置 disable-model-invocation: true；描述转为面向人类——一行摘要，去掉触发列表。 仅当智能体必须自行触达该技能，或其他技能必须触达时才选模型调用。若只靠手动触发，就设为用户调用，不付上下文负载。当用户调用技能多到记不住时，可用路由技能（router skill）来缓解：一个用户调用技能，列出其他技能及各自适用时机。
二、撰写描述 模型调用描述承担两项任务——说明技能是什么，并列出应触发的分支。每个词都增加上下文负载，因此描述比正文更需要严格修剪：
- 前置技能的主导词——描述是主导词发挥调用作用的地方。
- 每个分支一个触发。重命名同一分支的同义词属于重复，应合并，只保留真正不同的分支。
- 删除正文已有的身份信息。描述只保留触发，以及任何“当其他技能需要……”的触达子句。
三、信息层级 技能由两类内容构成——步骤与参考——可自由混合。核心决策是用哪种、各自位于信息层级何处。该层级按智能体对材料的即时需要程度排序：
- 技能内步骤：SKILL.md 中的有序动作，属主要层级。每个步骤以完成标准收尾，即告诉智能体工作已完成的条件。标准应可检查，必要时穷尽（如“每个被修改的模型都已处理”，而非“产出变更列表”），模糊标准会招致过早完成。
- 技能内参考：SKILL.md 中的定义、规则或事实，按需查阅。常为合法的扁平同级集合，并非坏味道。本技能全部为参考。
- 外部参考：被推出 SKILL.md 到单独文件的参考，通过上下文指针触达，仅在指针触发时加载。 要求严格的完成标准会驱动深入的基础工作，无论技能是否有步骤，因为“每条规则都已应用”约束扁平参考，正如“每个步骤都已完成”约束序列。 推得太少，顶层臃肿；推得太多，隐藏了智能体真正需要的材料。这一张力就是全部决策所在。 渐进式披露即沿层级下移——从 SKILL.md 移入链接文件——以保持顶层可读。机制：技能文件夹中的链接 .md 文件，按内容命名（本技能将完整定义披露到 GLOSSARY.md）。有些技能以多种方式使用，每种不同方式即一个分支——不同运行走不同路径。分支是最清晰的披露测试：每个分支都需要的内联，只有部分分支触达的推到指针后。上下文指针的措辞而非其目标，决定智能体何时、多可靠地触达材料。 层级决定某块内容位于多深，共置则决定它旁边放什么：将概念的定义、规则和注意事项放在同一标题下，而非分散，这样读一部分会带出邻近部分。
四、何时拆分 粒度是划分技能的精细程度，每次切分都消耗两种负载之一，因此只在切分值得时才拆。两种切分：
- 按调用拆分：当有独特主导词应自行触发，或其他技能必须触达时，拆出模型调用技能。新描述始终加载，需付上下文负载，因此独立触达必须值得。
- 按序列拆分：当后续步骤（某步骤完成后的步骤）诱使智能体匆忙完成当前步骤（过早完成）时，拆出一段步骤。让它们不可见，鼓励智能体在当前任务上做更多基础工作。
五、修剪 每个含义保持单一事实来源：一个权威位置，改行为只需改一处。 检查每一行是否相关：它是否仍与技能所做之事有关？ 然后逐句而非逐行寻找无效语句：对每个句子单独做无效测试，失败时删除整句而非修剪词语。要激进——大多数失败的散文应删除，而非重写。
六、引导词 引导词是模型预训练中已存在的紧凑概念，智能体运行技能时用它思考（如 lesson、fog of war、tracer bullets）。在文中重复（强引导词可能只需一次），它积累分布式定义，用最少 token 锚定整片行为区域，调动模型已有先验。 它在两方面服务可预测性。正文中锚定执行：词出现时智能体每次都采取相同行为。描述中锚定调用：当同一词出现在提示、文档和代码中，智能体将共享语言链接到技能，更可靠地触发。 寻找用引导词重构技能的机会。三处拼写的三元组（重复）、用一句话指向一个想法的描述——都是可折叠为单个 token 的段落。例如：“fast, deterministic, low-overhead”可折叠为 tight；“a loop you believe in”可折叠为 red。收益双重：更少 token，更锐利的思考挂钩。假设每个技能都携带可被引导词退休的重述——去找出来。
七、失败模式 用于诊断用户可能遇到的技能问题：
- 过早完成：步骤未真正完成就结束，注意力滑向“已完成”。防御按序：先锐化完成标准（便宜、局部）；仅当标准不可约地模糊且观察到匆忙时，才通过拆分隐藏后续步骤（序列切分）。
- 重复：同一含义出现在多处。增加维护和 token 成本，并夸大该含义在层级上的真实地位。
- 沉积：陈旧层因添加感觉安全、删除感觉冒险而沉淀。任何缺乏修剪纪律的技能的默认命运。
- 蔓延：技能单纯太长，即使每行都活跃且独特。损害可读性和可维护性，浪费 token。解药是层级：将参考披露到指针后，按分支或序列拆分，使每条路径只携带所需。
- 无效语句：模型默认已遵守的行，付负载却什么也没说。测试：它是否改变相对默认的行为？弱引导词是无效语句；修复是更强的词（relentless），而非不同技术。
- 否定：用禁止来引导会适得其反：不要想大象反而命名了大象，使其更易得。应正面提示——陈述目标行为，使被禁行为从未被说出；仅保留无法正面表述的硬护栏，即便如此也配以该做什么。