# Writing For Agents

> 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.

- Skill: `znlgis/writing-for-agents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add znlgis/writing-for-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/znlgis/writing-for-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: znlgis (https://skillmd.com/u/znlgis)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/znlgis/writing-for-agents

---


# 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:

1. **In-file step** — ordered actions, the primary tier.
2. **In-file reference** — definitions and rules consulted on demand.
3. **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.