安装此技能
npx skills@latest add mattpocock/skills --skill=writing-for-agents 然后在你的编码 agent 里输入 /writing-for-agents 。
本页目录
它做什么
writing-for-agents 是编写面向 agent 的文档的参考：一个技能、一份 AGENTS.md 或 CLAUDE.md、一份规范文档（spec）、一条运行时提示词、一份 README、任何 agent 会读的文档。格式各不相同，但写法相同。同样的杠杆让每一份都变得可预测，所以 agent 在每次运行时都遵循同样的过程（不一定得到同样的输出）。
它默认的修法是删除，而不是解释。让一个 agent 为另一个 agent 写指令，它会把大部分词花在解释模型（model）已经知道的东西上。那些行每一行都是空操作（no-ops）：它耗费上下文（context）却不改变任何行为。这份参考帮你找出它们，所以它对你已经有的文档和空白文件同样有用。
它在 v1.1 之前叫 writing-great-skills。新名字符合它一直以来的样子。它几乎没有哪部分是技能特有的。只与技能有关的机制（frontmatter、模型调用还是用户调用的选择、路由器技能）放在一份链接的 SKILL-MECHANICS.md 里，只有当你面前的文档是一个技能时你才去读它。
什么时候用它
输入 /writing-for-agents，或者当你正在创建或编辑一个技能，或修改 AGENTS.md 或 CLAUDE.md 时，agent 会自己来拿它。
对于 agent 会读的其他一切，你手动用它：你的文档、规范文档和工单（tickets）、系统提示词和离开键盘（AFK）提示词。测试就一个问题：agent 会读这个吗？agent 如何拿到文档并不重要：一个指针点名它、一个人粘贴它，或者它就在仓库里。要弄清楚一个代码库包含什么，用 grill-with-docs。这份参考控制的是文档如何被阅读，而不是它知道什么。
两种负载
核心想法是每一份文档和每一个指针都会花掉的两笔预算：
- 上下文负载（context load）：始终加载的材料对 agent 窗口造成的成本：一行
AGENTS.md、一条技能描述、任何每个轮次（turn）都留在上下文里、不管触不触发的东西。 - 认知负载（cognitive load）：你记住有哪些文档、以及何时该用每一份的成本。你就是索引。不要试图把这项成本降到最低，因为它是人类能动性的代价。
一旦你按这两种负载思考，大多数写作决定（拆还是不拆、内联还是披露、用指针还是硬推）就变成在不同地方做出的同一笔取舍。
杠杆
- 上下文指针（context pointers）：留在上下文里的引用，它点名上下文之外的材料，并编码何时去取它。一条技能描述和一行点名某份文档的
AGENTS.md是同一回事。指针的措辞，而不是它的目标，决定 agent 多可靠地遵循它。 - 信息层级（information hierarchy）：从文件内步骤，到文件内参考，再到指针后披露的参考，这一级级阶梯。**渐进式披露（progressive disclosure）**就是沿这个阶梯把材料往下移，让顶层保持易读。
- 完成标准（completion criteria）：每一步的完成条件有多清楚、多严格，以及那种要求所引起的实际功夫（legwork）。它们是抵御**过早完成（premature completion）**的防线。
- 引导词（leading words）：一个已经存在于模型预训练里的紧凑概念（tight、red、tracer bullet），agent 在运行文档时用它来思考。它在两个地方起作用。在正文里它引导执行，在指针里它触发调用。
- 修剪（pruning）：单一事实来源、相关性，以及逐句施加的空操作测试，用来对付重复（duplication）、沉积（sediment）和蔓延（sprawl）。
常见问题
/writing-great-skills 去哪了？
就是这个技能，在 v1.1 里改了名。用户早在改名之前就把它对准 AGENTS.md、文档、规范文档、工单和运行时提示词了。结构、引导词和修剪适用于任何 agent 会读的文本。没有别名。用新名字重新安装。
「为 agent 写作」：所以是 agent 来写？ 反过来。你是作者；agent 是读者。这才是它难的地方。你为一个已经读过一切的读者写作，所以解释是浪费，精确才是全部的工作。
我就不能让 agent 替我写吗？ 可以，而它会产出啰嗦的东西。放任不管，模型会解释它已经知道的东西，而且它不会自己施加空操作测试，也不会自己去找一个引导词。用这份参考来审查草稿。它的大部分价值来自那遍审查。
我让一个 agent 精简一份文档，它却把功能砍掉了。 被告知要「精简」的 agent 会为长度优化，因为长度是它们看得见的东西。空操作测试检查的是行为，不是风格：删掉那一行，然后问 agent 的行为是否改变了。当一句话没有通过时，删掉整句，而不是从里面修剪词语；关于它的分歧，通过运行文档来解决，而不是靠争论。
我怎么知道它什么时候完成？ 当它能用，而且你再也找不到重复、沉积或空操作的时候。没有自动化评测。你靠手动运行文档、并用失败模式词汇来诊断问题，以此检查。当一份文档行为异常时，同一套词汇帮你修好它：先命名失败模式，再修那一个。
这个该放在 CLAUDE.md 里还是别的地方？
问一问你想付哪种负载。CLAUDE.md 无条件加载进每一场会话（session）。指针后面的材料只花费指针自己那一行，直到它被触发。任何十场会话里只有一场适用的东西，在另外九场里都要付出上下文负载。
我需要为每个新模型重写我的文档吗？ 基本不需要，而且对单一模型过拟合会带来它自己的问题。为新模型更新通常只是又一遍空操作修剪，而不是重写。
我的技能只在我据以构建它的那个确切任务上有效。 常见方法（先把工作做一遍，然后让 agent 把它写成技能）与那一次运行贴得太近，例子会变得过于具体。把那次运行留作证据，然后有意识地泛化：剥掉属于那个仓库和那些文件的东西，为这一类任务写作。
英语不是我的母语。我会失去引导词的优势吗？ 不会。找到那个能用最少 token 装下最多行为的词，是这份参考替你完成的工作。
它生效的标志
- 文档随着变好而变短，而你对剩下这么少感到意外。
- 你能指着一个引导词，并看到它在不止一个地方改变了 agent 的行为。
- 没有任何东西被陈述两次，以任何形式。重复是一份从未被测试过的文档最可靠的迹象。
- 只有一个分支需要的参考放在指针后面，而不是放在主文件里。
它在体系中的位置
这是一份随时可用的独立参考。它适用于整套技能，而不是某一个技能。这里的每个技能都是用它的方法写成的，它也覆盖其他技能产出的文档（一份 GLOSSARY.md 及其 ADR、一份规范文档、一个工单），只要 agent 必须读它们。它唯一的直接调用者是 retro，后者在提出任何引导文件或技能之前先加载它。当你不确定哪个技能或哪条流程适合一项任务时，ask-matt 会在整套技能上为你路由。