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, since the agent takes the same process every run rather than producing the same output.

When the document you're writing is a skill, read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills.

Project instructions are operating manuals

A README helps a human or agent understand and adopt the project. Project agent instructions explain how to change it safely and in character. Cache only what the environment cannot cheaply reveal:

• project intent and properties a change must not compromise;
• a glossary for terms whose meaning or preferred wording is local;
• hidden footguns and commands whose obvious form is wrong;
• the expected scope and verification path for common changes;
• a surface matrix of clients, entry points, adapters, contracts, reversible states, docs, or deployment modes that a change may need to cover.

Keep discoverable scripts, directory listings, and package metadata in their real source of truth. Put personal tone and stable cross-project preferences in global instructions rather than making every repository repeat them.

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.