writing-great-skills

name	writing-great-skills
description	编写和编辑高质量 skills 的参考指南 — 使 skill 行为可预测的词汇和原则。
disable-model-invocation	true

一个 skill 的存在是为了从随机系统中提取确定性。可预测性 —— 即 agent 每次运行时采取相同的流程，而非产生相同的输出 —— 是根本美德；以下每个杠杆都为此服务。

加粗术语在 GLOSSARY.md 中有定义；可查阅获取完整含义。

调用方式

两种选择，付出不同的代价：

• 模型调用 skill 保留 description，因此 agent 可以自主触发它，并且其他 skills 也可以触达它（你也仍然可以手动输入其名称）。它会产生上下文负载 —— description 每轮都留在窗口里。实现机制：省略 disable-model-invocation，并编写一个面向模型的 description，包含丰富的触发短语（"当用户想要……、提及……时使用"）。
• 用户调用 skill 将 description 从 agent 的触达范围中移除：只有你手动输入其名称才能调用它 —— 其他 skill 也无法触达它。零上下文负载，但它消耗认知负载：你是必须记住它存在的索引。实现机制：设置 disable-model-invocation: true；description 变为面向人类的 —— 一句摘要，去掉触发列表。

只有当 agent 必须自行触达该 skill，或其他 skill 必须触达它时，才选择模型调用。如果它只需手动触发，则设为用户调用，不付出任何上下文负载。

当用户调用 skills 多到你记不住时，积累的认知负载可以通过一个路由 skill 来解决：一个用户调用的 skill，列出其他 skills 以及何时使用它们。

编写 description

模型调用的 description 做两件事 —— 说明该 skill 是什么，并列出应触发它的分支。每个词都会增加上下文负载，所以 description 比正文更应该被严格修剪：

• 将 skill 的主导词前置 —— description 是它发挥调用作用的地方。
• 每个分支一个触发器。 给单个分支换不同说法的同义词属于重复 —— "使用 TDD 构建功能……要求测试优先开发" 是一个分支写了两次。收拢它们；只保留真正不同的分支。
• 删除正文中已有的身份信息。 将 description 限制为触发器，以及任何"当另一个 skill 需要……"的触达子句。

信息层级

一个 skill 由两种内容类型构成 —— 步骤和参考 —— 它们可以自由混合：一个 skill 可以全是步骤、全是参考，或两者兼有。核心决策是使用哪种以及每种在信息层级上的位置，该层级按 agent 对材料需求的紧急程度排序：

1. skill 内步骤 —— SKILL.md 中的有序操作，是最主要的层级：agent 按顺序做什么。每个步骤以一个完成标准结束，即告诉 agent 工作完成的条件。使其可检查（agent 能否区分已完成和未完成？），并在重要时做到穷尽（"每个修改过的模型都已覆盖"，而非"生成一个变更列表"）—— 模糊的标准会引发过早完成。
2. skill 内参考 —— SKILL.md 中的定义、规则或事实，按需查阅。通常是一组合法的扁平同级项（例如一次 review 的所有规则处于同一层级）—— 这是一种合理的安排，不是异味。本 skill 就是纯参考。
3. 外部参考 —— 从 SKILL.md 中移出到单独文件的参考，通过上下文指针触达，仅在指针被触发时加载。（范围从已披露参考 —— 如 GLOSSARY.md 这样的同级文件，仍属于该 skill 的一部分 —— 到完全的外部参考，存在于 skill 系统之外，任何 skill 都可以指向它。）

一个严格的完成标准驱动彻底的实地探查 —— agent 在工作过程中的深入挖掘 —— 无论 skill 是否有步骤，因为"每条规则都已应用"绑定扁平参考，正如"每个步骤都已完成"绑定一个顺序一样。

推得太少则顶层膨胀；推得太多则隐藏了 agent 实际需要的材料。这种张力就是整个决策。

渐进式披露是沿层级向下移动 —— 从 SKILL.md 中移出到链接文件 —— 使顶层保持清晰可读。实现机制：skill 文件夹中一个链接的 .md 文件，以其包含的内容命名（本 skill 将其完整定义披露到 GLOSSARY.md）。有些 skills 以不止一种方式使用，每种不同的使用方式是一个分支 —— 不同次运行走 skill 的不同路径。分支是最清晰的披露测试标准：将每个分支都需要的材料内联，将只有某些分支需要的材料放到指针后面。上下文指针的措辞，而非其目标，决定了 agent 触达该材料的时机和可靠性。

