writing-for-agents-wx

写给 agent 看的任何文档的参考——一个 skill、一份 AGENTS.md / CLAUDE.md、一份被指针指向的 doc。打包方式不同，写法一致：同一组杠杆让每份文档可预测——agent 每次跑的是同一套过程，而不是产出相同的输出。

当你写的文档本身是一个 skill 时，frontmatter、调用方式选择、路由类 skill 这些 skill 专属的细节见 SKILL-MECHANICS.md；本 skill 只讲通用的写作杠杆。

上下文指针（context pointer）

上下文指针（context pointer） 是留在 agent 上下文里的一句引用，它指名某个上下文之外的材料，并编码了「何时去读它」的条件。一个 skill 的 description 就是一个指针；AGENTS.md 里指名某份文档的一行，也是同一个东西。决定 agent 何时触达材料的，是指针的措辞，不是它的目标——以及它有多可靠。一个必须触达的目标躲在一句弱措辞后面，就是一个 variance bug（不稳定触达缺陷）：先把措辞磨尖（sharpen），只有当 sharpen 仍不够时才把材料 inline 进主上下文。

一个指针做两件事——说明材料是什么，并列出应当触发去读它的分支（branch，文档要处理的不同情况，所以不同运行会走不同路径）。常驻指针的每一个词在每一轮都在花成本，所以它比正文更该被狠删：

• 把引导词前置——指针正是在这里完成触发工作的。
• 一个分支一个 trigger。 把同一个分支换几个同义词写，那是一个分支写了两遍；合并它们，只保留真正不同的分支。
• 砍掉正文已经携带的身份信息。

两种负担（the two loads）

你加的每一份文档和每一个指针，都在花两种预算之一：