writing-for-agents

Files (3)

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

SKILL.md (first lines)

撰写任何智能体会消费的文档的参考——一个技能、一份 `AGENTS.md` / `CLAUDE.md`、一份通过指针取用的文档。包装不同；写法不变：同样的那些杠杆让每一种都变得可预测——智能体每一次运行都采取同样的_过程_，而非产出同样的输出。

当你正在撰写的文档是一个技能时，读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)，了解 frontmatter、调用选择，以及路由器技能。

## 上下文指针

一个**上下文指针（context pointer）**是持在智能体上下文里、点名某份上下文之外材料并编码取用它之条件的一份引用。一个技能的描述是其中之一；`AGENTS.md` 里点名某文档的一行是同一个对象。指针的_措辞_、而非它的目标，决定了智能体何时去取用那份材料——以及多可靠。一个措辞薄弱的指针背后放一个必备目标，是一个方差 bug：先把措辞磨锋利，只有当磨锋利失败时才把材料内联。

一个指针做两件事——陈述材料是什么，并列出应当触发去取用它的那些**分支（branches）**（一个分支是文档所处理的一个不同情形，所以不同的运行走过它的不同路径）。一个始终加载的指针的每一个字都在每一轮上花费代价，所以它挣得比正文更狠的修剪：

- **把引导词前置** —— 指针正是它做触发工作的地方。
- **每个分支一个触发。** 给单一分支改名的同义词，是把一个分支写了两遍；把它们合并，只保留真正不同的分支。
- **砍掉正文已经承载的身份信息。**

## 两种负载

你每添加一份文档和一个指针，都花费两种预算之一：

- **上下文负载（Context load）** —— 始终加载的材料在智能体窗口上的代价：一行 `AGENTS.md`、一段技能描述，任何每轮都坐在上下文里、无论是否触发都花费词元和注意力的东西。
- **认知负载（Cognitive load）** —— 落在人类身上的代价：哪些文档存在，以及何时去取用每一个。人类就是索引。这不是一项要最小化的代价——它是人类能动性的价格；把它花在人类判断力重要之处，把它移除于无关紧要之处。

只通过一个指针取用的材料，以指针自己那一行为代价而逃离上下文负载；完全没有指针的材料，则整个骑在认知负载上。

## 信息层级

一份文档由两种内容类型构成——**步骤（steps）**（智能体按顺序执行的动作）与**参考（reference）**（按需查阅的定义、规则、事实）——它们自由混合：全是步骤（一份食谱）、全是参考（一次审阅的规则、这个技能），或两者兼有。核心决策是每一块坐在**信息层级**上的哪个位置，这是一道按智能体多急切地需要该材料来排名的阶梯：

1. **文件内步骤** —— 首要层级：智能体做什么，按顺序。
2. **文件内参考** —— 按需查阅。常常是一个名正言顺的扁平同级集（一次审阅的每一条规则在同一档上）——一种妥当的安排，而非一种坏味道。
3. **被披露参考** —— 推出到一个单独的文件里，由一个上下文指针取用，只在指针触发时加载。范围从同一文件夹里的一个同级文件，一直到住在任何地方、任何文档都能指向的完全外部参考。

往下推得太少，顶端会臃肿；往下推得太多，你会藏起智能体真正需要的材料。那份张力就是整个决策。

**渐进式披露（Progressive disclosure）**是沿这道阶梯向下的动作——移出主文件、置于一个指针背后——好让顶端保持清晰可读。它主要不是一项词元优化：它是层级如何被保护的方式。分支是最干净的披露测试：内联每一条分支都需要的东西，把只有部分分支才取用的东西推到一个指针背后。当一份文档有步骤时，本该被披露的文件内参考会把它们埋起来，并把留意它们变成一次抛硬币——这是一个方差杠杆，而不只是一个清晰度杠杆。

**同址（Co-location）**是文件内的伴侣：阶梯决定一块材料坐得_多靠下_，同址则决定它一旦到了那里_旁边坐着什么_。把一个概念的定义、规则和注意事项放在一个标题之下，而非散落各处，好让读到其中一部分就把它的邻居一并带来。判据是：文档应当读起来像是为智能体写的文档——成组的材料读起来是那样，散落的材料则不然。（与重复不同：重复是把一个含义放在两处；散落是把一个含义割裂在许多处。）

**蔓生（Sprawl）**是这里的失败模式：一份文档单纯太长，即便每一行都在生效且独一无二。注意力在这份过量里变薄，而每一多出的行都是又一行要去保持相关。解药是那道阶梯：把参考披露到指针背后，并按分支或顺序拆分，好让每条路径只承载它需要的东西。

## 步骤与完成标准

每个步骤都结束于一个**完成标准（completion criterion）**——那个告诉智能体活儿干完了的条件。有两个属性让它成为一个杠杆：

