# Writing For Agents

为 agent 编写文档。适用于创建或编辑 skills，或修改 AGENTS.md 或 CLAUDE.md 时。

- Repository: https://github.com/vinvcn/mattpocock-skills-zh-CN (5461 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill writing-for-agents -g -a claude-code -y`
Codex: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill writing-for-agents -g -a codex -y`
Cursor: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill writing-for-agents -g -a cursor -y`
Gemini CLI: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill writing-for-agents -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add vinvcn/mattpocock-skills-zh-CN`

## Description

为 agent 编写文档。适用于创建或编辑 skills，或修改 AGENTS.md 或 CLAUDE.md 时。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

为 agent 消费的任何文档提供参考：一个 skill、一个 `AGENTS.md` / `CLAUDE.md`、一个经 pointer 触达的文档。包装方式不同；写作本身并无不同：同样的杠杆让每一份都变得可预测：agent 每次运行都采取相同的 _process_，而不是产出相同的 output。

当你写的文档是 skill 时，阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) 了解 frontmatter、invocation 选择以及 router skills。

## Context pointers

**context pointer** 是 agent context 中持有的一个 reference，它命名某个 context 之外的材料，并对触达它的条件进行编码。某个 skill 的 description 就是其一；`AGENTS.md` 中命名某个文档的一行是同一个对象。决定 agent 何时以及多可靠地触达材料的，是指针的 _措辞_，而不是它的目标。一个必须是目标的、却由措辞薄弱的 pointer 承载的内容，是一个 variance bug：先打磨措辞，只有打磨失败时才内联该材料。

一个 pointer 做两件事：说明材料是什么，并列出应触发触达它的 **branches**（一个 branch 是文档处理的一个独立情形，所以不同的 runs 会沿不同的路径穿过它）。一个始终加载的 pointer 的每个词都会在每一轮付出成本，所以它比正文更该被大力修剪：

- **把 leading word 放到最前面**：pointer 是它做触发工作的地方。
- **每个 branch 一个 trigger。** 如果同义词只是重命名单一 branch，那就是同一个 branch 写了两遍；合并它们，只保留真正不同的 branches。
- **删掉正文已经承载的 identity。**

## 两种 load

你添加的每个文档和 pointer 都会花掉两个预算之一：

- **Context load**：始终加载的材料对 agent window 的成本：一行 `AGENTS.md`、一个 skill description、任何每轮都躺在 context 里的东西，无论是否触发都要花 tokens 和注意力。
- **Cognitive load**：对人类的成本：存在哪些文档、何时伸手去取每一份。人类就是 index。这不是要最小化的成本，它是 human agency 的代价；把它花在人的判断起作用的地方，在它不起作用的地方移除它。

只能通过 pointer 触达的材料，以该 pointer 自己那一行为代价逃过 context load；完全没有 pointer 的材料则完全由 cognitive load 承载。

## 信息层级

一个文档由两类内容构成：**steps**（agent 执行的有序动作）和 **reference**（按需查阅的定义、规则、事实），它们自由混合：全是 steps（一份菜谱）、全是 reference（一次 review 的规则、本 skill），或两者都有。核心决策是每块内容放在 **information hierarchy** 的哪个位置，一个按 agent 需要材料的即时程度排序的 ladder：

1. **In-file step**（primary tier）：agent 按顺序做什么。
2. **In-file reference**：按需查阅。通常是一个合法的 flat peer-set（一次 review 的所有规则都在一个 rung 上），这是合理的安排，不是坏味道。
3. **Disclosed reference**：推到独立文件中，经 context pointer 触达，只在 pointer 触发时加载。既涵盖同一文件夹里的 sibling 文件，也涵盖存在于任何地方、任何文档都能指向的完全 external reference。

把太少内容下放会让顶层膨胀；把太多内容下放会隐藏 agent 实际需要的材料。那种张力就是整个决策。

The rest: https://github.com/vinvcn/mattpocock-skills-zh-CN/blob/HEAD/skills/productivity/writing-for-agents/SKILL.md