writing-for-agents

Files (3)

• LICENSE
• SKILL-MECHANICS.md
• SKILL.md

SKILL.md (first lines)

# Writing for agents

## What it does

`writing-for-agents` is the reference you write agent-facing documents against:
a skill, an `AGENTS.md` / `CLAUDE.md`, a
[spec](https://www.aihero.dev/ai-coding-dictionary/spec), a runtime prompt, a
README, any doc an [agent](https://www.aihero.dev/ai-coding-dictionary/agent)
reads. The packaging differs; 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.

Its default move is deletion, not explanation. Ask an agent to write
instructions for another agent and it spends most of its words explaining what
the [model](https://www.aihero.dev/ai-coding-dictionary/model) already knows.
Every one of those lines is a **no-op**, paying
[context](https://www.aihero.dev/ai-coding-dictionary/context) and changing no
behaviour. This reference is the lens that finds them, which is why it earns its
keep at least as often on a document you already have as on a blank file.

It was called `writing-great-skills` until v1.1. The rename tracks what it
always was underneath: almost none of it is skill-specific. The skill-only
mechanics (frontmatter, the model- versus user-invoked choice, router skills)
are disclosed to a linked `SKILL-MECHANICS.md` you read only when the document
in front of you is a skill.

## When to reach for it

Type `/writing-for-agents`, or the agent reaches for it on its own when you're
creating or editing a skill, or modifying `AGENTS.md` or `CLAUDE.md`.

Reach for it by hand for everything else an agent reads: your docs, specs and
[tickets](https://www.aihero.dev/ai-coding-dictionary/ticket), system and
[AFK](https://www.aihero.dev/ai-coding-dictionary/afk) prompts. The test is one
question: does an agent read this? And it does not matter how the document gets
in front of it, whether a pointer names it, a human pastes it, or it simply sits
in the repo. For working out what a codebase actually contains in the first
place, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs); this
reference governs how a document reads, not what it knows.

## The two loads

The idea the whole reference turns on is a pair of budgets every document and
pointer spends:

- **Context load**: the cost of always-loaded material on the agent's window: an
  `AGENTS.md` line, a skill description, anything sitting in context every
  [turn](https://www.aihero.dev/ai-coding-dictionary/turn) whether or not it
  fires.
- **Cognitive load**: the cost on you, namely which documents exist and when to
  reach for each. You are the index. Not a cost to minimise: it is the price of
  human agency.

Once you think in these two loads, most authoring decisions (split or don't,
inline or disclose, point or push) become the same trade made in different
places.

## The levers

- **[Context pointers](https://www.aihero.dev/ai-coding-dictionary/context-pointer)**:
  the reference held in context that names out-of-context material and encodes
  when to reach it. A skill description and an `AGENTS.md` line naming a doc are
  the same object; the pointer's *wording*, not its target, decides how reliably
  the agent reaches through it.
- **Information hierarchy**: the ladder from in-file step, to in-file reference,
  to disclosed reference behind a pointer.
  **[Progressive disclosure](https://www.aihero.dev/ai-coding-dictionary/progressive-disclosure)**
  is the move down that ladder so the top stays legible.
- **Completion criteria**: the clarity and demand of each step's done-condition,
  and the **legwork** that demand drives; the defence against **premature
  completion**.
- **Leading words**: a compact concept already in the model's pretraining
  (*tight*, *red*, *tracer bullet*) that the agent thinks with while running the
  document. It anchors twice: execution in the body, invocation in the pointer.
- **Pruning**: single source of truth, relevance, and the no-op test applied
  sentence by sentence, against **duplication**, **sediment** and **sprawl**.

## Common questions

**Where did `/writing-great-skills` go?** It is this skill, renamed in v1.1.
Practitioners were already pointing it at `AGENTS.md`, docs, specs, tickets and
runtime prompts long before the name caught up; structure, leading words and
pruning turn out to be the craft of any text an agent reads. There is no alias.
Reinstall under the new name.

**"Writing for agents": so the agent does the writing?** The other way round.
You are the author; the agent is the reader. That is the whole difficulty of the
genre: you are writing for a reader who has already read everything, so
explanation is waste and precision is the entire job.

**Can't I just ask the agent to write it for me?** You can, and it will produce
something verbose. Left alone the model explains what it already knows, and it
will not apply the no-op test or reach for a leading word on its own. Use the
reference on the draft: a review pass is where most of its value lands.

**I asked an agent to trim a document and it cut the functionality.** Agents
told to "streamline" optimise for length, because length is the thing they can
see. The no-op test is behavioural, not aesthetic: delete the line and ask
whether the agent's behaviour changed. When a sentence fails, delete the whole
sentence rather than trim words from it, and settle a disagreement about it by
running the document, not by arguing.

**How do I know when it's done?** When it works, and you can no longer find
duplication, sediment or no-ops. There is no automated eval here; the check is a
manual run plus the failure-mode vocabulary as a diagnostic. When a document
misbehaves, that vocabulary is also the repair kit: name the failure mode first,
then fix that.

**Should this live in `CLAUDE.md` or somewhere else?** Ask which load you want
to pay. `CLAUDE.md` loads into every
[session](https://www.aihero.dev/ai-coding-dictionary/session) unconditionally;
material behind a pointer costs only the pointer's own line until it fires.
Anything that applies in one context out of ten is paying context load the nine
other times.

**Do I need to rewrite my documents for each new model?** Mostly no, and
over-fitting to one model is its own trap. Updating for a new model is usually
another no-op pass rather than a rewrite.

From hurricanehrndz/agent-toolkit, MIT.

More from hurricanehrndz/agent-toolkit