一句话

写给 agent 看的文档的参考规范：context pointer、两种 load、信息层级、完成判据、leading word、删减原则；默认修法是删不是解释。

何时用

• 适合：写或改技能、AGENTS.md/CLAUDE.md、spec、README、系统提示等任何 agent 会读的文档。
• 不适合：想知道代码库内容（用 matt-grill-with-docs）；它管文档怎么读，不管文档知道什么。

怎么用

帮我按 writing-for-agents 审查这份 AGENTS.md

1. 定位每个内容在信息层级哪级：in-file 步骤、in-file 参考、pointer 后的披露参考；步骤永远在主文件。
2. 问每行花的是哪种 load：context load（常驻窗口）还是 cognitive load（人肉索引）。
3. 逐句查 no-op（模型默认就做的事删整句）、duplication（一个意思只留一处）、sediment（逐层沉积的过期内容）。
4. 用 leading word 收束行为（优先借已有词汇）；少写否定禁令，多写正面目标。
5. 涉及技能本体机制（frontmatter、用户/模型调用、路由技能）读 SKILL-MECHANICS.md。

产出

• 修改建议或改写后的文档；matt-retro 在第 1 步调它拿写作规范。

要点与坑

• pointer 的措辞决定触发可靠性：必看内容藏在弱措辞的 pointer 后面是 variance bug。
• progressive disclosure 主要不是省 token，是保住层级：每个分支只背自己需要的。
• 环境也是 single source of truth：一句话能在 package.json 查到的就别写进文档当缓存。

关联

• 调用方：matt-retro · 同类：pstack-technical-writing
• 所属：00-matt-概览