本资料是一份关于如何编写和编辑 AI 智能体技能（skill）的参考文档，主题是用词汇与原则让技能变得可预测。
一、核心理念 技能存在的目的是从随机性系统中榨取确定性。可预测性指智能体每次运行都走同一流程（而非产出相同结果），这是根本优点，文中所有手段都服务于它。粗体术语在 GLOSSARY.md 中有定义。
二、调用方式 有两种选择，成本不同：
- 模型调用技能（model-invoked）：保留描述，智能体可自主触发，其他技能也可调用它（用户也可直接输入名称）。它带来上下文负担——描述每轮都在窗口中。做法：不设 disable-model-invocation，并写面向模型的描述，含丰富的触发措辞（如“当用户想要……、提到……”）。
- 用户调用技能（user-invoked）：描述从智能体可达范围移除，只有用户输入名称才能调用，其他技能也不能调用。零上下文负担，但消耗认知负担：用户须自己记住它的存在。做法：设置 disable-model-invocation: true，描述改为面向人——一行摘要，去掉触发列表。 仅当智能体需要自行触达该技能、或其他技能必须调用它时，才选模型调用；若只靠手动触发，就设为用户调用，不付上下文负担。当用户调用技能多到记不住时，可用一个路由器技能（router skill）：一个用户调用技能列出其他技能及何时使用。
三、撰写描述 模型调用描述有两项职责：说明技能是什么，并列出应触发的分支。每个词都增加上下文负担，因此描述比正文更需狠心精简：
- 把技能的主导词放在最前，描述是主导词发挥调用作用的地方。
- 每个分支一个触发条件。同一分支的同义改写属于重复（如“用 TDD 构建功能……要求测试先行的开发”是同一分支写两遍），应合并，只保留真正不同的分支。
- 删掉正文已含的身份说明。描述只保留触发条件，外加“当其他技能需要……”这类可达条款。
四、信息层级 技能由两类内容构成：步骤（steps）与参考（reference），可自由混合。核心决策是用哪种、各放在信息层级的哪一级（按智能体需要的即时程度排序）：
- 技能内步骤：SKILL.md 中有序的动作，属主层级。每个步骤以完成标准结尾，该标准须可检查（能否分辨完成与未完成），必要时须穷尽（如“每个修改过的模型都已处理”，而非“产出变更清单”）——模糊标准会招致过早完成。
- 技能内参考：SKILL.md 中的定义、规则或事实，按需查阅，常是合法的平级集合（如评审的每条规则同在一级），不算坏味道。本文档本身全是参考。
- 外部参考：从 SKILL.md 推到单独文件的参考，通过上下文指针触达，仅在指针触发时加载。范围从披露参考（技能内的兄弟文件，如 GLOSSARY.md）到完全外部、位于技能系统之外、任何技能都可指向的参考。 严苛的完成标准会驱动智能体更深入地做功课，无论技能有无步骤。推得太少，顶层膨胀；推得太多，隐藏了智能体真正需要的材料——这一张力就是全部决策。 渐进披露即沿层级下移（移出 SKILL.md 到链接文件），让顶层保持清晰。做法：技能文件夹中的 .md 链接文件，按其内容命名（本技能将完整定义披露到 GLOSSARY.md）。有些技能以多种方式使用，每种不同方式是一个分支——不同运行走不同路径。分支是最清晰的披露测试：每个分支都需要的就内联，只有部分分支才到达的就放到指针后。指针的措辞（而非其目标）决定智能体多可靠地触达材料。 层级决定一块内容放多深，共置决定它旁边放什么：一个概念的定义、规则与注意事项应放在同一标题下，而非散落各处。
五、何时拆分 粒度即技能划分的精细程度，每次切分都消耗两种负担之一，只有值得才拆。两种切分：
- 按调用拆分：当有独特的主导词应自行触发，或其他技能必须触达时，拆出模型调用技能。新描述常驻加载，付上下文负担，所以独立可达性必须值得。
- 按序列拆分：当后续步骤会诱使智能体草率完成当前步骤（过早完成）时，把一段步骤拆开。让后续步骤不在视野内，鼓励智能体在当前任务上多下功夫。
六、精简 每个含义只保留单一事实来源：一个权威位置，改行为只需改一处。逐行检查相关性：是否仍与技能所做相关？然后逐句寻找空操作：对每句单独做空操作测试，失败就整句删除，而非修剪词语。要狠——多数不合格的散文应删掉，而非重写。
七、主导词（leading word） 主导词是模型预训练中已有的紧凑概念，智能体运行技能时用它思考（如 lesson、fog of war、tracer bullets）。在文中反复出现（不必然——强主导词可能只需一次），它积累分布式定义，用最少 token 锚定一整片行为区域，调动模型已有先验。它在两方面服务可预测性：在正文中锚定执行——词一出现，智能体每次就采取同样行为；在描述中锚定调用——同一词出现在提示、文档、代码中时，智能体把共享语言与该技能关联，更可靠地触发。应寻找机会用主导词重构技能：三处拼写的三元组（重复）、用一句话比划一个想法的描述，都是可折叠成单个 token 的段落。示例：“快速、确定、低开销”重述同一品质，改为 tight（紧凑循环）；“你相信的循环”改为 red，把模糊门槛变成二元可观察状态（循环在 bug 上变红，或不变红）。双赢：更少 token，更锐利的思考挂钩。
八、失败模式 用于诊断用户可能遇到的技能问题：
- 过早完成：步骤未真正完成就结束，注意力滑向“已完成”。防御顺序：先锐化完成标准（廉价、局部）；只有当标准无法再清晰且观察到草率时，才通过拆分（序列切分）隐藏后续步骤。
- 重复：同一含义出现在多处，耗费维护与 token，并让该含义在层级中的突出度超过真实等级。
- 沉积：陈旧层次因“加着安全、删着危险”而积累，是缺乏精简纪律的技能默认命运。
- 臃肿：技能就是太长，即使每行都有效且唯一，损害可读性与可维护性并浪费 token。解药是层级：把参考披露到指针后，按分支或序列拆分，让每条路径只携带所需内容。
- 空操作：模型默认已遵循的句子，说了等于没说。测试：相比默认是否改变行为？弱主导词（在模型已经有点彻底时说“要彻底”）是空操作，修法是换更强的词（relentless），而非换技术。
- 否定式指令：用禁止来引导会适得其反，如“不要想大象”反而点名了大象。应正面提示：陈述目标行为，让被禁行为根本不出现；只在无法正面表述且作为硬性护栏时保留禁止，且同时给出替代做法。
本文档为纯参考型技能，未提供具体安装命令、收费或平台信息。