| name | writing-for-agents |
| description | Use when writing or editing a document an agent consumes — a skill, an AGENTS.md / CLAUDE.md, or any doc reached by a pointer. Triggers include "write a skill", "improve this doc", "agent instructions". For opencode config mechanics use opencode-config instead. |
Writing For Agents
Packaging differs; the writing levers are the same: make the agent take the
same process every run, not the same output.
Context pointers
A context pointer names out-of-context material and encodes when to reach
it: a skill's description, a line in AGENTS.md pointing at a doc. Its wording,
not its target, decides when the agent reaches the material. A must-have target
behind a weak pointer is a variance bug: sharpen the wording first, inline only
if sharpening fails.
A pointer does two jobs — say what the material is, and list the branches
(distinct cases the doc handles) that trigger reaching it. Every word of an
always-loaded pointer costs on every turn, so prune it hardest:
- Front-load the leading word — that's where it fires.
- One trigger per branch — synonyms are one branch written twice; collapse them.
- Cut identity the body already carries.
The two loads
Every doc and pointer spends one of two budgets:
- Context load — always-loaded material (an
AGENTS.md line, a skill
description) costing tokens every turn whether or not it fires.
- Cognitive load — the human remembering which docs exist and when to reach
for each. Not a cost to minimise: it's the price of human agency. Spend it
where judgement matters, remove it where it doesn't.
Information hierarchy
Rank content by how immediately the agent needs it:
- In-file step — ordered actions, the primary tier.
- In-file reference — definitions and rules consulted on demand.
- Disclosed reference — pushed to a separate file, reached by a pointer.
Progressive disclosure moves material down the ladder so the top stays
legible. Branching is the cleanest test: inline what every branch needs; push
behind a pointer what only some branches reach. Co-location keeps a
concept's definition, rules, and caveats under one heading. Sprawl is the
failure mode: disclose reference and split by branch or sequence.
Steps and completion criteria
Every step ends on a completion criterion — the observable condition that
tells the agent the work is done. Two levers:
- Clarity — can the agent tell done from not-done? A vague bound invites
premature completion: attention slips to being done. Sharpen the bound
first (local, cheap). Only if it's irreducibly fuzzy and you observe the
rush, hide later steps by splitting the sequence — across a real context
boundary (a handoff or subagent), not an inline call.
- Demand — how much it requires. "Every modified model accounted for" forces
legwork; "produce a change list" doesn't. The strongest criteria are both
checkable and exhaustive.
Leading words
A leading word is a compact concept the model already holds (lesson,
fog of war, tracer bullets). Repeated as a token, never a sentence, it
anchors a region of behaviour in few tokens by recruiting priors. A coined word
recruits no priors — reach for an existing one first.
It anchors twice: in the body, execution (same behaviour every time the word
appears); in a pointer, invocation (the shared word links prompt, doc, and
code). Collapse spelled-out triads into one token: "fast, deterministic,
low-overhead" → tight.
Negation is the failure mode beside it: steering by prohibition drags the
banned behaviour into context and makes it more available. Prompt the
positive — state the target ("write one-line comments") so the banned one is
never spoken. A prohibition earns its place only as a hard guardrail you can't
phrase positively; even then, pair it with the positive target.
Pruning
- Single source of truth. One authoritative place per meaning. Duplication
costs maintenance and inflates prominence past its real rank.
- The environment is a source of truth too.
package.json scripts, config,
directory layout — a doc restating them is a cache earning its load only when
the lookup is expensive. Cache what the agent can't find by looking: the
unwritten convention, the reason behind a choice, the gotcha no config admits.
- Check relevance line by line. Stale layers settle because adding feels
safe and removing feels risky. Shorter docs stay relevant.
- Hunt no-ops. An instruction the model obeys by default pays load to say
nothing. Test: does it change behaviour vs the default? If not, delete the
whole sentence, not words from it.
Source: mattpocock/skills (MIT) — adapted and trimmed.
