writing-for-agents

技能简介

该技能用于指导如何编写供 Agent 阅读的文档，包括 Skill 文件、AGENTS.md / CLAUDE.md 以及被上下文指针引用的外部文档。它解决的核心问题是：通过合理的文档结构、措辞和信息层级安排，让 Agent 每次运行都能稳定、可预期地获取所需信息。

使用场景

• 创建新的 Skill 或编辑已有 Skill 的描述与正文时
• 编写或修改 AGENTS.md / CLAUDE.md 时
• 设计被 Agent 按需读取的参考文档（reference doc）时
• 需要将长文档拆分为多个文件，并通过指针（context pointer）引导 Agent 访问时

使用方法

本技能是一份写作参考规范，无需安装或激活，直接阅读并遵循其中的原则即可。

1. 阅读参考：在编写任何供 Agent 消费的文档前，阅读本技能正文，了解两条核心负载（context load 与 cognitive load）以及信息层级的选择逻辑。
2. 编写 Skill 时：如正在编写的是 Skill 文件，先阅读同目录下的 SKILL-MECHANICS.md，了解 frontmatter 写法、调用方式以及 router skill 的设计规则。
3. 应用到目标文档：将技能中的原则（指针措辞、分支触发词、渐进式披露、完成标准等）应用于你正在编写的 AGENTS.md、CLAUDE.md 或 Skill 文档。

注意事项

• 指针措辞比目标更重要：一个指向重要文档的指针若措辞模糊，会导致 Agent 在需要时无法触发跳转，应优先打磨措辞，而非将内容直接内联。
• 始终加载的内容需要精简：Agent 每一轮运行都会读取常驻指针（如 Skill 描述、AGENTS.md 行），因此每条指针都应做到“一个分支一个触发词”，删除与正文重复的表述。
• 区分两种负载：context load 是常驻内容对 Agent 上下文的消耗；cognitive load 是人类维护文档索引的成本。不要盲目追求其中一项最小化，而应把人类判断力花在真正需要的地方。
• 警惕文档蔓延（sprawl）：当文档过长时，即使每一行都有价值，Agent 的注意力也会被稀释。应通过指针拆分参考内容，按分支或顺序切分文档路径。