- **清晰度（Clarity）** —— 智能体分得清完成与未完成吗？一个含糊的边界（「达成理解」）会招致**过早完成（premature completion）**：在步骤真正完成之前就结束它，注意力滑向_已经完成_。仍在前方可见的那些步骤——**完成后步骤（post-completion steps）**——提供拉力；标准的清晰度是阻力。按顺序防御：**先把边界磨锋利**（局部且廉价）；只有当它不可化约地模糊_并且_你观察到那种急躁时，才通过拆分顺序把后面的步骤藏起来——而藏起来只在一个真正的上下文边界上才起作用（一次交接或一次子智能体派发；一次内联调用会把后面的步骤留在上下文里，什么都不清除）。
- **要求度（Demand）** —— 它要求多少。「每一个被修改的模型都被交代清楚」逼出彻底的工作，而「产出一份改动清单」则不会。要求度驱动**跑腿功夫（legwork）**——智能体在工作内部所做的挖掘，潜伏在措辞里而非写成它自己的一个步骤——而且它不受步骤约束：「每一条规则都被应用」约束一体扁平参考，正如「每一步都完成」约束一个顺序，这就是一份全是参考的文档仍然承载一道穷尽性门槛的方式。

最强的标准既可核查又穷尽。

## 何时拆分

把一份文档拆成两份会花费两种负载之一，所以只有当这一刀挣得回来时才拆：

- **按顺序** —— 当完成后步骤诱使智能体去急赶眼前这一步时，拆分一串步骤。把它们移出视野会驱动对当前任务更多的跑腿功夫。当心相反的情况：合并顺序会把每一步的后续步骤暴露给后面的东西，招致过早完成。
- **按调用** —— 技能专属：见 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)。

## 引导词

一个**引导词（leading word）**是一个已住在模型预训练里的紧凑概念，智能体在运行文档时用它来思考（_lesson_、_fog of war_、_tracer bullets_）。作为一个词元反复出现、绝不作为一个句子，它累积起一份分布式定义，并用最少的词元锚定一整个行为区域，靠的是招募模型早已持有的先验。自造你自己的词，只要你清楚地定义它也行，但一个杜撰的词招募不到任何先验——你用定义词元付出的，正是一个预训练词免费给出的；先伸手去取一个已有的词。

它锚定两次。在正文里，_执行_：那个词每次出现，智能体都伸手去取同样的行为，而在扁平参考内部，它把注意力聚焦到一类要去找的东西上。在一个指针里，_调用_：当同一个词住在你的提示词、你的文档和你的代码库里时，智能体会把那份共享语言与材料联系起来，并更可靠地取用它。

去猎取用引导词重构的机会。一个在三处被拼写出来的三元组，一个花一句话去指涉一个想法的指针——每一个都是一段乞求坍缩成单个词元的文字：

- 「fast, deterministic, low-overhead」→ _tight_（一个 _tight_ 循环）。
- 「a loop you believe in」→ _red_ —— 一个模糊的门槛变成一个二元的可观察状态（循环在这个 bug 上变_红_，或者不变）。

你赢两次：更少的词元，以及一个更锋利、供智能体挂靠其思考的钩子。假定每一份文档都在承载着引导词能退役的那些重述——去把它们找出来。

**否定（Negation）**是这个杠杆旁边的失败模式：靠禁止来引导，会把被禁的行为拖进上下文，让它_更_可用，而非更不可用。_别想大象_，于是大象就是全部；否定是一个弱修饰词，被强烈激活的概念淹没，所以那道禁令有一半读起来像是去做那件事的指令。提示那个**正向的**——陈述目标行为（「写一行注释」），好让被禁的那个从不被说出口。一道禁令只有作为一道你无法正向措辞的硬护栏时才挣得它的位置；即便如此，也把它与正向目标配对，好让注意力落在该做什么上。

## 修剪

- 把每个含义保持在一个**唯一真理来源（single source of truth）**里：一个权威的地方，好让改变行为是一处编辑。**重复（Duplication）**——同一个含义出现在不止一处——花费维护和词元，并把一个含义在阶梯上的显要性抬高到超过它真实的排名。（它是引导词的意外反面，引导词故意重复一个词元，绝不重复含义。）
- **环境（environment）**也是一个真理来源——`package.json` 脚本、配置文件、目录布局、`--help` 输出——而一份重述它的文档是一份**缓存（cache）**：一份查找的副本，只有当查找昂贵时才挣得它的负载。缓存智能体靠查看找不到的东西：那条不成文的约定、一个选择背后的理由、任何配置都不坦白的那个坑。把单文件、单命令的查找留给环境，那里它们不会过时。
- 逐行检查**相关性（relevance）**：它是否仍关乎文档所做的事？一行失去相关性，是因为它从不关乎任务（纯粹的说明，或一条本该被披露的分支），或者因为它随着它所描述的行为或世界的改变而过时。更短的文档更容易保持相关。没有一套修剪纪律，默认的命运是**沉积（sediment）**：陈旧的层层堆积，因为添加感觉安全、移除感觉冒险，直到你不得不向下钻穿它们才能找到仍在生效的东西。
- 逐句猎取**空操作（no-ops）**：一条模型默认就服从的指令，付着负载却什么都没说。那个测试——它相对于默认改变了行为吗？——是相对于模型的，而非相对于读者的：两个人在一个空操作上意见相左，是在默认上意见相左，而了结它靠的是运行文档，而非争辩。当一句话没通过时，删掉整句，而不是从中削词。这个测试也给引导词打分：一个弱到打不过默认的词（智能体已经差不多够彻底时的_be thorough_）是一个空操作，而修法是一个更强的词（_relentless_），而非一种不同的技巧。

From WenWuZhiDao/mattpocock-skills-zh, MIT.

More from WenWuZhiDao/mattpocock-skills-zh