AGENT SKILL

writing-great-skills

出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。

License 许可
MIT
最近更新
2026-07-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
writing-great-skills
description
出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。
disable-model-invocation
true

02 资源文件 2

03 SKILL.md 正文

技能的作用是从随机系统中驯服出确定性。可预测性——智能体每次运行都采用相同的 过程,而不是生成相同的输出——是最根本的品质;下文每个杠杆都为它服务。

粗体术语 的定义位于 GLOSSARY.md;请在那里查阅完整含义。

调用

有两种选择,各自以不同成本作为交换:

  • 模型调用 技能会保留 description,因此智能体可以自主触发它,而且 其他技能也能触达它(你仍然可以输入其名称)。它会产生 上下文负荷——description 每轮都停留在窗口中。机制:省略 disable-model-invocation,并编写一段面向模型、包含丰富触发措辞的 description(“当用户想要……、提到……时使用”)。
  • 用户调用 技能会让智能体无法触达 description:只有你输入其名称才能调用它——其他技能也无法调用。上下文负荷为零,但会消耗 认知负荷:你 就是必须记住该技能存在的索引。机制:设置 disable-model-invocation: true;description 变为面向人的单行摘要,并移除触发条件列表。

仅当智能体必须自行触达该技能,或其他技能必须触达它时,才选择模型调用。如果它只会被手动触发,请将其设为用户调用,从而不承担上下文负荷。

当用户调用技能多到超出你的记忆能力时,可以用 路由技能 解决累积的认知负荷:使用一个用户调用技能列出其他技能及其适用时机。

编写 description

模型调用技能的 description 承担两项职责——说明技能是什么,并列出应触发它的 分支。每个词都会增加 上下文负荷,因此 description 比正文更需要严格精简:

  • 将技能的引领词前置——description 正是引领词发挥调用作用的地方。
  • 每个分支只设一个触发条件。 用同义词重新命名单个分支属于 重复——“使用 TDD 构建功能……要求测试优先开发”是将同一个分支写了两次。将它们合并;只保留真正不同的分支。
  • 删去正文中已有的身份说明。 description 只保留触发条件,以及任何“当其他技能需要……”的触达条款。

信息层级

技能由两种可自由组合的内容类型构成——步骤 和 参考资料:技能可以全部由步骤组成、全部由参考资料组成,或兼有两者。核心决策是选用哪一种,以及各自位于 信息层级 的什么位置;这架阶梯按照智能体需要材料的即时程度排序:

  1. 技能内步骤——SKILL.md 中的有序操作,也是主要层级:智能体按顺序做什么。每个步骤都以一项 完成标准 结束,也就是告诉智能体工作已经完成的条件。让标准 可检查(智能体能否区分完成与未完成?),并在重要之处要求 完整(“每个修改过的模型均已纳入”,而不是“生成变更列表”)——含糊的标准会诱发 过早完成。
  2. 技能内参考资料——SKILL.md 中按需查阅的定义、规则或事实。通常是一组合理的扁平同级内容(评审的每条规则都位于同一层级)——这是一种良好安排,而不是异味。本技能全部由参考资料组成。
  3. 外部参考资料——从 SKILL.md 移到独立文件中的参考资料,通过 上下文指针 触达,并且仅在指针触发时加载。(范围涵盖 渐进披露的 参考资料——例如 GLOSSARY.md 这样的同级文件,仍属于技能的一部分——直至完全位于技能系统之外、任何技能都可指向的 外部参考资料。)

要求严格的完成标准会驱动彻底的 幕后执行工作——智能体在工作中自行查找与执行的内容——无论技能是否包含步骤,因为“应用每条规则”对扁平参考资料的约束,正如“完成每个步骤”对顺序的约束。

下移得太少,顶部会膨胀;下移得太多,又会隐藏智能体实际需要的材料。这种张力就是整个决策的核心。

渐进式披露 是沿阶梯下移——从 SKILL.md 移到链接文件中——让顶部保持清晰易读。机制:在技能文件夹中放置一个链接的 .md 文件,并按其所含内容命名(本技能将完整定义披露到 GLOSSARY.md)。有些技能有不止一种使用方式,每种独特方式都是一个 分支——不同运行会在技能中采用不同路径。分支是最清晰的披露检验:内联每个分支都需要的内容,将只有部分分支会触达的内容放到指针之后。决定智能体何时触达材料以及触达有多可靠的是 上下文指针 的 措辞,而不是它的目标。

