writing-for-agents

Files (3)

• SKILL-MECHANICS.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

编写任何 Agent 会消费的文档时的参考：一份 Skill、一份 `AGENTS.md` / `CLAUDE.md`、一份通过指针到达的文档。包装不同，写法相同：同一组杠杆让每次运行都走同一套*过程*，而不是产出同一份结果。

当前文档是 Skill 时，阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)，了解 frontmatter、调用方式选择，以及路由 Skill。

## 上下文指针

**上下文指针（context pointer）** 是留在 Agent 上下文中的引用：它点名一份当前不在上下文里的材料，并编码何时去取。Skill 的 description 是一种指针；`AGENTS.md` 里点名某份文档的一行也是同一种对象。决定 Agent 会不会去取、以及取得到多可靠的，是指针的*措辞*，不是目标本身。一份必须到达的材料，若指针措辞疲弱，就是方差缺陷：先把措辞写锋利；只有锋利之后仍不够，才把材料内联进来。

指针做两件事：说明材料是什么，并列出应触发读取的**分支**（分支是文档处理的不同情形，因此不同运行会走不同路径）。始终加载的指针里，每个词每个回合都在花钱，所以它比正文更需要修剪：

- **把引导词放到最前**：指针正是引导词发挥触发作用的位置。
- **每个分支一个触发条件。** 只是给同一分支换同义词，等于把一条分支写了两遍；合并它们，只保留真正不同的分支。
- **删掉正文已经携带的身份信息。**

## 两种负载

你加入的每份文档和每个指针，都会花掉两种预算之一：

- **上下文负载（context load）** 是始终加载的材料对 Agent 窗口的成本：`AGENTS.md` 的一行、Skill description、每个回合都坐在上下文里的任何东西，无论有没有触发，都在消耗 token 和注意力。
- **认知负载（cognitive load）** 是对人的成本：存在哪些文档、何时去取每一份。人就是索引。这不是要尽量压到零的成本：它是人保有主动权的代价；花在需要人判断的地方，从人不需要判断的地方拿掉。

只通过指针到达的材料躲开了上下文负载，代价是指针自己那一行；完全没有指针的材料，全部骑在认知负载上。

## 信息层级

文档由两种内容构成：**步骤**（Agent 按顺序执行的动作）和**参考**（按需查阅的定义、规则、事实）。两者可以自由混合：全是步骤（一份配方）、全是参考（一次审查的规则、本 Skill），或两者都有。核心决定是每块内容落在**信息层级**的哪一档：这是按 Agent 立刻需要材料的程度排列的梯子。

1. **文内步骤**是主档：Agent 按顺序做什么。
2. **文内参考**按需查阅。常常是一组合法的扁平同类项（审查的每条规则都在同一档），这是正常安排，不是坏味道。
3. **披露参考**被推到单独文件，由上下文指针到达，只在指针触发时加载。范围从同目录兄弟文件，到任何文档都能指向的完全外部参考。

往下推得太少，顶部会膨胀；推得太多，又会藏起 Agent 真正需要的材料。这组张力就是全部决定。

**渐进式披露**是沿梯子往下走（离开主文件、藏到指针后面），让顶部保持可读。它首先保护层级，token 优化只是附带结果。分支是最干净的披露测试：每个分支都需要的内容内联，只有部分分支才到达的内容放到指针后面。文档含有步骤时，本该披露的文内参考会把步骤埋住，让“有没有看到步骤”变成抛硬币：这是方差杠杆，不只是可读性杠杆。

**共置**是文件内部的配套规则：梯子决定一块内容*往下走多远*，共置决定它落到那一档后*旁边放什么*。把一个概念的定义、规则和例外放在同一个标题下，不要拆散，这样读到一部分就会带上邻居。检验标准：文档读起来应像写给 Agent 的说明。成组的材料是这种感觉；拆散的材料不是。（这和重复不同：重复是同一含义写了两处；拆散是把一个含义撕成许多碎片。）

**蔓延**是这里的失败模式：文档就是太长，即便每一行都还活着、都不重复。注意力被多余部分摊薄，多出来的每一行都要继续保持相关。治法仍是这把梯子：把参考披露到指针后面，并按分支或序列拆分，让每条路径只携带它需要的内容。

## 步骤与完成标准

每个步骤都以**完成标准**结束，即告诉 Agent 工作已经做完的条件。两件事让它成为杠杆：

