Writing for agents

The aim is a predictable process: the agent takes the same path every run. Every line spends the agent's attention, so each one has to change behaviour.

Pointers

A skill description, or an AGENTS.md line naming a doc, is a pointer. It is always loaded and decides when the agent reaches the material.

• Say what the material is, then give one trigger per distinct case. Collapse synonyms into one trigger.
• Front-load the word the user actually types.
• When must-have material goes unread, sharpen the pointer first. Inline the material only if that fails.

Structure beats prose

Before writing a rule, look for a mechanism that enforces it: a lint rule, hook, script, type, or frontmatter flag. Build the mechanism and drop the line. Prose is for judgment calls.

Placement

Rank material by how many runs need it: