Writing For Agents Zh

---
name: writing-for-agents-zh
description: 给 Agent 写文档、写 SKILL.md、写 AGENTS.md / CLAUDE.md、写规则文件、让 Agent 每次跑都稳定。当用户说「怎么写一个好的 SKILL.md」「AGENTS.md 该写什么」「技能描述怎么写才会被触发」「文档太长 Agent 不看」「同一个技能每次表现不一样」「什么时候该拆成两个技能」时使用。核心概念：上下文指针（描述与规则行的措辞决定 Agent 何时去读）；两种负担（上下文负担 vs 认知负担）；信息层级（文件内步骤 > 文件内参考 > 披露到外部的参考）与渐进披露、同处放置、蔓延；每步的完成标准（清晰度与要求度、过早完成、后续步骤的拉力）；何时拆分（按序列、按调用方式）；引导词（用模型预训练里已有的紧凑概念锚定行为，正面表述优于禁止）；修剪（单一事实来源、环境即缓存、相关性、空操作句）。技能专属：模型调用 vs 用户调用、路由技能。也覆盖「改得更容易被正确触发」「别写成一本手册」「老是漏掉后面的步骤」这类说法。改编自 Matt Pocock 的 writing-for-agents（MIT）。
author: Captain
version: 0.1.1
display_name: "给 Agent 写文档（技能与规则文件）"
display_name_en: "Writing for Agents (zh)"
description_zh: "让技能、AGENTS.md、规则文件每次都被正确读取与执行：上下文指针措辞、两种负担、信息层级与渐进披露、完成标准、何时拆分、引导词与正面表述、修剪空操作句；附技能的调用方式选择与路由技能。"
description_en: "Make skills, AGENTS.md and rules files read and executed reliably: pointer wording, the two loads, information hierarchy and progressive disclosure, completion criteria, when to split, leading words and positive phrasing, pruning no-ops; skill invocation choice and router skills."
tags:
  - "SKILL.md"
  - "AGENTS.md"
  - "CLAUDE.md"
  - "prompt engineering"
  - "文档设计"
  - "上下文指针"
  - "Agent 文档"
examples_zh:
  - "帮我把这个 SKILL.md 改得更容易被正确触发"
  - "写一份 AGENTS.md，别写成一本手册"
  - "这个技能 Agent 老是漏掉后面的步骤，怎么改"
examples_en:
  - "Rewrite this SKILL.md so it triggers reliably"
  - "Write an AGENTS.md that isn't a manual"
  - "The agent keeps skipping later steps of this skill, how do I fix it"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "✒️" } }
---

# 给 Agent 写文档

任何 Agent 消费的文档——技能、`AGENTS.md` / `CLAUDE.md`、被指针引到的文档——包装不同，写法相同：同样的杠杆让每一份都**可预测**，因为 Agent 每次跑的是同一个**过程**，而不是产出同样的输出。

## 上下文指针
**上下文指针**是 Agent 上下文里的一条引用：点名某份上下文外的材料，并编码去读它的条件。技能的 description 是一个；`AGENTS.md` 里点名某文档的一行也是。指针的**措辞**（不是目标）决定 Agent 何时去读、多可靠。必读的目标配一条措辞软弱的指针就是方差 bug：先磨措辞，磨不动再把材料内联。
指针做两件事：说明材料是什么，列出触发它的**分支**（文档处理的不同情形）。始终加载的指针每个字每回合都在花钱，所以比正文更要狠修：**把引导词放最前**（指针在这里做触发工作）；**一个分支一个触发词**（同一分支的同义词是写了两遍，合并；只留真正不同的分支）；**删掉正文已经承载的身份说明**。

## 两种负担
每份文档、每个指针都在花两种预算之一：**上下文负担**——始终加载材料对 Agent 窗口的成本（`AGENTS.md` 的一行、技能描述，不管触不触发每回合都在花 token 和注意力）；**认知负担**——对人的成本（哪些文档存在、何时该找哪个，人是索引）。认知负担不是要最小化的东西，是人类自主权的代价：把它花在人的判断重要的地方，从不重要的地方拿掉。只通过指针到达的材料逃过上下文负担，代价是指针那一行；完全没有指针的材料全靠认知负担。

