# Writing For Agents > 为 agents 撰写文档。在创建或编辑 skills，或修改 AGENTS.md 或 CLAUDE.md 时使用。 - Skill: `gongyijie85/writing-for-agents` (Agent Skill) - Install (CLI): `npx skillmds@latest add gongyijie85/writing-for-agents` - Raw SKILL.md: https://api.skillmd.com/api/skills/gongyijie85/writing-for-agents/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: gongyijie85 (https://skillmd.com/u/gongyijie85) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gongyijie85/writing-for-agents --- 为 agent 消费的任何文档——一项 skill、一份 `AGENTS.md` / `CLAUDE.md`、一个通过 pointer（指针）触达的文档——提供撰写参考。包装形式不同，写作方法不变：相同的杠杆（levers）让每一份文档都可预测——agent 每次运行都走相同的_过程_，而不是产出相同的输出。 当你撰写的文档是一项 skill 时，请阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)，了解 frontmatter、调用方式选择和 router skills（路由类 skills）。 ## 上下文指针（Context pointers） **context pointer（上下文指针）** 是保存在 agent 上下文中的一种引用：它指名某些上下文之外的材料，并编码了触达该材料的条件。skill 的 description 就是一个例子；`AGENTS.md` 中指名某文档的一行也是同一类对象。决定 agent 何时、以及多可靠地触达材料的，是指针的_措辞_，而不是它的目标。一个必须触达的目标藏在措辞软弱的指针后面，就是一次 variance bug（方差性缺陷）：先打磨措辞，只有当打磨无效时才把材料内联进来。 指针承担两项工作——说明材料是什么，并列出应触发触达它的 **branches（分支）**（一个 branch 是文档处理的某个独立情形，不同的运行会走不同的路径）。常驻加载的指针每个词每一轮都在消耗成本，因此它比正文更应被严格修剪： - **把 leading word 前置**——指针正是在这里完成它的触发工作。 - **每个 branch 一个触发词。** 为同一个 branch 换名的同义词，等于把同一个 branch 写了两遍；合并它们，只保留真正不同的 branches。 - **删掉正文已承载的身份信息。** ## 两种负载（The two loads） 你添加的每一份文档和指针都会消耗两种预算之一： - **Context load（上下文负载）**——常驻材料对 agent 窗口的消耗：一行 `AGENTS.md`、一条 skill description、任何每一轮都待在上下文里的东西，无论是否触发都在消耗 tokens 和注意力。 - **Cognitive load（认知负载）**——对人的消耗：存在哪些文档、何时该使用哪一份。人是索引。这不是需要最小化的成本——它是人类能动性的代价；在人类判断重要的地方投入它，在不重要的地方移除它。 只通过指针触达的材料，以指针自身那一行为代价躲开 context load；完全没有指针的材料则完全承载在 cognitive load 上。 ## 信息层级（Information hierarchy） 一份文档由两种内容类型构建——**steps（步骤）**（agent 执行的有序动作）和 **reference（参考）**（按需查阅的定义、规则、事实）——它们可以自由混合：全是 steps（一份菜谱）、全是 reference（一次 review 的规则、本 skill），或两者兼有。核心决策是每一块内容在**information hierarchy（信息层级）**上的位置——这是一把按 agent 需要该材料的紧迫程度排序的梯子： 1. **In-file step（文件内步骤）**——最顶层：agent 按顺序做什么。 2. **In-file reference（文件内参考）**——按需查阅。常常是一组合法的扁平同级内容（一次 review 的所有规则在同一级）——这是合理的安排，不是坏味道。 3. **Disclosed reference（外置参考）**——被推送到单独的文件中，通过 context pointer 触达，仅在指针触发时加载。范围从同一文件夹中的同级文件，一直到完全外部的参考——后者可以存在于任何地方，任何文档都可以指向它。 往下推得太少，顶层会臃肿；推得太多，你会藏起 agent 真正需要的材料。这种张力就是整个决策本身。 **Progressive disclosure（渐进式披露）** 是沿梯子向下的动作——移出主文件、放到指针之后——让顶层保持易读。它首先不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：把每个 branch 都需要的内容内联，把只有部分 branch 会触达的内容放到指针之后。当文档含有 steps 时，本应被披露的 in-file reference 会埋没它们，把对步骤的关注变成一次抛硬币——这是 variance 杠杆，而不仅是可读性杠杆。 **Co-location（共置）** 是文件内的配套动作：梯子决定一块内容_向下放多深_，co-location 决定它_旁边放什么_。把某个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样阅读其中一部分时会把相邻内容一起带出来。检验标准：文档读起来应当像是专门为 agent 写的文档——分组的内容读起来如此；散落的内容则不然。（这不同于 duplication（重复）：重复是在两处重复同一个含义；散落是把一个含义拆散到多处。） **Sprawl（蔓延）** 是这里的失败模式：文档就是太长，即使每一行都是有效且独一无二的。注意力在过量内容上被稀释，每多一行就多一行需要保持相关。解药就是那把梯子：把 reference 披露到指针之后，并按 branch 或 sequence 拆分，让每条路径只承载它需要的内容。 ## 步骤与完成标准（Steps and completion criteria） 每个步骤都以一个 **completion criterion（完成标准）** 收尾——告诉 agent 工作已完成的条件。两个属性使它成为杠杆： - **Clarity（清晰度）**——agent 能区分完成与未完成吗？模糊的边界（"已达成共识"）会招致 **premature completion（过早完成）**：在步骤真正完成之前就结束它，注意力转向"_显得完成_"的状态。仍然可见的前方步骤——**post-completion steps（完成后的步骤）**——提供拉力；标准的清晰度则是阻力。按顺序防守：**先打磨边界**（局部且廉价）；只有当边界无法再收紧_并且_你观察到了匆忙收尾时，才通过拆分序列把后续步骤隐藏起来——而且隐藏只有在跨越真正的上下文边界时才有效（一次 hand-off 或一次 subagent 派遣；内联调用会让后续步骤仍然留在上下文里，什么也清不掉）。 - **Demand（要求强度）**——它要求做到什么程度。"每个被修改的模型都交代清楚"会迫使彻底的工作，而"产出一份变更清单"则不会。Demand 驱动 **legwork（苦功）**——agent 在工作中自行挖掘的深度，它潜藏在措辞里，而不是写成独立的一步——而且它不受步骤限制："每条规则都应用到位"约束的是一大块扁平 reference，正如"每一步都完成"约束的是一段序列——这正是纯 reference 文档仍然带有穷尽性门槛的方式。 最强的标准既可核查又穷尽。 ## 何时拆分（When to split） 把一份文档拆成两份会消耗两种负载之一，所以只有在拆分的收益配得上成本时才拆： - **按 sequence（序列）拆分**——当 post-completion steps 诱使 agent 匆忙完成当前步骤时，拆分这段步骤序列。让它们保持在视线之外，会在当前任务上驱动更多 legwork。当心反向情况：合并序列会让每一步的后续步骤暴露在接下来的内容面前，招致 premature completion。 - **按 invocation（调用方式）拆分**——skill 特有：参见 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)。 ## Leading words（领航词） **leading word（领航词）** 是已经存在于模型预训练中的紧凑概念，agent 在执行文档时会用它来思考（_lesson_、_fog of war_、_tracer bullets_）。以 token 而非句子的形式反复出现，它积累起一个分布式定义，并通过征用模型已有的先验，用最少的 token 锚定一整片行为区域。自己造词也行，只要定义清楚——但一个生造的词征用不到任何先验：你要为定义付出 token，而一个预训练过的词是免费赠送的；先找现成的词。 它锚定两次。在正文中，锚定 _execution（执行）_：每次这个词出现，agent 都会走向相同的行为；在扁平 reference 内部，它把注意力聚焦到要寻找的一类东西上。在指针中，锚定 _invocation（调用）_：当同一个词同时出现在你的 prompts、你的文档和你的代码库中时，agent 会把这种共享语言与材料关联起来，从而更可靠地触达它。 主动寻找用 leading words 重构的机会。一个在三处展开的三元组、一句指向某个概念的指针——每一处都是渴望坍缩成单个 token 的段落： - "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop). - "a loop you believe in" → _red_ — a fuzzy gate becomes a binary observable state (the loop goes _red_ on the bug, or it doesn't). 你赢两次：更少的 token，以及一个更锐利的钩子让 agent 挂起它的思考。假定每份文档都携带着可以被 leading words 退役的重述——去找出它们。 **Negation（否定式表述）** 是这个杠杆旁边的失败模式：通过禁止来引导，会把被禁止的行为拖进上下文，让它变得_更容易_被激活，而不是更难。"别想大象"，结果满脑子都是大象；否定是一个弱修饰语，会被强烈激活的概念压过，于是禁令有一半会被读成"去做这件事"的指令。改用**正向**提示——陈述目标行为（"写一行式注释"），让被禁止的行为永远不被提及。禁令只有在作为无法用正向方式表述的硬护栏时才有立足之地；即使如此，也要把它与正向目标配对，让注意力落在"该做什么"上。 ## 修剪（Pruning） - 把每个含义保持在**单一事实来源（single source of truth）**中：一个权威的位置，这样改变行为就是一次单点编辑。**Duplication（重复）**——同一个含义出现在不止一处——要付出维护成本和 token，还会把某个含义在梯子上的显要程度抬高到超出它的真实位次。（这是 leading word 的意外镜像：leading word 是有意重复 token，从不重复含义。） - **环境**也是一个事实来源——`package.json` 里的 scripts、配置文件、目录结构、`--help` 的输出——而一份重述它的文档就是一个 **cache（缓存）**：一份查找结果的副本，只有当查找本身昂贵时才配得上它的负载。缓存 agent 靠查看无法找到的东西：未写下来的约定、某个选择背后的原因、任何配置都不会承认的坑。把"一个文件、一条命令"就能查到的内容留给环境，在那里它们不会过时。 - 逐行检查**相关性（relevance）**：它还与这份文档所做的事相关吗？一行内容要么因为从未作用于任务（纯叙述，或一个本应被披露的 branch）而失去相关性，要么因为它所描述的行为或世界发生变化而过时。更短的文档更容易保持相关。没有修剪纪律，默认的命运是 **sediment（沉积）**：一层层过时的内容沉淀下来，因为添加让人感觉安全、删除让人感觉有风险，直到你不得不穿透它们才能找到仍然有效的内容。 - 逐句搜寻 **no-ops（空操作）**：一条模型默认就会遵守的指令，付出了负载却什么也没说。检验标准——它是否改变了相对默认行为的行为？——是相对于模型而言的，不是相对于读者：两个人对一条 no-op 意见不一，其实是对默认行为意见不一，解决方式是运行这份文档，而不是辩论。当一句话检验不通过时，删除整句话，而不是从它里面删几个词。这个检验同样给 leading words 打分：一个弱到无法胜过默认行为的词（agent 已经相当 thorough 时还说_be thorough_）就是 no-op，解决办法是换一个更强的词（_relentless_），而不是换一种技巧。