writing-great-skills

有一种技能可以从随机系统中梳理出确定性。可预测性——Agent 每次运行都采用相同的 过程，而不是产生相同的输出——是最根本的特质；下文每个杠杆都是为它服务的。

加粗术语在 GLOSSARY.md 中有定义；请在那里查看完整含义。

调用方式

有两种选择，成本各不相同：

• 模型调用的技能需要保留一个描述，这样 Agent 就可以自主调用 它，_而且_其他技能也能找到它（你仍然可以手动输入其名称）。它会增加上下文负载——描述每轮都会占据上下文窗口。实现方式：省略 disable-model-invocation，并编写面向模型的描述，使用丰富的触发语句（“当用户想要……、提到……时使用”）。
• 用户调用的技能不会向 Agent 暴露描述：只有你手动输入其名称才能调用——其他技能也无法调用。它的上下文负载为零，但会增加认知负载：你 就是索引，必须记住它的存在。实现方式：设置 disable-model-invocation: true；此时 description 面向人类——使用单行摘要，不包含触发条件列表。

只有在 Agent 必须自行找到该技能，或另一个技能必须找到它时，才选择模型调用。如果它始终只会手动触发，就将其设为用户调用，并且不产生任何上下文负载。

当用户调用的技能多到超出你的记忆范围时，可以通过路由技能解决这些累积的认知负载：这是一个用户调用的技能，列出其他技能以及何时应找到每个技能。

编写描述

模型调用的描述承担两项任务——说明技能是什么，并列出应触发它的分支。每个词都会增加上下文负载，因此描述比正文更需要严格删减：

• 将技能的引导词前置——描述正是技能发挥调用作用的地方。
• 每个分支只设置一个触发条件。 只是为单个分支换名称的同义词属于重复——“使用 TDD 构建功能……要求采用测试先行开发”其实是同一个分支写了两次。将它们合并；只保留真正不同的分支。
• 删除正文中已有的身份信息。 将描述限定为触发条件，以及任何“当另一个技能需要……”之类的调用子句。

信息层级

技能由两类内容构成——步骤和参考内容——两者可自由组合：技能可以全是步骤、全是参考内容，或两者兼有。核心决策是使用哪一类，以及每类内容位于信息层级的哪一层；该层级按 Agent 对材料的即时需求程度排序：

1. 技能内步骤——SKILL.md 中的一项有序操作，属于主层级：Agent 按顺序执行的内容。每个步骤都以一项完成标准收尾，即告知 Agent 工作已完成的条件。标准应当_可核查_（Agent 能否分辨已完成与未完成？），必要时还要做到_穷尽_（“所有已修改模型均已纳入”，而不是“生成变更列表”）——模糊标准会诱发过早完成。
2. 技能内参考——SKILL.md 中的定义、规则或事实，供按需查阅。它通常可以合理地采用平级集合（评审的每条规则都位于同一级），这是妥当的安排，并非坏味道。此技能全部由参考内容构成。
3. 外部参考——从 SKILL.md 移至独立文件的参考内容，通过上下文指针访问，且仅在指针触发时加载。（其范围从_已披露_参考内容——例如 GLOSSARY.md 这样的同级文件，仍属于技能的一部分——一直延伸至完全外部参考内容，后者位于技能系统之外，且任何技能都可以指向它。）

严格的完成标准会促成充分的调查工作——即 Agent 在工作过程中进行的深入挖掘——无论技能是否包含步骤；正如“每个步骤都已完成”约束步骤序列，“每条规则都已应用”也会约束平级参考内容。

如果将内容下沉得太少，顶层就会臃肿；下沉过多，又会隐藏 Agent 实际需要的材料。整个决策就在于平衡这种张力。

渐进式披露是沿层级下沉的操作——从 SKILL.md 移入链接文件——从而让顶层保持清晰易读。其运作方式是：在技能文件夹中放置一个链接的 .md 文件，并按其承载的内容命名（本技能将完整定义披露至 GLOSSARY.md）。有些技能有多种使用方式，每种不同方式都是一个分支——不同运行会沿技能的不同路径执行。分支是检验披露是否恰当的最清晰方法：将每个分支都需要的内容内联，只有部分分支会访问的内容则置于指针之后。决定 Agent 何时以及以多高可靠性访问材料的，是上下文指针的_措辞_，而不是其目标。