## 信息层级
文档由两种内容构成：**步骤**（Agent 按序执行的动作）与**参考**（按需查阅的定义、规则、事实）。核心决策是每块内容放在**信息层级**的哪一级——按 Agent 需要它的紧迫度排的梯子：1 **文件内步骤**（主级：做什么、按什么顺序）；2 **文件内参考**（按需查阅，常是一组平级规则，这很正常不是坏味道）；3 **披露的参考**（推到单独文件，靠指针到达，指针触发才加载；从同目录的兄弟文件到任何文档都能指向的外部参考）。推得太少顶部臃肿，推得太多藏起了 Agent 真需要的东西——这个张力就是整个决策。
**渐进披露**是沿梯子往下推（出主文件、藏到指针后）以保持顶部可读。它主要不是 token 优化，是保护层级的方式。分支是最干净的披露测试：每个分支都需要的内联，只有部分分支到达的推到指针后。文档有步骤时，本该披露的文件内参考会埋掉步骤，让"注意到它们"变成掷硬币——这是方差杠杆，不只是可读性杠杆。
**同处放置**是文件内的伴侣：梯子决定放多深，同处放置决定放在那一级时旁边是什么。一个概念的定义、规则、注意事项放在一个标题下而不是散落，读一处就带出邻居。测试：文档读起来像为 Agent 写的文档；分组的材料读起来是，散落的不是。（区别于重复：重复是一个意思出现在两处；散落是一个意思碎在多处。）
**蔓延**是这里的失败模式：文档就是太长，哪怕每行都活、都独一无二。注意力在多余上变薄，每多一行就多一行要维护相关性。解法就是梯子：把参考披露到指针后，按分支或序列拆分让每条路径只带它需要的。

## 步骤与完成标准
每个步骤止于一个**完成标准**——告诉 Agent 工作已完成的条件。两个属性让它成为杠杆：**清晰度**——Agent 能否区分完成与未完成？模糊的界限（"达成理解"）招来**过早完成**：注意力滑向"已完成"而提前结束。可见的后续步骤提供拉力，标准的清晰度提供阻力。按序防御：先磨锋界限（局部且便宜）；只有它本质上模糊**且**你观察到了冲刺，才通过拆序列把后续步骤藏起来——藏只在真正的上下文边界起作用（交接或子代理派发；行内调用让后续步骤留在上下文里，什么都清不掉）。**要求度**——它要求多少。"每个被改的模型都已核对"逼出彻底的工作，"产出一份变更清单"不会。要求度驱动**跑腿**（Agent 在工作中做的挖掘，潜藏在措辞里而不是写成独立步骤），且不限于步骤："每条规则都已应用"约束一组平级参考，正如"每一步都已做"约束一个序列——全参考文档也能承载穷尽性标准。最强的标准既可核对又穷尽。

## 何时拆分
把一份拆成两份要花两种负担之一，只在值得时拆：**按序列**——后续步骤诱使 Agent 冲过眼前这一步时拆开，看不见后续能驱动更多跑腿；反过来小心：合并序列把每一步的后续暴露给下一步，招来过早完成。**按调用方式**——技能专属，见下。

## 引导词
**引导词**是模型预训练里已有的紧凑概念，Agent 在执行文档时用它思考（*课*、*迷雾*、*曳光弹*）。作为一个 token 反复出现而不是一句话，它累积一个分布式定义，用最少的 token 锚定一整片行为，靠的是模型已有的先验。自造词也行但要定义清楚——自造词招不来先验，你要用定义的 token 付预训练词白送的东西；先找现成的词。
它锚定两次。正文里锚定**执行**：词每次出现 Agent 都伸手去拿同一行为，在平级参考里聚焦注意力到一类要找的东西。指针里锚定**调用**：同一个词住在你的提示词、文档、代码库里时，Agent 把共享语言与材料关联，更可靠地去读。
主动找机会用引导词重构：在三处拼写出来的三元组、花一句话比划一个概念的指针，都是求着坍缩成一个 token 的段落——"快、确定、低开销" → *紧*（一个*紧*的回路）；"一个你信得过的回路" → *红*，把模糊的门变成二元可观察状态（回路对 bug 变*红*，或不变）。你赢两次：更少 token、更锋利的钩子。假设每份文档都带着引导词能退役的复述，去找。
**否定**是这个杠杆旁的失败模式：用禁止来引导会把被禁行为拖进上下文并让它**更**可得，不是更少。"别想大象"，大象就是一切；否定是弱修饰，被强激活的概念淹没，禁令半读成做那件事的指令。提示**正面**目标（"写一行注释"），被禁的那件事永远不被说出。禁止只有在无法正面表述的硬护栏上才值得，即便如此也配上正面目标让注意力落在该做的事上。

