writing-for-agents

一份用于编写智能体所阅读的任何文档的参考：一个技能、一份 AGENTS.md / CLAUDE.md、一份通过指针触达的文档。包装方式各异，但写作规则是一致的：同样的杠杆让每份文档都变得可预测，因为智能体每次运行采取的是同一个流程，而不是产出同一个输出。

当你正在编写的文档是一个技能时，请阅读 SKILL-MECHANICS.md，了解前置元数据、调用方式的选择，以及路由技能。

上下文指针

上下文指针（context pointer） 是智能体上下文中持有的一条引用，它指向一份"上下文之外"的资料，并编码了触达该资料的条件。技能的 description 就是一条；AGENTS.md 中指向某份文档的一行也是同一回事。决定智能体何时、以多高的可靠性触达这份资料的，是这条指针的措辞，不是它的指向。一个本应被触达的指向目标，却藏在一段措辞含糊的指针背后：这是一个方差 bug：先打磨措辞；只有当打磨失败时，才把资料直接内联进去。

一条指针承担两件事：说明这份资料是什么，以及列出应当触发触达它的分支（branch 是这份文档所处理的一种独立情形，所以不同次运行会走不同的路径）。每一条始终加载的指针里的每一个词，在每一次轮次中都在付代价，所以它需要比正文更严格的精简：

• 把"引导词"前移：指针是触发工作真正发生的地方。
• 一个分支对应一个触发词。 同义词把同一个分支换了个说法写两遍，本质上是一个分支；把它们合并，只保留真正不同的分支。
• 去掉正文已经承载的身份信息。

两种负载

你新增的每一份文档与每一条指针，都在花两种预算之一：