Writing for Agents 技能：把文档写成可执行指令

专门讲怎么写 SKILL.md、AGENTS.md，让代理每次都能走对流程。

写完一份技能文档，最挫败的体验是：你自己看得懂，代理却时而照做时而乱来。Writing for Agents 就是专门解决这个偏差的——它不教你写“好文章”，而是教你写“代理能稳定执行的文件”。核心观点很清醒：代理每次跑的是同一套过程，而不是产出同一个结果，所以文档的目标是可预测，不是好看。

核心能力

1. 上下文指针：用措辞决定代理会不会去读

技能里把“指针”定义为：存在上下文里的一句引用，它指向某份不在上下文里的材料，并编码了去读它的条件。技能描述是一类指针，AGENTS.md 里提到某份文档的那一行也是。关键在于：指针的措辞而不是目标，决定了代理什么时候会去读、读得多可靠。常见故障是“材料很关键但指针写得很弱”，修法是先把措辞写硬，实在不行再把材料内联进来。

2. 两种成本：上下文负载与认知负载

技能区分了两笔预算。上下文负载是常驻内容每轮都在花的 token 与注意力，比如 AGENTS.md 的一行；认知负载是压在人脑上的——“到底有哪些文档、什么时候该用哪份”。后者不该无限压缩，它是人的掌控感的代价；该做的是把它花在需要人判断的地方。这个区分能解释为什么很多团队的 AI 规范越写越多，效果却越来越差。

3. 信息层级与渐进披露

它把内容排成一个阶梯：文件内步骤是第一层（代理按顺序做的事），文件内参考是随时查阅的第二层，被推到独立文件、靠指针触发的第三层。推到下面的太多，代理会找不到真正需要的东西；推得太少，顶部会臃肿。判断标准很实用：每个分支都需要的内联，只有部分分支会用的才往后推。

4. 完成标准：可判定且穷尽

每个步骤都要有一个“完成标准”，用它告诉代理什么叫做完了。写得模糊（比如“理解到位”）会引发过早完成：代理会在真的做完之前就收手。防御顺序是先收紧边界，实在模糊且你确实观察到它在抢跑，才把后续步骤拆到另一个上下文里。“每个改动的模型都要交代”比“给一份变更清单”要求高得多，强度靠措辞而不是靠感叹号。

5. 引领词与禁止句的反效果

它建议用预训练里已经存在的紧凑概念当“引领词”（比如 red、tight），反复以 token 形式出现，而不是每次重新定义。同时提醒：禁止式写法会把被禁的行为拉进上下文，反而让它更可得。“不要想大象”就是范例。正确做法是直接写正面目标（“写单行注释”），让被禁的行为压根没被说出口。

使用上手

1. 先分清你要写的是哪种文档：技能（带 frontmatter）、AGENTS.md/CLAUDE.md、还是被指针指向的参考文档。写技能时先读技能目录里的 SKILL-MECHANICS.md。
2. 列出代理在这个文档里会走的所有分支（不同情况走不同路径）。一张表列出来，标出哪些是主路径、哪些是少见分支。
3. 按分支决定内容位置：每个分支都要用的写进主文件；只有部分分支用的推到单独文件，并在主文件写一行措辞明确的指针。
4. 给每个步骤加完成标准，用能判定对错的句子，而不是形容词。写完自查：一个新人能不能只看这句就知道做完了没。
5. 扫一遍全文找这两种句子：模型默认就会做的（无效句）、用禁止句代替正面指令的。一律删改，别留恋。
6. 最后查重复：同一个意思是否在两处出现。重复会让它在层级里的权重被虚抬，且以后改行为要改两处。

优点与不足

优点

• 把“写提示词”从经验变成可检查的工程方法。
• 两种负载的区分非常好用，能解释很多“越写越差”的现象。
• 完成标准、引领词、禁止句三条可直接落地。
• 自带 SKILL-MECHANICS，讲清了技能该不该自动触发、路由技能怎么写。

不足

• 内容密度很高，第一遍读容易抓不住重点，需要边写边回查。
• 面向的是写 Agent 文档的人，普通写作场景用处不大。
• 部分例子依赖英文语感（引领词），中文场景要自己换例子。
• 没有现成模板，需要你按它的原则自己搭。

适合谁

• 正在写或维护 Skill 的技能作者。
• 给团队维护 AGENTS.md、CLAUDE.md 的工程负责人。
• 发现“AI 时好时坏”、想从文档层面降方差的人。
• 想把内部规范交给 Agent 执行、又不想写长篇提示词的人。

下载与访问

• 使用方式：WorkBuddy 对话中调用 writing-for-agents
• 技能目录：~/.workbuddy/skills/writing-for-agents
• 配套文档：同目录下 SKILL-MECHANICS.md

获取与授权

本文属于「技能」分类的 AI 资源专栏，更多评测见分类页。