write-skills

编写技能

技能不是文档，而是为已经懂得如何编码和推理的 Agent 压缩的操作记忆。它的作用是确保可预测性——让 Agent 每次运行都遵循相同的流程，而不是产出相同的结果。只写那些会改变 Agent 行为的上下文。

首要原则

1. 从描述中触发。 Frontmatter 中的 description 是技能加载前唯一会被读取的部分。说明技能的用途，以及应该触发它的具体情境。不要把触发规则藏在正文里。

2. 把 Token 当作稀缺资源。 假设 Agent 已经擅长通用推理。指出方向，让强大的模型自行推断实现细节。包装型技能可以只有两句话：说明要用的能力和要遵循的技能。只有在有证据表明存在失败时，才补充操作细节。

3. 写流程，而不是长篇说明。 优先使用祈使规则、决策点和简短示例。好的技能能改变 Agent 下一轮的行为，而不只是解释主题。同时，流程要与交付物的形态相匹配：一份写着“挑选适用项”的技巧目录会让 Agent 只挑选工具，而不是遵循流程——如果任务本身是一种有明确形式的交互（如访谈、分阶段漫步），工作流就必须采用这种形式，并将技巧作为其中的步骤。

4. 循序渐进地披露信息。 主技能文件要简短。将冗长的架构、示例、提供方文档或特定变体的指导移到链接的 references/ 文件中，并通过仅在需要时触发的指引来引用。将易出错且需要重复执行的操作放入 scripts/。将可复用的输出素材放入 assets/。

5. 通过实际使用来验证。 新 Agent 能在真实任务中正确应用技能，技能才算合格——在不提供提示的情况下运行，并使用将要运行它的最弱模型进行测试；如果技能只有在编写它的前沿模型上才能引导出正确行为，那它就脆弱得不适合发布。编辑后，要假设自己没有任何对话历史，重新阅读，并删掉所有不会影响行动的内容。

6. 示例要说明问题，而非解决方案。 示例的价值在于教会 Agent 识别反复出现的问题——问题征兆、症状，以及你如何发现它不对。这样的内容才经久耐用。你当时采用的修复方法则不然：代码会变化，固化的解决方案会过时；更糟的是，它可能会在下次不适用时仍然指示 Agent 采用同一做法。描述失败模式及其特征，让 Agent 根据当前代码重新推导修复方案。“一个基于质心距离判定的方向性问题，从各个方位看都不合理”能教会 Agent 识别问题；“于是我们用 FRONT_ARC 作为判定依据”则会过时。拿不准时，就说明哪里出了问题以及你如何发现的，然后到此为止。

引导词

引导词是模型在预训练中已经掌握的简洁概念，Agent 执行技能时会借助它来思考（例如 战争迷雾、示踪弹、红、紧凑）。一个词就能唤起模型已有的先验知识，并用最少的 Token 锚定一整套行为。

• 它能在正文中锚定执行（同一个词 → 每次都触发同一种行为），也能在描述中锚定调用（当这个词也出现在用户的提示词、文档和代码中时，技能会更可靠地触发）。
• 找出可以用一个引导词替代的重复表述。“快速、确定性、低开销” → 一个紧凑的循环。“你相信其结果的循环” → 让这个循环变红。一举两得：更少的 Token，更明确的触发点。
• 薄弱的引导词毫无作用（Agent 本就会“全面细致”）。解决办法是换成更有力的词（毫不松懈），而不是增加句子。

调用方式

选择技能的调用方式；每种选择的成本各不相同。

• 模型调用（默认）：保留 description，让 Agent 能主动调用该技能，其他技能也能调用它。代价是上下文加载——每轮对话都会将该描述放入上下文窗口。请编写丰富的触发语句。
• 用户调用：设置 disable-model-invocation: true。只有用户输入技能名称才能调用；不占用上下文，但用户必须记得该技能存在。此时，description 会变成面向用户的一句话说明。

只有当 Agent 或其他技能需要在未收到提示时调用该技能，才选择模型调用。如果用户调用的技能数量超过记忆容量，请添加一个路由技能，说明其他技能的名称以及分别适用的情形。

描述

描述有两项作用：说明技能是什么，并列出会触发它的不同情形（分支）。

• 将最关键的词放在开头——调用相关的工作就在这里发生。
• 每个分支对应一个触发情形。用同义词改写同一分支属于重复；应将它们合并，只保留真正不同的分支。
• 删除正文中已有的身份说明。只保留触发条件，以及“其他技能需要……时”的调用说明。

信息层级

技能由步骤和参考资料组成，可自由混合。根据每项内容对 Agent 的紧迫程度进行排序：

