Writing for agents
A skill description, a line in AGENTS.md, and a rule file's glob are the same
object: a context pointer. Each names material that is out of context and
states the condition for reaching it. The pointer's wording, not its target,
decides whether it is reached.
That single idea is why descriptions deserve so much care and routers so little.
Paths below are relative to this skill's directory; resolve them to absolute
paths before reading anything.
Read this before
- Writing or editing any
SKILL.md, especially its description.
- Writing or editing an instructions file at any level:
AGENTS.md at the
root or in a folder, or the harness's own equivalent (CLAUDE.md, a Copilot or
Cursor instructions file).
- Adding a convention, or a rule file that points at one.
- Deciding whether something belongs inline or behind a link.
The material
- references/theory.md is the full treatment:
context pointers, the two loads, the information hierarchy, completion
criteria, leading words, negation, and pruning. Read it in full the first time.
- references/skill-mechanics.md covers the
skill-specific branch: model-invoked versus user-invoked, splitting by
invocation, and router skills.
How it maps onto a repository
The theory is harness-neutral. In a repository it lands on these layers:
| Concept |
Where it lives |
| Context pointer |
a skill's description; a line in an instructions file naming a document and when to read it; a rule file's glob (Claude Code's paths:, Cursor's globs:) |
| Context load |
everything always resident: every installed skill's description, plus each instructions file on the path to the file being worked on |
| Cognitive load |
what a person must remember exists: the conventions folder's index, every user-invoked skill |
| Progressive disclosure |
a skill's references/; an instructions file in a subfolder, read only when work happens there; rule files that load when a matching file is read; the conventions folder, reached by one line in AGENTS.md |
| Co-location |
a script lives in the skill that runs it |
| Sediment |
an instructions-file section nobody has pruned, read into every session regardless |
| No-ops |
instructions the model already follows by default. Delete the sentence |
House rules about agent-facing prose, including any budgets (a line cap on
AGENTS.md, a description cap tighter than the spec's), live in the conventions
folder. This repository's agent configuration should have been provided to you
(the ## Agent skills block pointing at docs/agents/). If it is missing, use
the defaults below and suggest the user run the setup-aclarify-skills skill.
- Conventions folder (
docs/agents/workspace.md): read its rules on
writing for agents before these defaults, and follow them where they differ.
Default: none.
- Default budgets: a description of at most 1024 characters, the Agent
Skills maximum, where some harnesses truncate; a
SKILL.md body of at most
500 lines, with depth in references/ one level deep.
The one rule to carry away
Prompt the positive, never the prohibition. "Write the owner and the date on
every action item" works. "Don't forget the owner" does not, and reliably
produces the thing it names. Negation is the most common failure in hand-written
agent instructions.
1---2name: writing-for-agents3description: >-4 The craft of the prose agents read: skill descriptions and bodies, instructions files5 (AGENTS.md, CLAUDE.md), rule files and reference docs; context pointers, progressive6 disclosure, leading words and pruning. Use whenever wording or rewording any of those,7 deciding what belongs in always-loaded context versus behind a pointer, pruning an8 instructions file that has grown, or asking whether a line is a no-op. Do NOT use to9 build, split, port or test a skill end to end (use `skill-builder`, which loads this), to10 measure whether one fires (`harness-eval`), to state or route a convention (`add-standard`,11 `standards`), or for prose a person reads: a working surface (`conveying-clearly`), a12 byline piece (`draft-argued-piece`), or marketing copy (`seven-copy-critics`).13license: MIT14metadata:15 source: https://skillmd.com/skills/spencermarx/writing-for-agents16 credits: "Adapted from Matt Pocock's writing-for-agents skill, https://github.com/mattpocock/skills (MIT)"17---1819# Writing for agents2021A skill description, a line in `AGENTS.md`, and a rule file's glob are the same22object: a **context pointer**. Each names material that is out of context and23states the condition for reaching it. The pointer's wording, not its target,24decides whether it is reached.2526That single idea is why descriptions deserve so much care and routers so little.2728Paths below are relative to this skill's directory; resolve them to absolute29paths before reading anything.3031## Read this before3233- Writing or editing any `SKILL.md`, especially its `description`.34- Writing or editing an instructions file at any level: `AGENTS.md` at the35 root or in a folder, or the harness's own equivalent (`CLAUDE.md`, a Copilot or36 Cursor instructions file).37- Adding a convention, or a rule file that points at one.38- Deciding whether something belongs inline or behind a link.3940## The material4142- **[references/theory.md](references/theory.md)** is the full treatment:43 context pointers, the two loads, the information hierarchy, completion44 criteria, leading words, negation, and pruning. Read it in full the first time.45- **[references/skill-mechanics.md](references/skill-mechanics.md)** covers the46 skill-specific branch: model-invoked versus user-invoked, splitting by47 invocation, and router skills.4849## How it maps onto a repository5051The theory is harness-neutral. In a repository it lands on these layers:5253| Concept | Where it lives |54|---|---|55| Context pointer | a skill's `description`; a line in an instructions file naming a document and when to read it; a rule file's glob (Claude Code's `paths:`, Cursor's `globs:`) |56| Context load | everything always resident: every installed skill's description, plus each instructions file on the path to the file being worked on |57| Cognitive load | what a person must remember exists: the conventions folder's index, every user-invoked skill |58| Progressive disclosure | a skill's `references/`; an instructions file in a subfolder, read only when work happens there; rule files that load when a matching file is read; the conventions folder, reached by one line in `AGENTS.md` |59| Co-location | a script lives in the skill that runs it |60| Sediment | an instructions-file section nobody has pruned, read into every session regardless |61| No-ops | instructions the model already follows by default. Delete the sentence |6263House rules about agent-facing prose, including any budgets (a line cap on64`AGENTS.md`, a description cap tighter than the spec's), live in the conventions65folder. This repository's agent configuration should have been provided to you66(the `## Agent skills` block pointing at `docs/agents/`). If it is missing, use67the defaults below and suggest the user run the `setup-aclarify-skills` skill.6869- **Conventions folder** (`docs/agents/workspace.md`): read its rules on70 writing for agents before these defaults, and follow them where they differ.71 Default: none.72- **Default budgets:** a description of at most 1024 characters, the Agent73 Skills maximum, where some harnesses truncate; a `SKILL.md` body of at most74 500 lines, with depth in `references/` one level deep.7576## The one rule to carry away7778**Prompt the positive, never the prohibition.** "Write the owner and the date on79every action item" works. "Don't forget the owner" does not, and reliably80produces the thing it names. Negation is the most common failure in hand-written81agent instructions.