Skills mattpocock skills Engineering workflow

retro

Use it when:: A coding session went badly or slowly and you want the next one to go better.
It does:: Reads that session's logs and looks for fixes to the agent's setup, not to the code it wrote.
You get:: A list of suggested changes, most severe first, such as a lint check to add or a rule to move out of AGENTS.md.
Needs:: writing-for-agents, a sibling skill on writing docs for agents.
Runs:: Only when you call it.

Skill 22 of 24 in the Engineering workflow bundle, after diagnosing-bugs and before writing-for-agents.

TL;DR

A retrospective on how the agent worked, aimed at its environment: the repo's files, checks and tools. It reads the session you name, from session logs on your machine, or the current one by default, and looks for seven kinds of improvement: files that were hard to find, mistakes an automated check could have caught, mistakes the review agent should have caught, an oversized AGENTS.md, expensive tool calls, instructions that don't change the agent's behavior, and information the agent couldn't reach, such as dev server logs. It favors deterministic checks: a mechanical mistake gets a lint rule, a pre-commit hook or a CI job rather than a written rule, and a repo with no lint, type check or tests run by a hook or CI is flagged on its own. Judgement calls go in a CODING_STANDARDS.md that the reviewer reads, and AGENTS.md is kept to short pointers to other files. It stops at suggestions; making the changes is up to you.

Summarizes the skill at 5beb35b.

npx skills add https://github.com/mattpocock/skills --skill retro

skills.sh page Source on GitHub All skills from mattpocock/skills

Total Downloads: 339,619 on skills.sh, Nov 9, 2026
Repo stars: 318,714 mattpocock/skills
First seen: Aug 24, 2026 on skills.sh

Weekly Downloads

28.6K

+6% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	26,950
Sep 28	23,862
Oct 5	29,987
Oct 12	44,589
Oct 19	36,804
Oct 26	32,260
Nov 2	29,914
Nov 9	28,648

Category	category:debugging category:software-engineering Find root causes, review code and test what you built. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:workflow A multi-step process the agent follows: interview, debug, run a TDD loop, review.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	self-improvement skill-authoring

SKILL.md

From mattpocock/skills at 5beb35b. Checked daily, last changed Oct 20, 2026.

Frontmatter

name: retro
description: "Conduct a retrospective on a coding session."
disable-model-invocation: true

The user has asked for a retrospective. You are suggesting improvements to the coding agent's environment to improve future runs.

Steps

Call the Skill tool with writing-for-agents for the writing style guide.
Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one.
Look for candidates for improvement in these categories.

Navigation: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a navigation pointer make it easier? Use when the session took a long time to find a piece of information.
Automated checks: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its package.json/build-tool lint/check scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no guardrail (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. Use when the agent made a mistake an automated check could have caught, or the repo has no guardrail at all.
Coding standards: should the reviewer agent be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a mechanical one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve CODING_STANDARDS.md for genuine judgement calls (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). Use when the reviewer agent failed to catch a mistake.
Global AGENTS.md: are there any steering instructions that should be moved to coding standards (or automated checks) instead? Use when the AGENTS.md file is particularly large - in the repo OR the user's global scope.
Tool economy: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? Use when the agent made an expensive tool call.
No-ops: look for instructions in steering files that don't modify the agent's behavior. Use when the steering files are large and unwieldy.
Information access: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. Use when a crucial piece of information was not available to the agent.

Present these candidates to the user, in order of severity.

Reference

Implementation vs Review

Remember that all work goes through two stages: implementation and review. The implementation agent has the most context pressure. They are responsible for exploration, writing code, and debugging failures.

The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug.

This means that the review agent should be responsible for imposing coding standards, not the implementation agent.

Files

You have access to several files in the repo:

CLAUDE.md/AGENTS.md: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for navigation pointers to other files.
CODING_STANDARDS.md: this file is read during review, not implementation. Add navigation pointers to docs folders if the standards file gets more than 1,000 lines long.
Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the writing-for-agents skill.