writing-for-agents

Reference for writing any document an agent consumes — a skill, an AGENTS.md / CLAUDE.md , a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable — the agent taking the same process every run, not producing the same output. When the document you're writing is a skill, read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills. Context pointers A context pointer is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in AGENTS.md naming a doc is the same object. The pointer's wording , not its target, decides when the agent reaches the material — and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails. A pointer does two jobs — state what the material is, and list the branches that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body: Front-load the leading word — the pointer is where it does its triggering work. One trigger per branch. Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches. Cut identity the body already carries. The two loads Every document and pointer you add spends one of two budgets: Show more Installs 3.2K Repository mattpocock/skills GitHub Stars 203.8K First Seen 9 days ago Security Audits Gen Agent Trust Hub Pass Socket Pass Snyk Pass