writing-for-agents 是一份参考指南，主题是“为智能体撰写任何它要消费的文档”：技能（skill）、AGENTS.md / CLAUDE.md，或通过指针触达的文档。指南强调，这些文档的打包形式不同，但写作方法相同：同一套杠杆让每一份文档都变得可预测，因为智能体每次运行走的是同样的过程，而不是产出同样的结果。
当你要写的文档是一个技能时，指南建议阅读 SKILL-MECHANICS.md，了解 frontmatter、调用方式选择以及路由技能。
上下文指针
上下文指针是保存在智能体上下文中的引用，它命名某个上下文之外的材料，并编码触达该材料的条件。技能的 description 是一个指针；AGENTS.md 中命名某文档的一行也是同一个对象。决定智能体何时、以多高可靠性触达材料的，是指针的措辞，而不是它的目标。一个必须触达的目标若藏在措辞薄弱的指针后面，就是一个方差缺陷：先锐化措辞，只有在锐化失败时才把材料内联。
指针做两件事：说明材料是什么，并列出应触发触达它的分支（分支是文档处理的一个独立情形，因此不同运行会走不同路径）。始终加载的指针的每个词都在每一轮付出成本，因此它比正文更需要严格修剪：把领头的词前置，因为指针正是在那里发挥触发作用；每个分支只留一个触发词，重命名同一分支的同义词是一个分支写了两遍，应合并，只保留真正不同的分支；删掉正文已经承载的身份信息。
两种负载
你添加的每份文档和指针都会花掉两种预算之一：
上下文负载是始终加载的材料对智能体窗口造成的成本：AGENTS.md 的一行、技能描述、任何每轮都待在上下文里的东西，无论是否触发都在消耗 token 和注意力。
认知负载是对人的成本：存在哪些文档、何时该用哪一份。人是索引。这不是要最小化的成本：它是人类能动性的代价；在人类判断重要的地方花它，在不重要的地方去掉它。
只能通过指针触达的材料逃开了上下文负载，代价是指针自身那一行；完全没有指针的材料则完全依赖认知负载。
信息层级
文档由两类内容构成：步骤（智能体执行的有序动作）和参考（按需查阅的定义、规则、事实）。两者可自由混合：全是步骤（一份配方）、全是参考（一份评审的规则、本技能），或两者兼有。核心决策是每一块内容在信息层级上的位置，这个阶梯按智能体对材料的即时需要程度排序：
文件内步骤是主层级：智能体按顺序做什么。
文件内参考按需查阅。它常常是一个合理的扁平同级集合（一份评审的每条规则都在同一级），这是不错的安排，不是坏味道。
披露式参考被推到单独文件中，通过上下文指针触达，只在指针触发时加载。范围从同一文件夹中的兄弟文件，一直到完全外部的参考——它存在于任何地方，任何文档都可以指向它。
推得太少，顶层会臃肿；推得太多，你会藏起智能体真正需要的材料。这种张力就是整个决策。
渐进式披露是沿阶梯向下移动（移出主文件、放到指针后面），让顶层保持清晰。它主要不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：每个分支都需要的就内联，只有部分分支触达的就推到指针后面。当文档有步骤时，本应披露的文件内参考会埋没它们，让关注步骤变成抛硬币：这不仅是清晰度杠杆，也是方差杠杆。
共置是文件内的配套原则：阶梯决定一块内容放多深，共置决定它到了那里之后旁边放什么。把一个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样读一部分就会带出它的邻居。测试标准是：文档读起来应该像为智能体写的文档。分组材料读起来如此；散落材料则不然。（这与重复不同：重复是在两处重复同一个含义；散落是把一个含义碎片化到多处。）
蔓延是这里的失败模式：文档单纯太长，即使每一行都是活的、独特的。注意力在多余内容上变薄，每一行多余内容都是又一处需要保持相关的东西。解药是阶梯：把参考披露到指针后面，按分支或序列拆分，让每条路径只携带它需要的东西。
步骤与完成标准
每个步骤都以完成标准结束，即告诉智能体工作已完成的那个条件。两个属性使它成为杠杆：
清晰度：智能体能否区分完成与未完成？模糊的边界（“达成理解”）会招致过早完成：在真正完成之前就结束步骤，注意力滑向“已完成”。前方可见的步骤（完成后步骤）提供拉力；标准的清晰度是阻力。按顺序防御：先锐化边界（局部且便宜）；只有当它不可约地模糊、且你观察到抢跑时，才通过拆分序列来隐藏后续步骤。隐藏只在真正的上下文边界上有效（交接或子智能体派发；内联调用会把后续步骤留在上下文中，什么也清不掉）。
要求强度：它要求多少。“每个被修改的模型都已说明”会迫使彻底工作，而“产出一份变更列表”不会。要求强度驱动跑腿工作（智能体在工作中做的挖掘，潜藏在措辞里，而不是写成自己的步骤），它不绑定于步骤：“每条规则都已应用”约束一组扁平参考，正如“每个步骤都已完成”约束一个序列，这就是全参考文档仍能携带穷尽性门槛的方式。
最强的标准既可检查又穷尽。
何时拆分
把一份文档拆成两份会花掉两种负载之一，所以只在切分值得时才拆：
按序列：拆分一串步骤，其中完成后步骤会诱使智能体抢跑眼前这一步。把它们挡在视野外会驱动当前任务上更多跑腿工作。要警惕反面：合并序列会把每个步骤的后续步骤暴露给接下来，招致过早完成。
按调用方式，技能专属：见 SKILL-MECHANICS.md。
引导词
引导词是一个紧凑概念，已经存在于模型的预训练中，智能体在运行文档时用它来思考（lesson、fog of war、tracer bullets）。它作为 token 重复，而不是作为句子重复，从而积累分布式定义，用最少的 token 锚定一整片行为区域，方法是招募模型已有的先验。自造词如果定义清楚也能用，但自造词招募不到先验：你用定义 token 付出预训练词免费给出的东西；优先用已有的词。
它锚定两次。在正文中，执行：每次这个词出现，智能体都伸手去拿同样的行为；在扁平参考中，它把注意力聚焦到一类要寻找的东西上。在指针中，调用：当同一个词出现在你的提示、文档和代码库中时，智能体把这种共享语言与材料联系起来，更可靠地触达它。
寻找用引导词重构的机会。一个三词组合在三处拼写出来，一个指针花一句话去指一个想法。每一处都是 begging 要塌缩成单个 token 的段落：“fast, deterministic, low-overhead” → tight（一个 tight loop）；“a loop you believe in” → red，把模糊的门变成二元可观察状态（循环在 bug 上变红，或不变红）。你赢两次：更少 token，以及一个更锐利的钩子让智能体挂住思考。假设每份文档都携带着引导词可以退役的重述。去找它们。
否定是这一杠杆旁的失败模式：用禁止来引导会把被禁行为拖进上下文，让它更可得，而不是更不可得。别想大象，结果满脑子都是大象；否定是一个弱修饰语，被强激活的概念压过，所以禁令半读起来像在做那件事的指令。用正面提示：陈述目标行为（“写一行注释”），这样被禁的那个就从未被说出。禁令只有在作为你无法正面表述的硬护栏时才配有一席之地；即便如此，也要配上正面目标，让注意力落在该做什么上。
修剪
让每个含义只有一个单一事实来源：一个权威位置，这样改变行为就是一处编辑。重复（同一含义出现在多处）付出维护和 token 成本，并把一个含义在阶梯上的显著度抬高到超出它真实等级。（它是引导词的意外反面，引导词故意重复一个 token，从不重复含义。）
环境也是事实来源（package.json 脚本、配置文件、目录布局、--help 输出），重述环境的文档是一个缓存：一次查找的副本，只有当查找昂贵时才配得上它的负载。缓存智能体靠看找不到的东西：不成文的约定、选择背后的原因、没有配置会承认的坑。把单文件、单命令的查找留给环境，在那里它们不会过期。
检查每一行的相关性：它是否仍与文档所做的事有关？一行失去相关性，要么是因为它从不与任务相关（纯说明，或一个本应披露的分支），要么是因为它所描述的行为或世界变化而变得陈旧。更短的文档更容易保持相关。没有修剪纪律，默认命运是沉积：陈旧层沉淀下来，因为添加感觉安全、移除感觉冒险，直到你必须钻透它们才能找到还活着的东西。
逐句寻找无操作句：模型默认已经遵守的指令付出负载却什么也没说。测试（与默认相比它改变行为吗？）是相对于模型的，不是相对于读者的：两个人对无操作句有分歧，其实是对默认有分歧，靠运行文档来定，而不是靠辩论。当一句话失败时，删掉整句，而不是从里面修剪词。这个测试也给引导词打分：一个弱到打不过默认的词（在智能体已经相当彻底时说“要彻底”）是无操作句，修复办法是更强的词（relentless），而不是换一种技术。