writing-for-agents
Installation
SKILL.md
为 agent 编写任何文档时的参考：skill、AGENTS.md 或 CLAUDE.md，以及被上下文指针引用的文档。形式不同，写法相同：同一组方法能让文档的执行结果更稳定，也就是让 agent 每次都走相同的过程，而不是每次产出相同的结果。
- 编写 skill 时，阅读 SKILL-MECHANICS.md，了解 frontmatter、触发方式和路由 skill。
- 需要验证一句指引是否真的改变了 agent 的行为，或者编写完一个约束型 skill（agent 容易以“就这一次”为由绕过的那种）需要验证时，阅读 TESTING.md。
上下文指针
上下文指针（context pointer）是留在 agent 上下文中的一条引用，指向上下文之外的材料，并写明在什么条件下去读取它。skill 的 description 是一种上下文指针；AGENTS.md 中提到某份文档的一行文字也是。
决定 agent 何时读取、读取是否可靠的，是指针的措辞，而不是它指向的内容。如果必须阅读的材料挂在措辞很弱的指针后面，agent 有时读、有时不读，执行结果就会不稳定。先把指针措辞改得更具体；仍然无效时，再把材料直接写进正文。
指针做两件事：说明材料是什么，并列出应当触发读取的分支（分支是文档要处理的一种不同情况，不同的运行会走不同的路径）。常驻上下文的指针每一轮都会占用 token，所以要比正文更精简：
- 先导词放在前面：指针正是先导词发挥触发作用的位置。
- 一个分支一个触发词。 为同一分支换一种说法的同义词，等于把一个分支写了两遍；合并它们，只保留真正不同的分支。
- 删除正文已经说明的身份信息。
- 只写何时使用，不概括流程。 description 一旦概括了步骤，agent 会照着摘要执行，跳过正文。