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: predictability: the agent taking the same process every run, not producing the same output, is the root virtue, and every lever below serves it.

Bold terms are defined in GLOSSARY.md; look them up there for the full meaning.

When the document is a skill, read SKILL-MECHANICS.md for frontmatter, the 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. 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; 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:

writing-for-agents

Context pointers

The two loads