本指南提供了一套针对AI智能体文档写作的系统方法。它强调，无论文档是技能（skill）、AGENTS.md/CLAUDE.md还是通过指针引用的外部文档，其写作原则是相通的：目标是让智能体在每次运行时都采取一致的过程，而不是产出完全相同的结果。
一、上下文指针（Context Pointers） 指针是智能体上下文中对某些外部材料的引用，并编码了访问该材料的条件。技能描述、AGENTS.md中的一行文档名都是指针。指针的措辞（而非目标本身）决定了智能体何时以及多可靠地访问材料。如果重要材料背后的指针措辞薄弱，就会导致方差缺陷，应首先锐化措辞；若锐化无效，再考虑内联材料。指针承担两项任务：说明材料是什么，以及列出应触发访问的分支（每个分支是文档处理的不同情况）。由于常驻指针的每个词在每一轮都消耗成本，因此需要更严格地修剪：前置引导词、每个分支一个触发器、删除正文已承载的身份信息。
二、两种负载（The Two Loads） 每份文档和指针都会消耗两种预算之一：上下文负载（context load）是常驻材料对智能体窗口的成本，消耗令牌和注意力，无论是否触发；认知负载（cognitive load）是人类的成本，即人类作为索引需要记住哪些文档存在以及何时使用。认知负载不是要最小化的成本，而是人类能动性的代价，应在人类判断重要的地方花费，在不需要的地方移除。仅通过指针访问的材料以指针自身一行的代价逃脱上下文负载；没有指针的材料则完全依赖认知负载。
三、信息层级（Information Hierarchy） 文档由两种内容类型构成：步骤（steps，智能体执行的有序动作）和参考（reference，按需查阅的定义、规则、事实）。核心决策是每部分在信息层级中的位置：文件内步骤（主要层级）、文件内参考（按需查阅，可以是扁平的同行集合）、披露参考（推送到单独文件，通过上下文指针访问，仅在指针触发时加载）。渐进式披露（progressive disclosure）是将材料沿层级下移（移出主文件并置于指针之后），以保持顶层清晰。分支是判断披露的清晰测试：内联每个分支都需要的内容，将仅部分分支访问的内容推到指针之后。当文档有步骤时，应披露的文件内参考会掩埋步骤，使关注步骤变成抛硬币——这是方差杠杆，而不仅仅是可读性问题。
四、共置（Co-location） 共置是文件内的伴侣：层级决定材料放置多深，共置决定材料放置后旁边是什么。将概念的定義、规则和注意事项放在同一标题下，而非分散，这样阅读一部分会带入相邻内容。测试标准：文档应读起来像为智能体编写的文档。分散是失败模式：文档过长，即使每行都活跃且唯一，注意力也会在多余内容中稀释。
五、步骤与完成标准（Steps and Completion Criteria） 每个步骤都以完成标准结束，即告诉智能体工作完成的条件。两个属性使其成为杠杆：清晰性（智能体能否区分完成与未完成？模糊边界会导致过早完成）和需求度（要求多少？“每个修改的模型都得到解释”比“生成变更列表”要求更彻底的工作）。最强的标准既可检查又穷尽。
六、何时拆分（When to Split） 将一份文档拆分为两份会消耗两种负载之一，因此仅当拆分值得时才拆分：按序列拆分（将完成后的步骤移出视线，以驱动当前任务更多案头工作）；按调用拆分（技能特定，参见SKILL-MECHANICS.md）。
七、引导词（Leading Words） 引导词是模型预训练中已有的紧凑概念，智能体在运行文档时用它思考（如lesson、fog of war、tracer bullets）。作为令牌重复，而非句子，它积累分布式定义，以最少令牌锚定整个行为区域，通过招募模型已有的先验。自己造词可行，但需要定义令牌，而预训练词免费；应优先使用现有词。引导词在两个地方锚定：在正文中锚定执行，在指针中锚定调用。应寻找机会用引导词重构，将三处拼写的三元组或指针中花一句话暗示的概念折叠为单个令牌。否定是此杠杆旁的失败模式：通过禁止来引导会将禁止的行为拖入上下文并使其更易获得。应提示正面行为，使禁止的行为从未被说出。禁止仅作为无法正面表达的硬性护栏时才值得保留，即使如此也应与正面目标配对。
八、修剪（Pruning） 保持每个意义在单一事实来源中，避免重复。环境也是事实来源（package.json脚本、配置文件、目录布局、--help输出），文档重述环境是缓存，仅当查找昂贵时才值得。检查每行相关性：是否仍与文档所做相关？没有修剪纪律，默认命运是沉积（sediment）：陈旧层沉淀。逐句寻找无操作（no-op）：模型默认已遵守的指令不改变行为，应删除整句而非修剪词语。测试是模型相对的，通过运行文档而非辩论来解决。引导词也受此测试：太弱无法击败默认的词是无操作，修复方法是更强的词（如relentless），而非不同技术。
适用场景：创建或编辑技能文档、修改AGENTS.md/CLAUDE.md、编写任何智能体消费的文档。限制：指南中的具体技术（如SKILL-MECHANICS.md）需参考其他材料；部分建议依赖模型行为，需实际运行验证。