本指南是撰写Agent所用各类文档的参考——包括Skill、
/
，以及通过指针访问的文档。这些文档的呈现形式不同，但撰写逻辑一致：运用相同的方法能让每份文档的效果可预测——Agent每次执行时遵循相同的流程，而非生成完全一致的输出。
如果你撰写的是Skill文档，请阅读
，了解前置元数据、调用选择和路由Skill相关内容。
上下文指针
上下文指针是Agent上下文环境中存储的一种引用，用于指向外部内容并定义触发访问该内容的条件。Skill的描述就是一种上下文指针；
中指向某文档的行也属于同类对象。指针的措辞而非目标内容，决定了Agent何时以及能否可靠地访问对应材料。如果一个关键目标内容的指针措辞模糊，会导致执行差异问题：应先优化措辞，只有当优化无效时才考虑将内容内联到主文档中。
指针有两个核心作用——说明对应材料的性质，以及列出应触发访问的分支场景（分支指文档处理的不同情况，不同执行流程会走不同分支）。始终加载的指针每一个词都会占用每次交互的资源，因此比文档正文更需要精简：
- 前置核心触发词——指针的核心作用是触发访问，关键触发词应放在最前面。
- 每个分支对应一个触发条件。同义词描述同一分支属于重复表述，应合并，只保留真正不同的分支。
- 删除正文已包含的身份信息。
两类负载
你添加的每一份文档和指针都会消耗以下两类资源之一：
- 上下文负载——始终加载的内容对Agent上下文窗口的消耗：比如中的行、Skill描述，以及任何每次交互都存在于上下文的内容，无论是否触发都会消耗令牌和注意力。
- 认知负载——对人类使用者的消耗：需要记住哪些文档存在，以及何时使用哪份文档。人类是这些文档的索引。这并非需要最小化的成本——它是人类掌控权的代价；应将其用在需要人类判断的场景，在无需判断的场景则消除这类负载。
仅通过指针访问的内容可以避免上下文负载，但需要付出指针自身的行资源；完全没有指针的内容则完全依赖人类的认知负载。
信息层级
文档由两类内容构成——步骤（Agent执行的有序操作）和参考内容（按需查阅的定义、规则、事实）——两者可以自由混合：可以全是步骤（如操作指南）、全是参考内容（如评审规则、本Skill文档），或两者兼具。核心决策是确定每部分内容在信息层级中的位置，该层级根据Agent对内容的即时需求程度排序：
- 文档内步骤——最高层级：Agent需要按顺序执行的操作。
- 文档内参考内容——按需查阅的内容。通常可以是同级的扁平结构（如评审的所有规则处于同一层级）——这是合理的安排，并非问题。
- 外部参考内容——存放在独立文件中，通过上下文指针访问，仅在指针触发时加载。范围可以是同一文件夹下的兄弟文件，也可以是任意位置的外部文档，任何文档都可以指向它。
如果向下迁移的内容太少，顶层会过于臃肿；如果迁移过多，会隐藏Agent实际需要的内容。这种平衡就是决策的核心。
渐进式披露是将内容向下迁移的方式——从主文档移到指针之后——以保持顶层内容的可读性。这主要不是为了优化令牌消耗，而是为了维护信息层级。分支场景是最清晰的披露测试：将所有分支都需要的内容内联，仅将部分分支需要的内容放在指针之后。如果文档包含步骤，未披露的文档内参考内容会掩盖步骤，导致Agent是否关注这些步骤变得随机——这不仅影响可读性，还会导致执行差异。
就近放置是文档内的配套原则：信息层级决定内容的深度，就近放置则决定内容在该层级中的相邻元素。应将一个概念的定义、规则和注意事项放在同一标题下，而非分散各处，这样阅读一部分内容时能自然关联到相关内容。测试标准：文档应读起来像是为Agent编写的文档——内容分组合理的文档符合这一标准，分散的则不符合。（这与重复内容不同：重复是同一含义出现在两个地方；分散是同一含义被拆分到多个地方。）
内容膨胀是这里的失效模式：即使每一行内容都是有效的、唯一的，但文档过长。注意力会被分散，每多一行就多一份需要维护相关性的内容。解决方法是利用信息层级：将参考内容通过指针披露，按分支或流程拆分，让每个流程仅携带所需内容。
步骤与完成标准
每个步骤都有对应的完成标准——用于告知Agent工作已完成的条件。以下两个特性使其成为控制执行效果的关键：
- 清晰度——Agent能否区分已完成和未完成状态？模糊的边界（如“达成理解”）会导致提前完成：在任务真正完成前就结束步骤，注意力转移到“完成”本身。后续的步骤（完成后步骤）会形成拉力；而完成标准的清晰度则是阻力。优化顺序：先明确边界（本地修改，成本低）；只有当边界不可避免地模糊且观察到Agent急于完成时，才通过拆分流程隐藏后续步骤——且只有在真实的上下文边界（如任务交接或子Agent调度）下隐藏才有效；内联调用仍会让后续步骤留在上下文中，无法清除干扰。
- 要求程度——完成标准的严格程度。“所有修改的模型都已记录”比“生成变更列表”更能促使Agent完成全面的工作。要求程度决定了工作量——Agent在任务中需要完成的挖掘工作，隐含在措辞中而非单独作为步骤列出——且不限于步骤：“应用所有规则”适用于扁平的参考内容，就像“完成所有步骤”适用于流程序列一样，这也是纯参考文档仍能保证全面性的原因。
最有效的完成标准兼具可验证性和全面性。
拆分时机
将一份文档拆分为两份会消耗两类负载之一，因此只有当拆分带来的收益大于成本时才应进行：
- 按流程拆分——当后续步骤会诱使Agent急于完成当前步骤时，拆分流程。将后续步骤移出视野能促使Agent在当前任务上投入更多精力。注意反向情况：合并流程会让每个步骤的后续步骤暴露给后续流程，容易导致提前完成。
- 按调用方式拆分——Skill专属内容：详见。
核心触发词
核心触发词是模型预训练中已存在的紧凑概念，Agent在执行文档时会基于这些概念思考（如_lesson_、fog of war、tracer bullets）。将其作为令牌重复使用，而非整句表述，会逐步形成分布式定义，并利用模型已有的先验知识，用最少的令牌锚定一整套行为逻辑。如果自行创造词汇，需清晰定义，但自创词汇无法利用模型的先验知识——你需要付出定义令牌的成本，而预训练词汇是免费的；因此优先使用已有的词汇。
它有两层锚定作用。在文档正文中，用于执行：每次出现该词时，Agent都会采取相同的行为；在扁平参考内容中，它会引导Agent关注特定类别的内容。在指针中，用于调用：当同一词汇出现在提示词、文档和代码库中时，Agent会将这种共享语言与对应材料关联起来，从而更可靠地访问该材料。
寻找用核心触发词重构内容的机会。比如在三个地方重复表述的三元组、用整句表述一个概念的指针——这些都可以简化为单个令牌：
- "fast, deterministic, low-overhead" → tight（如_tight_ loop）。
- "a loop you believe in" → red——模糊的判断标准变为二元可观察状态（遇到bug时循环变为_red_，否则不变）。
这样做有两个好处：减少令牌消耗，同时为Agent的思考提供更清晰的锚点。假设每份文档都存在可以用核心触发词替代的重复表述——去找到它们。
否定表述是这一方法的失效模式：通过禁止性表述引导行为会将被禁止的行为带入上下文，使其更容易被触发，而非更难。比如“别想大象”，结果满脑子都是大象；否定是弱修饰词，会被强激活的概念覆盖，导致禁令反而像是执行该行为的指令。应使用肯定表述——明确目标行为（如“编写单行注释”），避免提及被禁止的行为。只有当无法用肯定表述明确硬约束时，才使用禁止性表述；即使如此，也要搭配肯定的目标行为，让注意力集中在应做的事情上。
精简原则
- 每个含义只保留单一权威来源：一个权威位置，这样修改行为只需在一处编辑。重复内容——同一含义出现在多个地方——会增加维护成本和令牌消耗，还会错误地提升该含义在信息层级中的地位。（这与核心触发词相反，核心触发词是故意重复令牌，而非重复含义。）
- 环境配置也是权威来源之一——脚本、配置文件、目录结构、输出——重述这些内容的文档属于缓存：查找结果的副本，只有当原查找成本很高时才值得消耗负载。缓存Agent无法通过查找获取的内容：不成文的约定、选择背后的原因、配置未提及的陷阱。将单文件、单命令可查找的内容留给环境配置，避免内容过时。
- 检查每一行的相关性：它是否仍与文档的用途相关？某行内容失去相关性的原因可能是从未对任务产生影响（如纯粹的说明性内容，或应披露的分支场景），或随着描述的行为或外部环境变化而过时。更短的文档更容易保持相关性。如果没有精简的习惯，文档最终会沉淀过时内容：过时的内容层积累下来，因为添加内容感觉安全，删除则有风险，直到你必须层层挖掘才能找到仍有效的内容。
- 逐句寻找无效表述：模型默认已经遵守的指令只会消耗负载却没有实际作用。测试标准——它是否会改变模型的默认行为？——是基于模型而非读者的：两个人对某表述是否无效有分歧，本质是对模型默认行为的认知不同，应通过执行文档验证，而非争论。如果某句子无效，应整句删除，而非删减词汇。该测试也适用于核心触发词：如果词汇太弱无法改变默认行为（如当Agent本来就比较全面时使用_be thorough_），就是无效表述，解决方法是使用更强的词汇（如_relentless_），而非更换技巧。