当层级决定某项内容应下沉_多远_时，共置决定它确定位置后_与什么并置_：将概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样阅读一个部分时，也会自然读到其邻近内容。

何时拆分

粒度决定了技能被划分得多细，而每次切分都要消耗两种负荷之一，因此仅在切分值得时才应拆分。切分方式有两种：

• 按调用方式——当有一个应当单独触发该技能的明确触发词，或另一个技能必须访问它时，将模型调用型技能拆分出来。新技能中始终加载的描述会增加上下文负载，因此，这种独立可访问性必须值得付出该代价。
• 按执行顺序——如果后续步骤（某一步的完成后的步骤）诱使 Agent 抢先完成当前步骤（过早完成），就拆分这一系列步骤。不显示后续步骤，可以促使 Agent 在当前任务上投入更多调查工作。

精简

让每项含义都只有一个单一事实来源：集中存放在一个权威位置，从而只需编辑一处即可更改行为。

逐行检查相关性：它是否仍与技能的作用有关？

然后逐句而非仅逐行查找无效内容：单独对每个句子执行无效内容测试；如果某句未通过，就删除整句，而不是仅修剪其中的词语。应果断处理——大多数未通过测试的文字都应删除，而不是改写。

引导词

引导词是模型预训练中已经存在的一个凝练概念，Agent 在运行技能时借此思考（例如 课程、战争迷雾、曳光弹）。它会在全文中反复出现（但并非必须如此——一个强有力的引导词可能只需出现一次），逐渐累积成分布式定义，并利用模型已有的先验，以最少的词元锚定一整片行为区域。

它在两个方面提升可预测性。在正文中，它锚定_执行_：每当这个词出现时，Agent 都会采取相同的行为。在描述中，它锚定_调用_：当同一个词也出现在你的提示词、文档和代码中时，Agent 会将这种共同语言与技能关联起来，更可靠地启动技能。

寻找重构技能以使用引导词的机会。在三处完整展开的三元结构（重复），或用一句话指向一个概念的描述——每一种都亟待压缩成单个词元。例如：

• “快速、确定性、低开销” -> 紧凑——把一个在阶段中反复重述的品质化为单个预训练词元（一个 紧凑 循环）。
• “你信得过的循环” -> 红——将模糊的门槛转换为二元可观测状态（循环遇到缺陷时会变 红，否则不会）。

这样会获得双重收益：词元更少，而且 Agent 有了更锋利的挂钩，可以据此展开思考。假设每项技能都带有可由引导词淘汰的重复表述——去找出它们。

失败模式

使用以下模式诊断用户可能遇到的技能问题。

• 过早完成——在步骤真正完成之前就收尾，注意力滑向“完成”状态。防御措施按顺序如下：先细化完成标准（成本低、局部）；只有在标准无论如何都仍显模糊，而且 你确实观察到抢跑时，才通过拆分来隐藏完成后的步骤（序列截断）。
• 重复——相同含义出现在多个地方。它会增加维护负担和词元消耗，并让某个含义在阶梯上的显著程度超过其真实位次。
• 沉积——因为增加内容感觉安全、删除内容感觉有风险而层层堆积的陈旧内容。任何缺少修剪机制的技能最终都会如此。
• 蔓延——技能单纯过长，即便每行都仍有效且各不相同。它会损害可读性和可维护性，并浪费词元。解法是阶梯：把参考内容置于指针之后，并按分支或序列拆分，让每条路径只承载所需内容。
• 空操作——模型默认已经遵守的一行，让你付出加载成本却什么也没说。检验标准：相较默认行为，它能改变行为吗？弱引导词（当 Agent 本来就较为周全时使用 做到周全）就是空操作；修复方法是换用更强的词（锲而不舍），而不是另一种技术。
• 否定式引导——通过禁止来引导会适得其反：_不要想大象_会把大象说了出来，使其更容易被想到，而不是更难。请用正向方式提示——陈述目标行为，使被禁止的行为根本不会被提及；仅当某项禁止无法正向表述时，才将其保留为硬护栏，即便如此，也要同时说明应该改做什么。