retro and writing-for-agents: improve your agent's environment after every session

When a session with an agent goes wrong, the usual move is to fix the code and move on. Matt Pocock's skills propose one more step: ask what in the environment made it go wrong and change it, so the next session starts from a better place. retro runs that retrospective and writing-for-agents is the reference for how to write the changes it proposes: CLAUDE.md, AGENTS.md, coding standards and skills. They belong together because retro loads writing-for-agents as its first step.

This is part thirteen of the Matt Pocock skills guide (mattpocock/skills repository, MIT license).

retro: closing the loop

ask-matt places /retro at the end of the main flow: "after a build, and especially one that went sideways". It doesn't suggest code changes but changes to the agent's environment.

Seven categories, most severe first

retro reads the session's primary sources (the current one by default, or another session's logs) and looks for candidates in these categories:

It presents the candidates ordered by severity.

Mechanical or judgement call

retro's most useful rule is how to classify a mistake:

• Mechanical (a fixed syntactic pattern, a banned API, an import shape, a file-location rule): it becomes a deterministic check, full stop. A rule in the repository's own linter, a pre-commit hook or a CI job, whichever is cheapest.
• Judgement call (cross-file consistency, "matches the surrounding style"): it goes into CODING_STANDARDS.md, which the reviewer reads.

Before proposing a new check, retro reads the repository's lint and check scripts and its CI: if the check already exists but is unwired or silently broken, that is the finding. And a repository with no guardrail at all (no pre-commit hook and no CI job running lint, types and tests) is a finding in itself.

Implementer and reviewer

retro rests on an idea about where each rule belongs. All work goes through two stages:

• The implementation agent has the most context pressure: it explores, writes code and debugs.
• The review agent has the least: it gets a diff and doesn't need to explore.

Conclusion: coding standards should be enforced by the reviewer (with code-review, covered in part 7), not the implementer. That's why CLAUDE.md and AGENTS.md, loaded into every session, should be used "incredibly sparingly", mostly for navigation pointers to other files.

writing-for-agents: how to write for an agent

writing-for-agents is the reference for any document an agent reads: a skill, an AGENTS.md or CLAUDE.md, or a doc reached through a link. It's the densest skill in the repository; these are its main ideas.

Context pointers

A context pointer is a reference in the agent's context that names outside material and says when to reach it. A skill's description is one; a line in AGENTS.md naming a doc is another. The key: the pointer's wording, not its target, decides whether the agent uses it. If must-have material isn't being used, sharpen the wording first; only inline it if that fails.

The two loads

• Context load: whatever is always loaded (an AGENTS.md line, a skill description) spends tokens and attention every turn, used or not.
• Cognitive load: what the person has to remember (which documents exist and when to use them). It isn't something to minimise: it's the price of you making the calls.

Information hierarchy

A document has steps (what the agent does, in order) and reference (definitions and rules it consults). They sit on a ladder: in-file steps, in-file reference, and disclosed reference in another file reached by a pointer. The test for moving something down: if every branch needs it, keep it inline; if only some do, put it behind a pointer. The opposite failure is sprawl: a document that's simply too long even when every line is live.

Completion criteria

Every step ends on a criterion that says when it's done. A vague one ("understanding reached") invites premature completion, because attention slips to the steps ahead. The best criteria are checkable and exhaustive: "every modified model accounted for" forces more work than "produce a change list".

Leading words and negation

A leading word is a compact concept the model already knows that anchors a behaviour in few tokens: "a *tight* loop", "the test goes *red*". The repository is full of them: *frontier*, *tracer bullet*, *fog of war*. And the opposite: banning something ("don't do X") drags it into context and makes it more likely. Write the behaviour you want in positive terms.

Pruning

• A single source of truth per meaning.
• Don't copy the environment: package.json, config files and --help are already sources of truth. Write only what the agent can't find by looking: the unwritten convention, the reason behind a choice.
• Hunt no-ops: an instruction the model already follows by default does nothing. If a sentence doesn't change behaviour, delete the whole sentence.

For skills

SKILL-MECHANICS.md adds the invocation decision: a model-invoked skill keeps its description always loaded (context load in exchange for the agent finding it); a user-invoked one costs no context, but you have to remember it. When user-invoked skills pile up, the cure is a router skill like ask-matt.

How they combine

retro finds what to change in the environment; writing-for-agents says how to write it so it works. A typical example: in a session, the agent used npm in a repository that uses pnpm. retro classifies it as mechanical and proposes a check (a hook that fails if package-lock.json appears), not another line in CLAUDE.md. If the agent struggled to find where the database queries live, it proposes a navigation pointer, and writing-for-agents says how to word it: leading word first, one clear condition, nothing the folder tree already says.

retro also closes the loop with diagnosing-bugs: after fixing a hard bug, running it in the same session asks what would have prevented it.

Common mistakes

• Turning every mistake into a CLAUDE.md line. That's the pattern the skill tries to avoid: it grows, becomes sediment and the agent ignores it.
• Writing rules in the negative. "Never use npm" is weaker than "use pnpm to install and run scripts".
• Running retro after /clear. It loses the primary source. Run it before, or point it at the session log.
• Duplicating in docs what package.json says. It goes stale.

FAQ

Does retro change files? Its SKILL.md asks it to present the candidates ordered by severity; you decide which to apply.

Is writing-for-agents useful for ordinary prompts? Yes: pointers, completion criteria and no-ops apply to any text a model will read.

Where do the standards the reviewer reads go? In CODING_STANDARDS.md (or CONTRIBUTING.md), which code-review always looks for.

Next step

At the end of your next long session, before clearing context, run /retro and apply only the first candidate. In part 14, the last in the guide, we look at teach and wait-what, the two skills meant to help you understand what the agent is doing.