为智能体写作

它的作用¶

writing-for-agents 是面向智能体的文档写作参考：一个技能、一个 AGENTS.md 或 CLAUDE.md、一个规范、一个运行时 Prompt、一个 README，或任何智能体阅读的文档。格式不同，但写作方式不变。相同的杠杆让每一份文档都可预测，因此智能体每次运行都遵循相同的流程（不一定得到相同输出）。

它的默认修法是删除，而不是解释。让智能体为另一个智能体编写指令时，它会把大部分篇幅用来解释模型已经知道的内容。这些行中的每一行都是 no-op：它消耗上下文，却不改变任何行为。这份参考帮助你找出它们，因此它对已有文档和空白文件同样有用。

在 v1.1 之前，它叫 writing-great-skills。新名字更符合它一直以来的定位。其中几乎没有任何内容专属于技能。仅与技能相关的机制（frontmatter、模型调用与用户调用的选择、路由技能）放在链接的 SKILL-MECHANICS.md 中，只有当你面前的文档是技能时才需要阅读。

何时使用它¶

输入 /writing-for-agents，或者当你在创建或编辑技能，或修改 AGENTS.md 或 CLAUDE.md 时，智能体会自行使用它。

对于智能体阅读的其他所有内容，都可以手动使用它：你的文档、规范和工单，系统 Prompt 和 AFK Prompt。判断标准只有一个问题：智能体是否会阅读它？智能体如何获得文档并不重要：指针指向它、人类粘贴它，或者它在仓库中。要了解代码库包含什么，使用 grill-with-docs。这份参考控制文档如何被阅读，而不是它知道什么。

两种负载¶

核心思想是两种预算，每份文档和每个指针都会消耗它们：

• 上下文负载：始终加载的材料对智能体窗口的成本：AGENTS.md 中的一行、技能描述，或任何在每个回合都留在上下文中的内容，无论它是否触发。
• 认知负载：你需要记住哪些文档存在以及何时使用每个文档的成本。你就是索引。不要试图最小化这个成本，因为它是人类能动性的代价。

一旦你用这两种负载来思考，大多数编写决策（拆分或不拆分、内联或披露、指向或推送）都会变成在不同地方做出的同一种权衡。

杠杆¶

• 上下文指针：保留在上下文中、指明上下文外材料并编码何时使用它的参考。技能描述和 AGENTS.md 中指明某文档的一行是同一回事。指针的措辞，而不是它的目标，决定智能体遵循它的可靠程度。
• 信息层级：从文件内步骤，到文件内参考，再到指针后面的披露参考的阶梯。渐进式披露 是将材料沿该阶梯下移，使顶部保持易读。
• 完成标准：每个步骤的完成条件有多清晰、多严格，以及这种严格带来的实际工作。它们是防止过早完成的防线。
• 引导词：模型预训练中已经存在的紧凑概念（紧凑、红色、曳光弹），智能体在运行文档时会用它来思考。它在两个地方起作用。在正文中，它指导执行；在指针中，它触发调用。
• 修剪：单一事实来源、相关性，以及逐句应用的 no-op 测试，用于对抗重复、沉积和蔓延。

常见问题¶

/writing-great-skills 去哪了？ 它是这个技能，在 v1.1 中重命名。早在重命名之前，用户就已将它用于 AGENTS.md、文档、规范、工单和运行时 Prompt。结构、引导词和修剪适用于智能体阅读的任何文本。没有别名。请使用新名称重新安装。

“为智能体写作”：所以是智能体来写作吗？ 恰恰相反。你是作者，智能体是读者。这正是它困难的原因。你为一个已经读过一切的读者写作，因此解释是浪费，精确才是全部工作。

我不能直接让智能体替我写吗？ 你可以，但它会产出冗长的内容。放任不管时，模型会解释它已经知道的东西，而且它不会自行应用 no-op 测试或寻找引导词。使用这份参考来审阅草稿。它的大部分价值来自那次审阅。

我让智能体精简一份文档，结果它删掉了功能。 被要求“精简”的智能体会优化长度，因为长度是它们能看到的东西。no-op 测试检查行为，而不是风格：删除该行，然后问智能体的行为是否改变。当一个句子不合格时，删除整个句子，而不是从中删词；对于它的分歧，通过运行文档来解决，而不是争论。

我怎么知道它完成了？ 当它有效，并且你再也找不到重复、沉积或 no-op 时。没有自动化评估。你通过手动运行文档，并使用故障模式词汇表来诊断问题来检查。当文档表现异常时，同样的词汇表帮助你修复它：先命名故障模式，然后修复它。

这应该放在 CLAUDE.md 还是其他地方？ 问自己愿意支付哪种负载。CLAUDE.md 会无条件加载到每个会话中。指针后面的材料在触发之前只消耗指针自身那一行的成本。任何只在十次会话中一次适用的内容，都会在其余九次中消耗上下文负载。

我需要为每个新模型重写我的文档吗？ 通常不需要，而且过度拟合某一个模型会带来它自己的问题。为新模型更新通常只是另一次 no-op 检查，而不是重写。

我的技能只在我当初构建它的那个具体任务上有效。 常见方法（先完成一次工作，然后让代理将其整理成技能）与那一次运行贴合得太紧，示例也往往过于具体。保留这次运行作为证据，然后有意识地泛化：剥离属于该仓库和那些文件的内容，面向任务类别来写。

英语不是我的第一语言。我会失去引导词优势吗？ 不会。找到能用最少 tokens 承载最多行为的词，是参考文档替你完成的工作。

它起效的标志¶

• 文档会随着质量提升而变短，你会惊讶于最后只剩下这么少。
• 你能指出一个引导词，并看到它在多处改变代理的行为。
• 任何内容都不以任何形式重复陈述。重复是文档从未经过测试的最可靠迹象。
• 只有某个分支需要的参考资料应放在指针后面，而不是主文件中。

适用场景¶

这是一个可随时取用的独立参考。它适用于整套内容，而不是单个技能。这里的每个技能都是依据它编写的，当代理需要阅读其他技能产生的文档（一个 GLOSSARY.md 及其 ADR、一份规格说明、一张工单）时，它也覆盖这些文档。它唯一的直接调用者是 retro，后者在提出任何 steering file 或技能之前会加载它。当你不确定哪个技能或流程适合某个任务时，ask-matt 会引导你遍历整套内容。