writing-for-agents
产品介绍
writing-for-agents 是 Matt Pocock Skills 中「写作方法论」类的唯一 Skill，安装在 ~/.trae-cn/skills/writing-for-agents/SKILL.md。当 AI 写 Skill 或 AGENTS.md 时自动调用，教 AI 如何写出高质量的、供其他 AI 读取的文档。
为什么需要这个 Skill
写给人类看的文档和写给 AI 看的文档，要求完全不同。人类可以容忍模糊、上下文缺失、需要推断的地方；AI 不能。AI 会按字面意思执行，不会”补全”你没说清楚的部分。所以写给 AI 的文档必须：
- 精确：每一步都写清楚，没有歧义
- 自包含：AI 不需要额外知识就能理解
- 结构化：用清晰的层次组织信息，方便 AI 快速定位
核心设计概念
1. 上下文指针（Context Pointers）
文档里的引用要清晰，告诉 AI 什么时候去读什么。不要把所有内容都内联写出来，而是用指针引用其他文件。
反例：把 10 个 Skill 的完整内容都复制到 AGENTS.md 里 正例：在 AGENTS.md 里写「遇到修 bug 的问题，读 diagnosing-bugs」
这样做有两个好处：
- AGENTS.md 保持精简，不会因为内容太多而稀释重点
- AI 知道什么时候该深入读哪个文件
2. 两种负载（Two Loads）
文档内容对 AI 来说有两种负载：
| 负载类型 | 说明 | 处理方式 |
|---|---|---|
| 上下文负载 | 每次都会自动加载的内容 | 必须精简，只保留最关键的信息 |
| 认知负载 | AI 需要记住的关键信息 | 可以适当详细，但要结构清晰 |
例子：Skill 文件的 frontmatter（标题、描述、触发条件）是上下文负载，每次都会加载，所以要精简。而 SKILL.md 的正文内容是按需加载的，可以详细。
3. 信息层级
文档里的信息分两种：
- 步骤（Ordered Actions）：操作流程，有顺序要求，必须严格遵循
- 参考（Definitions, Rules, Facts）：定义、规则、事实，无顺序要求，按需查阅
例子：TDD 的「红 → 绿 → 重构」是步骤，必须按顺序来。而「什么是 mocking」是参考，AI 需要时自己查。
4. 完成标准
每个步骤都要有明确的「完成」条件。没有完成标准的步骤，AI 不知道什么时候算做完，可能会提前停止或者过度执行。
反例：「写测试」—— AI 不知道写到什么程度算完成 正例：「写一个能复现 bug 的最小测试，包含：触发条件、期望结果、实际结果」
5. 领先词（Leading Words）
用模型预训练里已有的概念，不要发明新词。AI 已经学会了大量人类语言，用它已经知道的词能降低理解成本。
反例：发明一个新词「Delta 压缩」来描述某个概念 正例：用「压缩」「缓存」这些 AI 已经知道的词来描述
实际例子
假设你要写一个 Skill，教 AI 如何处理用户投诉。用这套方法论：
不好的写法：
帮用户处理投诉
好的写法：
## 处理用户投诉
### 步骤
1. **倾听**：读完整个投诉，不打断，不防御
2. **共情**：先表达理解，「我理解你的感受」
3. **分类**：判断是产品 bug、服务问题还是计费争议
4. **给出方案**：提供 2-3 个可选方案，让用户选
5. **执行**：按用户选的方案执行
6. **确认**：完成后确认用户是否满意
### 完成标准
- 步骤 2 完成：用户感受到被理解
- 步骤 3 完成：投诉已归类
- 步骤 4 完成：用户已选方案
- 步骤 5 完成：方案已执行
- 步骤 6 完成：用户确认满意或给出新问题
使用场景
- 写自己的 Skill 时
- 写 AGENTS.md 指导 AI 行为时
- 写任何 AI 会读取的文档时
- 审查别人写的 AI 文档时
常见陷阱
- 把文档写成人说明书：假设 AI 已经知道很多背景知识，结果 AI 看不懂
- 步骤没有完成标准：AI 不知道什么时候算做完
- 把所有内容内联：导致上下文爆炸，重点被稀释
- 发明新词：AI 不认识，理解成本高
相关笔记
- Matt Pocock Skills - Skill 集合
- triage - 问题分流
- diagnosing-bugs - 诊断循环
- tdd - 测试驱动开发
相关日记
- 2026-08-26 - 安装当天