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