1. 技能内步骤——在 SKILL.md 中按顺序执行的操作。每个步骤都应以完成标准收尾：标准应当可检查（Agent 能否判断是否完成？），并在必要时做到穷尽（例如“已核对每个修改过的模型”，而非“生成变更清单”）。模糊的标准容易导致过早结束。
2. 技能内参考资料——需要时查阅的定义或规则。将同级规则平铺排列没有问题，不是坏味道。
3. 外部参考资料——从 SKILL.md 移至链接文件中，仅在其指针触发时加载。

将一个概念的定义、规则和注意事项放在同一标题下（就近放置），这样阅读某一部分时也能看到相关内容。向下拆分太少会导致顶部内容臃肿；拆分太多则会隐藏 Agent 需要的信息。

何时拆分

每次拆分都有成本，因此只有在确有收益时才拆分：

• 按调用方式拆分——当某个不同的开头词应单独触发一项技能，或其他技能必须调用它时，才将其拆分为一项模型调用的技能。代价是新技能的描述会始终加载到上下文中。
• 按顺序拆分——当后续步骤会诱使 Agent 仓促完成当前步骤时，将一连串步骤拆分。隐藏后续步骤会让当前步骤的工作量增加。判断标志是阶段压缩：多个步骤的工作被塞进一条消息，或 Agent 声称后续步骤已完成，却从未打开过该步骤。主技能中“进入某一步时，阅读对应文件”的指针，即使在较弱的模型上也能可靠触发。

失败模式

根据以下情况诊断表现异常的技能：

• 过早完成 — 步骤尚未完成就结束。先修正完成标准（成本低）；只有当标准确实无法进一步明确，且你观察到仓促结束时，才通过拆分步骤来掩盖后续步骤。如果技能的工作以交接产物为终点，就将其指定为技能层级的唯一完成条件；否则，运行会在任何看起来已经完成的中间产物处结束。
• 禁披露 — 对有序工作流过度服从：Agent 为遵守后续步骤的安排，压下早期发现，导致用户在 Agent 隐瞒相关信息时作出决定。任何包含步骤排序的技能都需要明确说明这个例外：顺序只约束呈现，不约束披露。
• 侥幸通过 — 验证运行之所以成功，只是因为用户或外部环境主动提供了关键输入。结果是正确的，但流程并未促成这一结果；应将获取该信息的探询明确写成一个步骤，而不是寄希望于下次还能侥幸成功。
• 重复 — 同一含义出现在两个地方。保留一个唯一事实来源。
• 沉积 — 因为新增内容让人感觉稳妥，过时内容层层累积。应有意识地精简。
• 经验故事 — 将教训写成带有函数名、调优数值以及某个 bug 演变过程的修改实录。这些细节很快就会过时，还会淹没可迁移的规则。应说明原则以及需要留意的迹象；具体机制留给代码库。一条具体示例足以说明问题；堆砌一段示例反而会喧宾夺主。
• 实现索引 — 技能本应传授判断方法，却指向当前的源文件、行号、字面量或具体内部函数。这些定位信息会过时，导致 Agent 追逐旧机制。技能中保留持久有效的原则、症状、验收标准和参考资料；特定任务的实现说明放入当前规范。如果代码位置很重要，就告诉 Agent 在代码库中找到当前负责该部分的代码。
• 冗长 — 即使每一行仍有用，内容也过长。按以下阶梯精简：通过指针链接提供参考资料，按分支或顺序拆分。
• 无效指令 — 模型默认就会遵守的内容。逐句单独测试；如果某句无效，就删掉整句，不要只删几个字。

结构

除非有充分理由，否则采用以下结构：

---
name: short-verb-phrase
description: What this does. Use when ...
---

# Skill Title

One short paragraph defining the job.

## Workflow

1. Do the first load-bearing thing.
2. Make the key decision.
3. Produce or verify the artifact.

## Rules

- Keep the constraints that prevent common mistakes.
- Link only the references that should be loaded conditionally.

编辑步骤

创建或修订技能时：

• 优先使用小写连字符格式的动词 + 复数名词：audit-tests、write-skills、compare-screenshots。文件夹名和 frontmatter 中的名称必须一致。复数形式会扭曲含义时，可采用自然的例外；这是新名称的默认规则，不要求重命名现有技能。
• 让描述具体到无需阅读正文也能触发技能。
• 从正文中删除所有“何时使用”部分。
• 删除过时的历史记录、归属信息、占位符和设置说明。
• 删除文件路径、行号、当前常量和实现参数，除非该技能明确是代码导航操作手册。优先保留持久有效的原则，并指示检查当前代码。
• 多条相互重叠的要点，优先整合为一条有力规则。
• 如果合适，用一个引导词来改写重复表述。
• 示例应简短且贴近实际。
• 除非 README、变更日志或辅助文档是真正的参考资料，且技能会指示 Agent 何时阅读，否则不要添加。
• 如果有技能验证器，就运行它。

完成标准

当技能的元数据能正确触发技能、正文短到可以一遍读完，且新接手的 Agent 无需询问技能的用途就能按其执行时，技能即告完成。