Writing for Agents - 为智能体编写文档的写作指南

技能概述

Writing for Agents 是一套面向 AI 智能体的文档写作方法，用于编写 skill、AGENTS.md、CLAUDE.md 以及任何通过指针被智能体读取的文档。它的核心判断是：智能体每次运行走的都是同一套过程，而不是产出同一份结果，所以写作的目标是让过程变得可预测——该触发的地方稳定触发，该做完的地方真正做完。

适用场景

1. 编写或修改一个 skill：当你要写 SKILL.md、设计 description、决定哪些内容内联、哪些内容拆到单独文件时，这套方法给出判断依据。技能类文档的 frontmatter、调用方式选择与路由型技能另见 SKILL-MECHANICS.md。

2. 维护 AGENTS.md / CLAUDE.md 这类常驻文档：这类文件每一行都在每一轮对话中消耗上下文。当文档随着时间越写越长、开始出现沉淀的陈旧内容时，本技能提供修剪与分层的方法。

3. 智能体的执行结果不稳定，需要从文档侧修：典型表现是技能说明写了但很少被触发、步骤没做完就草草收尾、同一份文档两次运行走了完全不同的路径。这些是文档措辞问题，不是模型问题。

核心功能

1. 上下文指针设计：指针是存在于智能体上下文中、指向外部材料并编码了"何时去取"条件的引用——技能的 description 是一个指针，AGENTS.md 里指向某份文档的一行也是同一个对象。技能讲解如何让指针同时完成两件事：说明材料是什么，以及列出应该触发它的分支；并给出指针的修剪规则（前置核心词、一个分支一个触发词、删掉正文已承载的身份信息）。必须保留的材料配了一个措辞孱弱的指针，是一个方差缺陷：先修措辞，措辞修不好才内联。

2. 信息层级与渐进式披露：文档由步骤（智能体按序执行的动作）和参考（按需查阅的定义、规则、事实）两类内容构成，本技能提供一把梯子来安放它们——文件内步骤、文件内参考、经指针披露的外部参考。判断标准是分支：每个分支都要用的内联，只有部分分支会读的推到指针后面。配套的共置原则要求一个概念的定义、规则和注意事项放在同一标题下，避免同一含义散落多处；蔓延则是这里的失败模式，即文档单纯过长，即便每一行都还有效。

3. 步骤、完成标准与修剪：每个步骤都以一个完成标准收尾，即判断工作已完成的那个条件。它靠两个属性起作用：清晰度（智能体能否分辨做完与没做完，模糊的边界会招致提前完成）和要求强度（"每个改动的模型都要有交代"比"产出一份变更列表"逼出更多跑腿工作）。当标准天然模糊且确实观察到抢工，可以把后续步骤切出去——但切分只在真正的上下文边界上有效。修剪部分给出可执行的删减准则：单一事实来源、把环境本身当作事实来源、以及逐句排查无效句（模型默认就会遵守的指令，删掉整句而不是删词）。

常见问题

什么是上下文指针？它和普通引用有什么区别？

上下文指针是存在于智能体上下文中的一条引用，它命名了某份不在上下文里的材料，并编码了去取这份材料的条件。技能的 description、AGENTS.md 里指向某份文档的一行，都是同一个对象。关键区别在于：决定智能体何时去读、以及读得可不可靠的，是指针的措辞，而不是它指向的目标。所以指针写得含糊，材料再重要也可能不被读到。

怎么判断一段内容是内联还是拆到单独文件？

用分支来切：每个分支都必须读的内容内联，只有部分分支才会读到的内容推到指针后面。这就是渐进式披露，它主要不是为了省 token，而是为了保护层级——参考内容内联过多会埋掉步骤，让智能体注不注意步骤变成抛硬币。反方向也要当心：推得太狠，会把智能体真正需要的材料藏起来。这个张力就是全部决策所在。

什么是领衔词？中文文档也能用吗？

领衔词是一个已经存在于模型预训练里的紧凑概念（比如"课程""战争迷雾""曳光弹"），智能体在执行文档时用它来思考。它以 token 的形式反复出现，而不是以句子的形式，从而积累出一个分布式定义。它在两处起作用：在正文里锚定执行行为，在指针里帮助调用——当同一个词同时出现在你的提示词、文档和代码库里，智能体更容易把材料和它联系起来。自造词也可以，但自造词调动不了预训练先验，你会为定义付出本该免费的 token，所以优先找现成的词。

为什么文档里要少写"不要做某事"？

否定式是一种失效模式：用禁止来引导，会把被禁的行为一并拖进上下文，让它变得更容易被想到。否定只是一个弱修饰语，会被强烈激活的概念压过去，于是禁令有一半读起来像在指示去做那件事。正确做法是提示正面目标（比如直接写"写单行注释"），让被禁止的行为根本不被说出口。只有当你无法正面表述、且它是一条硬性护栏时，禁止句才值得保留——即便如此也要配上正面目标，让注意力落在该做的事上。

什么时候应该把一个技能拆成两个文档？

只在切分本身能挣回成本时才拆，因为每拆一次都要花掉两种负载中的一种。按序列拆：当后续步骤的存在会诱使智能体草草做完眼前这一步时，把后面的步骤移出视野，能逼出更多跑腿工作。反过来也要当心——把两段序列合并，会让每一步的后续步骤暴露给下一步，反而招致提前完成。按调用方式拆是技能特有的情况，见 SKILL-MECHANICS.md。

怎么判断哪句话属于该删的无效句？

逐句做同一个测试：这句话相对于模型的默认行为，改变了什么？没有改变的就是无效句。这个测试是相对于模型而言的，不是相对于读者而言的——两个人对某句是不是无效句有分歧，其实是对默认行为有分歧，靠运行文档来验证，而不是靠辩论。一句话没通过测试时，删掉整句，而不是从里面抠掉几个词。这个测试同样适用于评估领衔词的强度：一个弱到压不过默认行为的词（智能体本来就还算细致时，你写"要细致"）就是无效句，解法是换一个更强的词，而不是换一种技巧。