## 修剪
- 每个意思保持**单一事实来源**：一个权威位置，改行为是一处编辑。**重复**（同一意思在多处）花维护与 token，还把一个意思在梯子上的显赫程度抬过它真实的位次。（引导词的意外反面：引导词有意重复 token，从不重复意思。）
- **环境**也是事实来源（`package.json` 脚本、配置文件、目录布局、`--help` 输出），复述它的文档是**缓存**：一次查找的副本，只在查找昂贵时值得它的负担。缓存 Agent 靠看找不到的：不成文的约定、选择背后的理由、没有配置会坦白的坑。一文件一命令的查找留给环境，它不会过期。
- 逐行检查**相关性**：它还影响文档要做的事吗？一行会因为从不影响任务（纯说明，或该被披露的分支）或随行为与世界变化而过时失去相关性。更短的文档更容易保持相关。没有修剪纪律，默认命运是**沉积**：陈旧的层因为加感觉安全、删感觉危险而沉降，直到你得钻穿它们才找到还活着的东西。
- 逐句猎杀**空操作**：模型默认就会做的指令是花了负担什么都没说。测试（相对默认行为有没有改变？）是相对模型的，不是相对读者的：两人对某句是否空操作有分歧，是对默认的分歧，靠跑文档解决而不是辩论。一句不过关就删整句，不是删几个词。这个测试也给引导词打分：弱到打不过默认的词（Agent 已经挺彻底时说*要彻底*）是空操作，修法是更强的词（*不留死角*），不是换技术。

## 技能专属：调用方式与路由
两种选择，换的是两种负担：**模型调用**的技能保留 description，Agent 能自主触发它、其他技能能引用它；你仍能手动输入名字（模型调用总是包含人的触达）。description 是技能的顶层指针，被迫始终加载：以永久上下文负担换可发现性。一个内容全是参考的模型调用技能也是共享参考的家：别的技能能调它，多个技能需要的参考住在一处。写法：不设 `disable-model-invocation`，写面向模型的、带触发分支的描述。**用户调用**的技能把 description 剥离出 Agent 的触达：只有人输入名字才能调，任何技能都调不了。零上下文负担，但花认知负担：你是必须记得它存在的索引。写法：`disable-model-invocation: true`，description 变成面向人的一行摘要，去掉触发列表。只在 Agent 必须自己触达它、或别的技能必须触达它时选模型调用；只由人手动触发的就做成用户调用、不付上下文负担。两个用户调用技能都需要的共享参考不能住在任一方（没有描述就互相触达不了），推到技能系统之外的普通文件。
**按调用方式拆分**：有一个该独自触发的独特引导词（你在提示里真会用的触发词）、或别的技能必须触达时，拆出一个模型调用技能——为新的始终加载的描述付上下文负担，所以那份独立触达得值。
**路由技能**：用户调用技能多到记不住时，用一个用户调用的**路由技能**：点名其他技能与各自何时用，人只需记住一个。它只能提示不能触发它们：用户调用技能没有描述，除了人没有东西能触达它们。

## 改一份文档前自检
```
- [ ] description 把触发分支的引导词放在最前
- [ ] 每一步都有清晰、可核对的完成标准
- [ ] 只在真正的上下文边界才把内容拆到指针之后
- [ ] 每个意思只有一处权威来源，没有散落的复述
- [ ] 逐句过了一遍空操作测试，删掉了模型默认就会做的句子
```

---
改编自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 `writing-for-agents`（MIT）。改动见 ATTRIBUTION.md。