writing-for-agents

为 agent 消费的任何文档提供参考——一个 skill、一个 AGENTS.md / CLAUDE.md、一个经 pointer 触达的文档。包装方式不同；写作本身并无不同：同样的杠杆让每一份都变得可预测——agent 每次运行都采取相同的 process，而不是产出相同的 output。

当你写的文档是 skill 时，阅读 SKILL-MECHANICS.md 了解 frontmatter、invocation 选择以及 router skills。

Context pointers

context pointer 是 agent context 中持有的一个 reference，它命名某个 context 之外的材料，并对触达它的条件进行编码。某个 skill 的 description 就是其一；AGENTS.md 中命名某个文档的一行是同一个对象。决定 agent 何时以及多可靠地触达材料的，是指针的 措辞，而不是它的目标。一个必须是目标的、却由措辞薄弱的 pointer 承载的内容，是一个 variance bug：先打磨措辞，只有打磨失败时才内联该材料。

一个 pointer 做两件事——说明材料是什么，并列出应触发触达它的 branches（一个 branch 是文档处理的一个独立情形，所以不同的 runs 会沿不同的路径穿过它）。一个始终加载的 pointer 的每个词都会在每一轮付出成本，所以它比正文更该被大力修剪：

• 把 leading word 放到最前面——pointer 是它做触发工作的地方。
• 每个 branch 一个 trigger。 如果同义词只是重命名单一 branch，那就是同一个 branch 写了两遍；合并它们，只保留真正不同的 branches。
• 删掉正文已经承载的 identity。

The two loads

你添加的每个文档和 pointer 都会花掉两个预算之一：

• Context load ——始终加载的材料对 agent window 的成本：一行 AGENTS.md、一个 skill description、任何每轮都躺在 context 里的东西，无论是否触发都要花 tokens 和注意力。
• Cognitive load ——对人类的成本：存在哪些文档、何时伸手去取每一份。人类就是 index。这不是要最小化的成本——它是 human agency 的代价；把它花在人的判断起作用的地方，在它不起作用的地方移除它。

只能通过 pointer 触达的材料，以该 pointer 自己那一行为代价逃过 context load；完全没有 pointer 的材料则完全由 cognitive load 承载。

Information hierarchy

一个文档由两类内容构成——steps（agent 执行的有序动作）和 reference（按需查阅的定义、规则、事实）——它们自由混合：全是 steps（一份菜谱）、全是 reference（一次 review 的规则、本 skill），或两者都有。核心决策是每块内容放在 information hierarchy 的哪个位置——一个按 agent 需要材料的即时程度排序的 ladder：

1. In-file step ——primary tier：agent 按顺序做什么。
2. In-file reference ——按需查阅。通常是一个合法的 flat peer-set（一次 review 的所有规则都在一个 rung 上）——这是合理的安排，不是坏味道。
3. Disclosed reference ——推到独立文件中，经 context pointer 触达，只在 pointer 触发时加载。既涵盖同一文件夹里的 sibling 文件，也涵盖存在于任何地方、任何文档都能指向的完全 external reference。

把太少内容下放会让顶层膨胀；把太多内容下放会隐藏 agent 实际需要的材料。那种张力就是整个决策。

Progressive disclosure 是沿 ladder 下移的动作——移出主文件、放到一个 pointer 后面——让顶层保持清晰。它主要不是 token 优化：它是 hierarchy 被保护的方式。Branching 是最干净的 disclosure 测试：内联每个 branch 都需要的内容，只把部分 branches 触达的内容放到 pointer 后面。当一个文档有 steps 时，本应被 disclose 的 in-file reference 会把它们埋起来，把关注它们变成掷硬币——这是一个 variance 杠杆，而不只是可读性杠杆。