阶梯决定一项内容位于 多低的位置,共置 则决定它到达该位置后 与什么内容相邻:将概念的定义、规则和注意事项放在同一标题下,而不是让它们四处散落,这样阅读一部分时也会一并看到相邻内容。

何时拆分

粒度 是技能划分的细致程度,每次切分都会消耗两种负荷之一,因此只有在切分物有所值时才进行拆分。切分有两种:

  • 按调用切分——如果有一个独特的 引领词 应当独立触发某项技能,或其他技能必须触达它,就拆出一个 模型调用 技能。你会为新增且始终加载的 description 承担 上下文负荷,因此这种独立触达必须物有所值。
  • 按顺序切分——如果尚未执行的步骤(某个步骤的 完成后步骤)会诱使智能体仓促处理眼前步骤(过早完成),就拆分一连串 步骤。将后续步骤移出视野,会鼓励智能体针对当前任务做更多 幕后执行工作。

精简

将每个含义保存在一个 单一事实来源 中:只放在一个权威位置,这样改变行为时只需编辑一处。

检查每一行的 相关性:它是否仍与技能所做之事相关?

然后逐句查找 无效指令,而不只是逐行检查:单独对每个句子运行无效指令检验;如果句子未通过,就删除整个句子,而不是删减其中几个词。要大胆行动——大多数未通过的文本都应删除,而不是重写。

引领词

引领词 是已经存在于模型预训练中的紧凑概念,智能体运行技能时借助它进行思考(例如 课程、战争迷雾、曳光弹)。通过在文本中反复出现(但并非必须如此——强有力的引领词可能只需出现一次),它会调用模型已有的先验,用尽可能少的 token 累积出分布式定义,并锚定整个行为区域。

它从两个方面服务于可预测性。在正文中,它锚定 执行:每当该词出现,智能体都会采用相同的行为。在 description 中,它锚定 调用:当同一个词出现在你的提示词、文档和代码中时,智能体会将这种共享语言与技能关联起来,并更可靠地触发技能。

寻找通过重构技能来使用引领词的机会。在三个位置分别写出的三元组(重复),以及用一个句子暗示一个想法的 description——每一处都迫切需要 压缩 成单个 token。例如:

  • “快速、确定性、低开销” -> 紧密——贯穿一个阶段反复表述的同一种品质——压缩成一个预训练词语(一个 紧密 循环)。
  • “一个你相信的循环” -> 红——将含糊的门禁转换成可观察的二元状态(循环在缺陷上变 红,或者没有)。

你会赢得双重收益:更少的 token,以及 一个更明确的钩子,供智能体挂载其思考。假设每个技能都携带着能被引领词淘汰的重复表述——去找出它们。

失败模式

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

  • 过早完成——在步骤真正完成之前就将其结束,注意力滑向 完成状态。防御顺序:先让完成标准更明确(成本低、作用局部);只有当标准不可避免地模糊,并且 你观察到仓促行为时,才通过拆分(按顺序切分)来隐藏完成后步骤。
  • 重复——同一个含义出现在多个位置。它会增加维护成本、消耗 token,并让某个含义在阶梯上的显著性超过其真实层级。
  • 沉积——因添加内容让人觉得安全、移除内容显得有风险而沉淀下来的过时层次。这是任何缺乏精简纪律的技能的默认命运。
  • 过度膨胀——技能只是单纯过长,即使每一行都有效且独一无二。它会损害可读性和可维护性,并浪费 token。解决办法是使用阶梯:将 参考资料 披露到指针之后,并按 分支 或顺序拆分,使每条路径只携带所需内容。
  • 无效指令——模型默认已经遵循的一行内容,因此你付出负荷却什么也没说。检验方式是:与默认行为相比,它是否改变了行为?薄弱的引领词(当智能体本就还算彻底时使用 保持彻底)属于无效指令;解决办法是使用更强的词语(不留情面),而不是改用另一种技巧。
  • 否定式引导——通过禁止来引导会适得其反:不要想一头大象 点名了大象,让它变得更容易出现,而不是更少。提示 正向行为——陈述目标行为,使被禁止的行为完全不被提及;只有在无法用正向方式表达时,才将禁令保留为硬性防护措施,即便如此,也要将其与替代做法配对。

04 同仓库更多 Skills