{"slug": "the-retro-skill", "title": "The /retro Skill", "summary": "Matt Pocock released a coding-agent skill called /retro, installable via `npx skills@latest add mattpocock/skills --skill=retro`, that reviews a coding session's own log and proposes repo improvements ranked most severe first. The skill changes the agent's environment rather than the code, routing mechanical violations to automated checks and judgement calls to a reviewer's CODING_STANDARDS.md instead of AGENTS.md, and it only proposes fixes until the user selects a candidate. A repo with no guardrail at all — no pre-commit hook and no CI job running lint, typecheck and tests — is reported as a finding in its own right.", "body_md": "# The /retro Skill\n\nLook back on a session and suggest repo improvements.\n\nInstall this skill\n\n`npx skills@latest add mattpocock/skills --skill=retro`\nThen type `/retro` in your coding agent.\n\n- Source\n- [mattpocock/skills](https://github.com/mattpocock/skills)\n\n## On this page\n\n## [What it does](#what-it-does)\n\n`retro` looks back over a coding [session](https://www.aihero.dev/ai-coding-dictionary/session) and suggests improvements to the agent's **[environment](https://www.aihero.dev/ai-coding-dictionary/environment)**, so the next run goes better. It reads the session's own record (the current one by default, or one you point it at in the session logs), finds the moments the agent struggled, and hands you a list of candidate fixes, most severe first.\n\nIt changes the environment, not the code. The bug the agent shipped, the file it took twenty [tool calls](https://www.aihero.dev/ai-coding-dictionary/tool-call) to find, the rule the reviewer missed: `retro` doesn't fix any of them in place. It asks what about the repo let them happen, and proposes the check, the pointer, or the standard that stops them happening again. It also only proposes; nothing changes until you pick a candidate.\n\n## [When to reach for it](#when-to-reach-for-it)\n\nYou invoke this by typing `/retro`, and the agent won't reach for it on its own.\n\nReach for it at the end of a session that felt harder than it should have: the agent went looking for something for too long, made a mistake a machine could have caught, or needed information it had no way to get. A smooth session has little to teach; a painful one is where the findings are. If what you want is a verdict on the code the session produced, use [code-review](https://www.aihero.dev/skills-code-review) instead.\n\n## [Where the findings land](#where-the-findings-land)\n\nEach candidate belongs to one category, and the category decides where the fix goes:\n\n| What went wrong in the session | Fix it with | \n|---|---|\n| The agent took a long time to find a file or fact | A **navigation pointer** from a file it already reads | \n| It made a mistake a tool could have caught | An **[automated check](https://www.aihero.dev/ai-coding-dictionary/automated-check)** : lint rule, type, test, pre-commit hook, CI job | \n| The reviewer missed a judgement-call mistake | A rule in `CODING_STANDARDS.md` for the reviewer agent | \n| `AGENTS.md` or`CLAUDE.md` is large | Move its steering out, into standards or checks | \n| A tool call was expensive for what it returned | Streamline the tool, or replace it | \n| A steering file is full of lines that change nothing | Delete the **no-ops** | \n| The agent needed information it couldn't reach | Widen its access: tee the dev server log to a file, give read-only access to a service | \n\nThe leading idea is that standards belong to the **reviewer**, not the implementer. The implementing agent carries the most context pressure: it explores, writes code, and debugs failures. The reviewing agent receives a diff and nothing else. So a new rule goes where there is room to apply it, in review, and never in [AGENTS.md](https://www.aihero.dev/ai-coding-dictionary/agents-md), which loads into every session's [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) whether it's relevant or not.\n\nBefore any rule gets written, the violation is classified. A **mechanical** one (a banned API, an import shape, a file-location rule) gets a deterministic check, because a check can fail and a sentence in a standards file can't. Only genuine judgement calls, the kind no linter could ever enforce, become prose. A repo with no guardrail at all (no pre-commit hook, no CI job running lint, typecheck, and tests) is reported as a finding in its own right.\n\n## [Common questions](#common-questions)\n\n**Does it write the lint rule itself, or wait for a yes? Can I wire it to run after every session?**\n\nIt waits. `retro` only proposes; nothing changes until you pick a candidate, so there's no hand-editing and no auto-applied hook either. That is deliberate: one user asked for exactly this after being \"burned by auto-hooks that blocked good changes.\" Deciding what deserves a permanent check takes judgement, so the skill stays [human-in-the-loop](https://www.aihero.dev/ai-coding-dictionary/human-in-the-loop) and user-invoked. Some users do chain it after every implementation run, but a smooth session has little to teach, and running it on every one mostly produces rules nobody needed. There is no dry-run mode: a proposed check is built like any other code, so try it against the repo before you let it block merges.\n\n**Won't this pile up lint rules forever? Does it ever suggest removing one?**\n\nPartly, and this is its weakest spot. The removal side it has covers prose: no-ops in steering files, and steering in `AGENTS.md` or `CLAUDE.md` that belongs in standards or a check. Those it will flag for deletion when the files are large, judged against the session it is reading, so treat each one as a candidate for the deletion test rather than a verdict. It does not audit the lint rules, hooks, or CI jobs it proposed last month. It sees one session, so it can't tell you a rule has gone noisy or outlived the bug that justified it. Pruning checks is still your job; a rule that fires constantly on good code is the cue.\n\n**Won't it just invent generic advice to fill its categories?**\n\nThat's the sharpest critique it gets. One user found that \"once the job is finished, the AI tends to forget the struggles from the middle of the session and invents generic advice to satisfy the retro categories.\" The defence is that every candidate has to come from the session's own record, so the advice is specific to that session. That cuts both ways: it rarely hallucinates something irrelevant, but it can over-index on whatever this one session happened to be about. Discard any candidate you can't trace to a specific moment. Treat the severity order as a first draft too: a quiet, expensive mistake can rank below a loud, cheap one.\n\n**My session is long. Run it now, or start fresh?**\n\nBy default it reviews the current session, which is the best case: the struggles are still in the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window). If the session has drifted out of the [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) already, [clear](https://www.aihero.dev/ai-coding-dictionary/clearing) and point a fresh `/retro` at the previous session in the session logs instead.\n\n**The agent keeps making the same mistake. Should I add a line to `CLAUDE.md`?**\n\nUsually not, and that's the most common place `retro` pushes back. A line in `CLAUDE.md` is loaded into every session, dilutes everything else in the file, and drifts as the code changes. If the mistake is mechanical, the fix is a check that fails. If it's a judgement call, it goes in the coding standards the reviewer reads. `AGENTS.md` and `CLAUDE.md` are for navigation pointers, and little else. For the same reason `retro` is not a [memory system](https://www.aihero.dev/ai-coding-dictionary/memory-system): it doesn't store what happened, it changes the environment so it can't happen again.\n\n**My setup mentions `CODING_STANDARDS.md` and I don't have one. Where does it come from?**\n\nNothing ships the file. The first time a session turns up a judgement-call rule for the reviewer, `retro` proposes starting it, and once you accept, [code-review](https://www.aihero.dev/skills-code-review) reads it from then on. Any other standards doc you already keep, such as `CONTRIBUTING.md`, works the same way.\n\n**How is it different from `improve-codebase-architecture`?**\n\nThe input. [improve-codebase-architecture](https://www.aihero.dev/skills-improve-codebase-architecture) needs nothing but the code and looks for structural improvements to it. `retro` needs a session history, and improves the environment the agent works in rather than the code. They sit side by side; neither replaces the other.\n\n## [It's working if](#its-working-if)\n\n- Every candidate points back to a specific moment in the session, not a generic best practice.\n- Repeat mistakes turn into failing checks, and your `AGENTS.md` gets shorter over time rather than longer.\n- A missing check that already existed but sat unwired shows up as the finding, rather than a proposal to build a new one.\n- The next session on the same kind of task finds its way faster.\n\n## [Where it fits](#where-it-fits)\n\n`retro` is the last step of the main chain, where the flow looks back at itself:\n\n```\ngrill-with-docs → to-spec → to-tickets → implement → code-review → retro\n```\n\nRun it after a build worth learning from, in the same session or pointed at that session's log. A smooth build can skip it.\n\n- [code-review](https://www.aihero.dev/skills-code-review) is the reviewer agent`retro` most often tunes: new coding standards land where its Standards axis reads them.\n- [writing-for-agents](https://www.aihero.dev/skills-writing-for-agents) sets the writing style for every steering file and skill`retro` proposes, and`retro` loads it before it starts.\n\n[ask-matt](https://www.aihero.dev/skills-ask-matt) routes across the whole set when you are unsure which skill the situation wants.\n\nSkill actions\n\n`npx skills@latest add mattpocock/skills`\nInstalls the whole set. Then type `/retro` in your coding agent.\n\n[Skills.sh](https://www.skills.sh/mattpocock/skills)", "url": "https://wpnews.pro/news/the-retro-skill", "canonical_source": "https://www.aihero.dev/skills-retro", "published_at": "2026-10-05 08:30:02+00:00", "updated_at": "2026-10-05 08:46:51.017437+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Matt Pocock", "/retro", "mattpocock/skills"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/the-retro-skill", "markdown": "https://wpnews.pro/news/the-retro-skill.md", "text": "https://wpnews.pro/news/the-retro-skill.txt", "jsonld": "https://wpnews.pro/news/the-retro-skill.jsonld"}}