- **清晰**：Agent 能否分清做完和没做完？含糊边界（“已经理解”）会诱发**过早完成**：步骤其实还没做完就结束，注意力滑向*做完这件事本身*。后面仍看得见的步骤（**完成后步骤**）提供拉力；完成标准的清晰度提供阻力。按这个顺序防守：**先把边界写锋利**（局部、便宜）；只有边界本质上就模糊、*并且*你观察到抢跑时，才通过拆分序列把后续步骤藏起来。隐藏只在真正的上下文边界上有效（交接或子 Agent 分派；内联调用会把后续步骤留在上下文里，清不掉任何东西）。
- **要求**：它要求做多少。“每个被修改的模型都已交代”会迫使工作做透，“产出一份变更列表”则不会。要求驱动**实地工作（legwork）**（Agent 在工作内部做的挖掘，潜伏在措辞里，而不是写成单独一步），而且它不绑定在步骤上：“每条规则都已应用”约束一整块扁平参考，正如“每一步都已完成”约束一条序列。全是参考的文档，也因此仍能带上穷尽门槛。

最强的完成标准既可核对，又穷尽。

## 何时拆分

把一份文档拆成两份会花掉两种负载之一，所以只有切口赚回这笔开销时才拆：

- **按序列**：拆开一段步骤，若完成后步骤会诱使 Agent 抢跑眼前这一步。把后续步骤移出视野，会迫使当前任务做更多实地工作。反向合并同样危险：把序列并回去，会让每一步看见后面的步骤，诱发过早完成。
- **按调用方式**，仅适用于 Skill：见 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)。

## 引导词

**引导词（leading word）** 是已经活在模型预训练里的紧凑概念，Agent 执行文档时用它来思考（_lesson_、_fog of war_、_tracer bullets_）。它作为 token 反复出现，绝不要写成句子；这样会积成分布式定义，并用最少 token 锚定一整片行为，因为它征用了模型已经持有的先验。自己造词也可以，前提是定义清楚；但生造词征用不到先验：你用定义 token 付的，正是预训练词免费给的。先找已经存在的词。

它锚定两次。在正文里，锚定*执行*：这个词每次出现，Agent 都去够同一套行为；在扁平参考里，它把注意力收束到要找的那一类东西。在指针里，锚定*调用*：同一个词同时活在你的提示词、文档和代码库里时，Agent 会把这套共享语言连到材料上，取用也更可靠。

主动寻找能用引导词重构的机会。三处写开的三位一体、指针花一整句去比划一个想法。每一处都在求你把它收成一个 token：

- “fast, deterministic, low-overhead” → _tight_（一个 _tight_ 闭环）。
- “a loop you believe in” → _red_，把含糊门槛收成可观察的二元状态（闭环在缺陷上变 _red_，或者没有）。

你赢两次：更少 token，以及 Agent 挂靠思考的更锋利钩子。假定每份文档都在携带引导词可以退役的复述。去找它们。

优先直接说明目标行为，并把容易误判的边界与正例放在一起。授权、安全和数据保护等必要禁令保留。不同措辞是否有效要通过具体任务验证，不根据修辞偏好推断固定的失败概率。

## 修剪

- 每个含义只放在**唯一事实来源**：一个权威位置，改行为时只改一处。**重复**（同一含义出现在不止一处）耗费维护和 token，还会让这个含义在梯子上的位置虚高。（这是引导词的意外反面：引导词有意重复 token，从不重复含义。）
- **环境**也是事实来源（`package.json` scripts、配置文件、目录布局、`--help` 输出）。复述环境的文档是一份**缓存**：查找结果的副本，只有查找很贵时才配占用负载。缓存 Agent 看一眼找不到的东西：未写下的约定、某个选择背后的理由、配置文件不肯坦白的陷阱。把“一个文件、一条命令就能查到”的内容留给环境，那里不会过期。
- 检查每一行的**相关性**：它是否仍作用于这份文档要做的事？一行失去相关，要么从未作用于任务（纯说明，或本该披露的分支），要么所描述的行为或世界已经变了。更短的文档更容易保持相关。没有修剪纪律，默认结局是**沉积**：过期层堆下来，因为添加显得安全、删除显得冒险，直到你必须向下掏芯，才能找到仍然活着的部分。
- 逐句猎取**空操作**：模型默认就会遵守的指令，花负载却什么也没说。检验（相对默认行为，它有没有改变行为？）是相对模型的，不是相对读者的：两个人对空操作意见不合，其实是对默认行为意见不合，应用运行文档来结算，而不是靠辩论。句子不及格时，删掉整句，不要只剪几个词。这个检验也给引导词打分：弱到打不过默认的词（Agent 已经够 thorough-ish 时还说 _be thorough_）就是空操作；修法是换更强的词（_relentless_），不是换另一种手法。

From iZiTTMarvin/agent-skills-zh, MIT.

More from iZiTTMarvin/agent-skills-zh