# Writing For Agents > Writing standards for any document an AI agent consumes — a skill, a CLAUDE.md/AGENTS.md, or a doc reached by a pointer. Use when creating or editing a skill, or writing/editing CLAUDE.md, AGENTS.md, or any reference doc meant to be read by an agent rather than a human alone. - Skill: `alunadev/writing-for-agents` (Agent Skill) - Install (CLI): `npx skillmds add alunadev/writing-for-agents` - Raw SKILL.md: https://api.skillmd.com/api/skills/alunadev/writing-for-agents/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: alunadev (https://skillmd.com/u/alunadev) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/alunadev/writing-for-agents --- # Writing for Agents The packaging differs across a skill, a `CLAUDE.md`, or a doc reached by a pointer — the writing discipline doesn't. The goal isn't a document a human reads once; it's a document that gets an agent to the same *process* every run, not just the same output. ## Context pointers A context pointer is a reference living in the agent's always-loaded context (a skill description, a `CLAUDE.md` line) that names material and encodes when to reach it. The pointer's *wording* — not its target — decides whether the agent actually reaches the material, and how reliably. - Front-load the trigger word — the pointer does its work at the start, not buried in a clause. - One trigger per distinct case. Synonyms restating the same case are the same branch written twice — collapse them. - Cut identity the target document already states — don't restate the material in the pointer. ## Two budgets, spent differently - **Context load** — the cost of always-loaded material (a skill description, a `CLAUDE.md` line) on every single turn, whether or not it fires. - **Cognitive load** — the cost on the human of knowing which documents exist and when to reach for each. Not a cost to eliminate — it's the price of human judgment; spend it where the judgment matters, remove it where it doesn't. Material behind a pointer pays only the pointer's cost in context load; material with no pointer rides entirely on someone remembering it exists. ## Information hierarchy — where each piece of content sits 1. **In-file step** — what the agent does, in order. The primary tier. 2. **In-file reference** — consulted on demand, but still in the main file (e.g. a flat rule list). 3. **Disclosed reference** — pushed to a separate file, reached only through a pointer, loaded only when it fires. Push too little down and the top of the document bloats past what every run needs; push too much down and material the agent actually needs stays hidden. **Progressive disclosure** is moving material down this ladder as it stops being universally needed — the branching test: inline what every path needs, disclose what only some paths reach. **Co-location**: keep a concept's definition, rules, and caveats under one heading rather than scattered across the document, so reading one part brings its neighbors with it. ## Leading words A leading word is a compact, already-understood term (*seam*, *tracer bullet*, *red/green*) that anchors a whole region of behavior in a few tokens by recruiting priors the model already has, instead of restating a description every time. Reuse an existing well-known term before coining a new one — a made-up word carries no priors, so you pay in definition tokens what a pretrained word gives free. Avoid steering by **negation** ("don't do X") — naming the forbidden behavior makes it *more* available to the model, not less. State the positive target instead ("write one-line comments," not "don't over-comment"). ## Pruning - **Single source of truth.** The same meaning stated in two places is duplication — costs upkeep, and inflates that meaning's apparent importance. - **Don't restate the environment.** `package.json` scripts, config, `--help` output are sources of truth on their own; a doc that copies them is a stale cache waiting to happen. Document the unwritten convention or the reason behind a choice — not what a one-command lookup already answers. - **Check relevance regularly.** A line that no longer bears on the task, or has gone stale as the world changed, should go. Without this habit, documents accumulate sediment — old layers nobody wants to be the one to delete. - **Cut no-ops.** An instruction the agent already does by default costs tokens for nothing. If it doesn't change behavior, delete the sentence. ## Skills specifically: model-invoked vs. user-invoked - **Model-invoked** — has a description the agent can match against context; the agent decides when to reach for it. Always costs a little context load (the description), in exchange for auto-discovery. - **User-invoked** (`disable-model-invocation: true`) — only reached when the user explicitly types it. Zero ongoing context load, at the cost of the human having to remember it exists. - **Router skill** — a user-invoked skill that's just an index of other user-invoked skills, so the human doesn't have to hold that whole list in their own head. Pick model-invoked for anything the agent should apply by default (a discipline, a standard); user-invoked for anything expensive, destructive, or only useful when deliberately asked for — matches how `design-lab` (manual) vs. `prototype` (auto-triggers) are split in this repo. ## See also - `creating-skills` — the meta-skill for generating a new skill's structure. This skill is the writing discipline underneath it: `creating-skills` decides what a skill contains, `writing-for-agents` decides how any of it should be worded. - `products/ald-os/context/product-builder-principles.md` — Engineering #14, Documentation is part of the deliverable. This skill is that principle's operational form. ## Source Adapted from [mattpocock/skills](https://github.com/mattpocock/skills)' `writing-for-agents` and `SKILL-MECHANICS.md`.