/writing-rules

name: writing-rules
description: Write or review anything an agent reads — a core rule, a profile gate, a SKILL.md description, an instruction-file line, a subagent prompt, a handoff note, a verify-phase label. Part of the Agentsmith harness; supplies the levers that decide whether a line changes behaviour or only costs tokens — the two loads, context pointers, the ladder, completion criteria, leading words, the no-op test. Its default move is deletion, so it earns most on a draft that already exists.
compatibility: Requires an Agent Skills-compatible coding agent with filesystem access.

Writing rules — and anything else an agent reads

You are writing for a reader who has already read everything. Explanation is waste; precision is the whole job. Left alone, a model writing instructions for a model spends most of its words restating what it already knows — every one of those lines is a **no-op**: paid every turn, changing nothing.

The packaging differs (a `core/` rule, a profile gate, a `SKILL.md`, a subagent prompt, a handoff note) but the writing does not. The same levers make each one predictable, so the agent takes the same *process* every run rather than producing the same output.

When the document is a harness surface — a `core/` rule, a profile, a skill, a hook — read [`HARNESS-SURFACES.md`](HARNESS-SURFACES.md) for where it goes and what it costs.

Instruction vocabulary

`AGENTS.md` is the canonical portable instruction file. Never infer the active agent from this skill's install path: portable canonical content may be copied into a required client adapter such as `.claude/skills`. Treat client-specific instruction files as generated adapters; edit their shared `core/` or `profiles/` source, never an adapter copy.

The two loads

Every document and every pointer spends one of two budgets. Most authoring decisions are this one trade made in different places:

• **Context load** — what always-loaded material costs the agent's window: an instruction-file line, a

skill `description`, anything sitting in context every turn whether or not it fires.

• **Cognitive load** — what it costs *you*: knowing which documents exist and when to reach for

each. You are the index. Not a cost to minimise — it's the price of human agency. Spend it where human judgement matters; remove it where it doesn't.

Material behind a pointer escapes context load for the price of the pointer's own line. Material with no pointer at all rides entirely on cognitive load.

Context pointers

A **context pointer** is a reference held in context that names out-of-context material and encodes when to reach it. A skill's `description` and an instruction-file line naming a doc are **the same object**. The pointer's *wording*, not its target, decides how reliably the agent reaches through it — so a must-have target behind a weak pointer is a variance bug. Sharpen the wording first; inline the material only if sharpening fails.

A pointer does two jobs: say what the material is, and list the **branches** that should trigger it (a branch is a distinct case the document handles). Every word is paid every turn, so prune it harder than the body:

• **Front-load the leading word** — the pointer is where it does its triggering work.
• **One trigger per branch.** Synonyms renaming one branch are one branch written twice.
• **Cut identity the body already carries.**

The ladder — where each piece sits

Documents are built from **steps** (ordered actions) and **reference** (facts consulted on demand). They mix freely: all steps, all reference, or both. The decision is how far down each piece sits:

1. **In-file step** — what the agent does, in order. The primary tier. 2. **In-file reference** — consulted on demand. Often a legitimately flat peer-set (every gate of a profile on one rung). That's an arrangement, not a smell. 3. **Disclosed reference** — a separate file behind a pointer, loaded only when the pointer fires.

**Progressive disclosure** is the move down that ladder so the top stays legible. Branching is the cleanest test: **inline what every branch needs; disclose what only some branches reach.** Push too little down and the top bloats; push too much and you hide what the agent actually needs.

**Co-location** is the within-file companion — the ladder decides how far down, co-location decides what sits beside it. Keep a concept's definition, rules and caveats under one heading so reading one part brings its neighbours. (Distinct from duplication: that repeats one meaning in two places, scattering fragments one meaning across many.)

**Sprawl** is the failure mode here — a document simply too long, even when every line is live and unique. Attention thins across the excess. The cure is the ladder, not tighter sentences.

Completion criteria

Every step ends on a **completion criterion** — the condition that says the work is done. Two properties make it a lever, and both sharpen R5 (verify before you call it done):

• **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached")

invites **premature completion**: ending early because attention slipped to *being done*. The visible steps still ahead supply the pull; the criterion's clarity is the resistance. Sharpen the bound first — it's local and cheap. Only if it's irreducibly fuzzy *and* you observe the rush, split the sequence so the later steps aren't in view. That only works across a real context boundary (a handoff, a subagent dispatch); an inline call clears nothing.

• **Demand** — how much it requires. "Every consumer of the change checked" forces thorough work

where "check the change" does not. Demand drives **legwork**: the digging latent in the wording rather than written as its own step. It isn't step-bound — "every gate applied" binds a body of flat reference the same way.

The strongest criteria are both checkable and exhaustive. This is why R3 says *every* consumer and R2 says e