/writing-for-agents 技能

它的作用

writing-for-agents 是你编写面向智能体文档时对照的参考——一个技能、一份 AGENTS.md / CLAUDE.md，一个 spec，运行时提示词、README、任何 agent 读取。包装不同；写作相同：同样的杠杆让每一个都可预测，所以智能体采取相同的 process 每次运行都如此，而不是产出相同输出。

它的默认动作是删除，而不是解释。让一个智能体给另一个智能体写指令，它会把大部分篇幅花在解释 model 已经知道——其中每一行都是 no-op，支付 context 且不改变任何行为。这个参考就是发现它们的镜头，这就是为什么它在你已有的文档上，至少和在一张空白文件上一样经常值回票价。

它曾叫 writing-great-skills 直到 v1.1。改名顺应了它底层一直以来的样子：其中几乎没有技能专属的东西。纯技能机制——frontmatter、模型调用与用户调用之选、路由器技能——向链接的 SKILL-MECHANICS.md 你只在面前的文档是技能时才读。

何时使用

输入 /writing-for-agents，或当你在创建或编辑技能、修改 AGENTS.md or CLAUDE.md.

其余智能体阅读的一切，都手动使用它：你的文档、规格说明和 tickets，系统与 AFK 提示词。测试只有一个问题——智能体会读这个吗？——而且文档如何到它面前并不重要，无论是指针点名它、人粘贴它，还是它只是躺在仓库里。要首先弄清代码库实际包含什么，用 grill-with-docs ——这个参考管的是文档读起来如何，而不是它知道什么。

两种负载

整个参考所围绕的想法是一对预算，每份文档和指针都要花费：

上下文负载 ——常驻加载材料对智能体窗口的代价：一个 AGENTS.md 行、技能描述、任何每时每刻都待在上下文里的东西，轮次无论它是否触发。
认知负荷 ——对你的代价：哪些文档存在，何时使用每个。你是索引。不是要最小化的代价——它是人类能动性的价格。

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

杠杆

上下文指针 ——持有在上下文中的参考，它点名上下文外的材料并编码何时使用它。技能描述和 AGENTS.md 指向文档的行是同一个对象；指针的 wording，而不是它的目标，决定了智能体透过它触达的可靠程度。
信息层级 ——从文件内步骤，到文件内引用，到指针后的披露引用的阶梯。 渐进披露 是沿梯子向下的一步，让顶端保持易读。
完成标准 ——每一步完成条件的清晰度与要求，以及 legwork 需求所驱动；对抗 过早完成.
首词 ——一个已经存在于模型预训练中的紧凑概念（tight, red, 曳光弹），智能体在运行该文档时用它来思考。它锚定两次：执行锚在正文，调用锚在指针。
修剪 ——单一真相来源、相关性，以及逐句应用的无操作测试，对照 duplication, sediment and sprawl.

常见问题

原来的 /writing-great-skills 去哪了？ 它就是本技能，在 v1.1 中改名。实践者们已经在把它指向 AGENTS.md，文档、规格说明、任务和运行时提示词早已如此，远在名字赶上之前；结构、首词和修剪被证明是智能体阅读的任何文本的技艺。没有别名——请用新名字重新安装。

「为智能体写作」——所以是智能体来写？ 反了。你是作者；智能体是读者。这正是这类文体的全部难点：你在为一个已经读过一切的读者写作，所以解释是浪费，精确才是全部工作。

我不能直接让智能体替我写吗？ 可以，而它会产出冗长的东西。放任不管时，模型会解释它已知的东西，不会自行应用无操作测试或使用首词。在草稿上用这个参考——它的价值大多落在审查环节。

我让智能体精简文档，它把功能也删了。 被要求「精简」的智能体会为长度而优化，因为长度是它们看得见的东西。无操作测试是行为层面的，不是审美层面的：删掉那一行，问智能体的行为是否变了。当一个句子不合格时，删除整个句子而不是删减其中的词——关于它的分歧，用运行文档来裁决，而不是争论。

我怎么知道它什么时候完成？ 它生效时，你再也找不到重复、沉积或无操作。这里没有自动化评测；检查是手动运行加上作为诊断的失败模式词汇。当文档行为异常时，那套词汇也是修理包——先点名失败模式，再修它。

这个应该放在 CLAUDE.md 或别的地方？ 问清你想支付哪种负载。 CLAUDE.md 加载进每个会话无条件地；指针后的材料在触发前只花费指针自己那一行。十次上下文只有一次适用的东西，另外九次都在支付上下文负载。

我需要为每个新模型重写文档吗？ 大多不用，而且过度拟合某个模型本身就是陷阱。为新模型更新通常只是另一次无操作扫描，而不是重写。

我的技能只在构建它的那个具体任务上有效。 常见路线——先做一次工作，再让智能体把它写成技能——过度依赖那一次运行，范例产出得太具体。保留运行作为证据，然后刻意抽象：剥离属于那个仓库和那些文件的部分，面向任务类别来写。

英语不是我的母语。我会失去「首词」优势吗？ 不——找到那个用最少的 tokens 是参考为你做的工作。它是其用途之一。

做到以下就算成功

文档越好越短，你会惊讶于剩下多少。
你可以指着一个首词，看它在不止一处工作。
任何形式的内容都不会陈述两次。重复是文档从未被测试过的最可靠标志。
只有一个分支需要的参考放在指针后面，而不是在主文件里。

在流程中的位置

这是一个随时可调用的独立参考。它在链上没有邻居，因为它坐在整套之下，而不是任何单个技能旁边：这里的每个技能都是对照它写的，其他技能留下的文档—— CONTEXT.md 及其 ADR、规格说明、任务——一旦智能体需要读它们，就正是它管辖的文本。当你不确定哪个技能或流程适合某个任务时， ask-matt 为你规划整套流程。