层级决定了一段内容放在多远的位置，而就近原则决定了它旁边放什么：将概念的定义、规则和注意事项放在同一个标题下，而非散落各处，这样读一处就能连带看到其周边内容。

何时拆分

粒度指你分割 skills 的细密程度，每次切割消耗两种负载之一，因此仅在切割值得时才拆分。两种切割方式：

• 按调用 —— 当你有一个独特的主导词应独立触发时，或另一个 skill 必须触达它时，拆分出一个模型调用 skill。你为新产生的始终加载的 description 付出上下文负载，所以这种独立触达能力必须值得。
• 按顺序 —— 当后续步骤（一个步骤的完成后步骤）诱使 agent 仓促完成当前步骤（过早完成）时，拆分一段步骤序列。将它们移出视野鼓励 agent 对当前任务做更多实地探查。

修剪

将每个含义保留在单一事实来源中：一个权威位置，这样改变行为只需修改一处。

检查每一行是否具备相关性：它是否仍然影响该 skill 的行为？

然后逐句而非逐行地猎杀无效操作：对每个句子单独执行无效操作测试，当句子未通过时，删除整个句子，而非从中修剪词语。要激进 —— 大多数未通过的文本应该删除，而非重写。

主导词

主导词是一个紧凑的概念，已存在于模型的预训练中，agent 在运行该 skill 时用它来思考（例如课程、战争迷雾、示踪子弹）。它在文本中反复出现（尽管不一定 —— 一个强有力的主导词可能只需出现一次），积累出一种分布式定义，通过调用模型已有的先验知识，以最少的 token 锚定整个行为区域。

它两次服务于可预测性。在正文中它锚定执行：每次该词出现时，agent 都会采取相同的行为。在 description 中它锚定调用：当同一个词出现在你的提示语、文档和代码中时，agent 将该共享语言与 skill 关联起来，更可靠地触发它。

寻找机会将 skills 重构为使用主导词。在三处地方展开的三元组（重复），一个用一整句话来暗示一个概念的 description —— 每一处都是恳请收拢为单个 token 的段落。示例如下：

• "快速、确定性、低开销" -> 紧凑 —— 一个在某个阶段被反复重述的特性 —— 收拢为一个预训练词（一个紧凑的循环）。
• "一个你相信的循环" -> 红色 —— 将模糊的门禁转换为二进制可观察状态（循环在 bug 上变红，或不变）。

你赢两次：更少的 token，以及 agent 用来锚定其思考的更锐利的钩子。假定每个 skill 都携带着可以被主导词消除的重述 —— 去找到它们。

失败模式

用这些来诊断用户在使用 skill 时可能遇到的问题。

• 过早完成 —— 在真正完成之前就结束一个步骤，注意力滑向完成状态。防御手段，按顺序：首先锐化完成标准（成本低，局部修改）；仅当标准不可简化的模糊且你观察到仓促行为时，通过拆分（按顺序切割）隐藏完成后步骤。
• 重复 —— 同一含义出现在不止一个地方。增加维护成本和 token 消耗，并将含义在层级上的显著度虚高到超出其实际排名。
• 沉积 —— 因为增加感觉安全而删除感觉危险，导致陈旧层堆积。任何没有修剪纪律的 skill 的默认命运。
• 蔓延 —— skill 过于冗长，即使每一行都是活的且独特的。损害可读性和可维护性，浪费 token。解药是层级：将参考披露到指针后面，并按分支或顺序拆分，使每条路径只携带其所需的内容。
• 无效操作 —— 模型默认就会遵守的行，你付出负载却说不出任何效果。测试标准：它是否改变了默认行为？一个弱主导词（当 agent 已经大致做到时要求彻底）就是无效操作；修复方法是用更强烈的词（毫不留情），而非换一种技巧。
• 否定 —— 通过禁止来引导会适得其反：不要想大象 命名了大象，使其更易被调用，而非更少。使用积极措辞 —— 陈述目标行为，使被禁止的行为从未被提及；保留禁止性表述仅作为一种无法用积极方式表达的硬护栏，即便如此，也要成对提供替代行为。