writing-for-agentslisted

为 agent 消费的任何文档撰写参考——一个 skill、一份 `AGENTS.md` / `CLAUDE.md`、一个由 pointer 到达的文档。打包方式不同；写作方式相同：同样的杠杆让每一份都 predictable（可预测）——agent 每次运行采取相同的_过程_，而不是产出相同的输出。 当你写的文档是 skill 时，阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) 了解 frontmatter、invocation 选择和 router skills。 ## Context pointers（上下文指针） **context pointer** 是 agent 上下文中持有的一个 reference，它指名一些上下文之外的材料，并编码到达它的条件。skill 的 description 是一个；`AGENTS.md` 中命名某个文档的一行是同一个东西。指针的_措辞_，而不是它的目标，决定 agent 何时到达材料——以及有多可靠。一个必须命中的目标藏在措辞薄弱的指针后面，是一个 variance bug：先锐化措辞，只有锐化失败才内联材料。 指针做两件事——说明材料是什么，并列出应该 trigger 到达它的**branch**（branch 是文档处理的一个独特情况，所以不同的运行走不同的路径穿过它）。一个始终加载的指针的每个词在每个回合都花钱，所以它应受比正文更严格的修剪： - **把 leading word 放在最前���**——指针是它做触发工作的地方。 - **每个 branch 一个 trigger。** 把单个 branch 改名的同义词是同一个 branch 写了两遍；合并它们，只保留真正不同的 branch。 - **剪掉正文已经携带的身份。** ## The two loads（两种负载） 你添加��每份文档和每个指针都会花费两种预算之一： - **context load**——常驻材料在 agent 窗口上的成本：一行 `AGENTS.md`、一个 skill description、任何每个回合都在 context 里的东西，无论是否触发都花费 tokens 和注意力。 - **cognitive load**——在人身上的成本：存在哪些文档、何时去够取每一份。人是索引。不是要最小化的成本——它是人类主体性的代价；在人的判断重要的地方花它，在不需要它的地方去掉它。 只有通过指针到达的材料，以指针自身那一行为代价逃出 context load；完全没有指针的材料则完全依靠 cognitive load。 ## Information hierarchy（信息层次） 一份文档由两种内容类型构建——**steps**（agent 执行的顺序动作）和 **reference**（按需查阅的定义、规则、事实）——它们自由混合：全部是 steps（一份配方）、全部是 reference（一次 review 的规则、本 skill）、或两者兼有。核心决策是每块内容在 **information hierarchy** 上的位置——一个按 agent 需要材料的紧急性排序的 ladder： 1. **in-file step**——主层级：agent 按顺序做什么。 2. **in-file reference**——按需查阅。通常是一个合理平坦的同级集合（一次 review 的所有规则都在同一级）——是很好的安排，不是坏味道。 3. **disclo