writing-for-agents

1为 agent 消费的任何文档提供参考：一个 skill、一个 `AGENTS.md` / `CLAUDE.md`、一个经 pointer 触达的文档。包装方式不同；写作本身并无不同：同样的杠杆让每一份都变得可预测：agent 每次运行都采取相同的 _process_，而不是产出相同的 output。
2 
3当你写的文档是 skill 时，阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) 了解 frontmatter、invocation 选择以及 router skills。
4 
5## Context pointers
6 
7**context pointer** 是 agent context 中持有的一个 reference，它命名某个 context 之外的材料，并对触达它的条件进行编码。某个 skill 的 description 就是其一；`AGENTS.md` 中命名某个文档的一行是同一个对象。决定 agent 何时以及多可靠地触达材料的，是指针的 _措辞_，而不是它的目标。一个必须是目标的、却由措辞薄弱的 pointer 承载的内容，是一个 variance bug：先打磨措辞，只有打磨失败时才内联该材料。
8 
9一个 pointer 做两件事：说明材料是什么，并列出应触发触达它的 **branches**（一个 branch 是文档处理的一个独立情形，所以不同的 runs 会沿不同的路径穿过它）。一个始终加载的 pointer 的每个词都会在每一轮付出成本，所以它比正文更该被大力修剪：
10 
11- **把 leading word 放到最前面**：pointer 是它做触发工作的地方。
12- **每个 branch 一个 trigger。** 如果同义词只是重命名单一 branch，那就是同一个 branch 写了两遍；合并它们，只保留真正不同的 branches。
13- **删掉正文已经承载的 identity。**
14 
15## 两种 load
16 
17你添加的每个文档和 pointer 都会花掉两个预算之一：
18 
19- **Context load**：始终加载的材料对 agent window 的成本：一行 `AGENTS.md`、一个 skill description、任何每轮都躺在 context 里的东西，无论是否触发都要花 tokens 和注意力。
20- **Cognitive load**：对人类的成本：存在哪些文档、何时伸手去取每一份。人类就是 index。这不是要最小化的成本，它是 human agency 的代价；把它花在人的判断起作用的地方，在它不起作用的地方移除它。
21 
22只能通过 pointer 触达的材料，以该 pointer 自己那一行为代价逃过 context load；完全没有 pointer 的材料则完全由 cognitive load 承载。
23 
24## 信息层级
25 
26一个文档由两类内容构成：**steps**（agent 执行的有序动作）和 **reference**（按需查阅的定义、规则、事实），它们自由混合：全是 steps（一份菜谱）、全是 reference（一次 review 的规则、本 skill），或两者都有。核心决策是每块内容放在 **information hierarchy** 的哪个位置，一个按 agent 需要材料的即时程度排序的 ladder：
27 
281. **In-file step**（primary tier）：agent 按顺序做什么。
29…