How to use the Session Retrospective agent skill (retro)

What is an agent skill, and what does retro make the agent do?

An agent skill is a folder containing a SKILL.md file. The file tells a coding agent that supports SKILL.md skills, such as Claude Code, how to handle a particular kind of request. The retro skill is one of these. Its description is "Conduct a retrospective on a coding session."

When you ask for a retrospective, the agent looks back over a coding session. By default that is the current session. You can also name a session, which may mean searching session logs on your machine. The agent then looks for ways to make future runs smoother and presents them as a prioritised list of suggestions, in order of severity.

• Navigation: clearer pointers to where information lives, or hidden dependencies between files.
• Automated checks: linting, typing, tests or filesystem linters that could have caught a mistake the agent made.
• Coding standards: a new rule for the reviewer agent, a rule to remove or clarify, or a deterministic check for mechanical rules.
• Global AGENTS.md: steering instructions that could move into coding standards or automated checks, or a file that is too large.
• Tool economy: expensive tool calls or token-inefficient custom tooling.
• No-ops: instructions in steering files that do not change the agent's behaviour.
• Information access: data the agent needed but could not reach, such as dev server logs.

Install the retro skill from the ZIP or the Claude apps

Download the ZIP for skills/engineering/retro from this page. Its files are agents/openai.yaml and SKILL.md. Unzip it so that the retro folder sits in one of the skill locations below.

For a personal skill available in all your projects, unzip it into ~/.claude/skills/. For a skill that only applies to one project, unzip it into that project's .claude/skills/ folder. If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/retro
• Project only: .claude/skills/retro inside the repository

Install the writing-for-agents skill too

The retro skill calls the writing-for-agents skill to get its writing style guide. Without it, that step cannot run, so install it alongside retro in the same location you chose above.

How to trigger retro with natural requests

The skill is set to disable-model-invocation, which means it runs when you ask for it rather than whenever the agent thinks it is relevant. Ask for a retrospective in plain language. You can name a session if you want a past one reviewed.

The skill's own step-by-step text is the best guide to what it will do, so phrase your request around the word retrospective or the outcome you want.

• Run a retrospective on this session.
• Do a retro on yesterday's session in this repo and suggest environment improvements.
• Review the session where the agent kept failing the type checks and tell me what checks would have caught it.
• Look back at this session and say whether our AGENTS.md is too big.

What to expect from the output

The agent reads the primary sources for the session, checks the repository's own check commands and CI workflow first, then presents candidates in order of severity. The skill asks it to read the repo's package.json or build-tool lint and check scripts and its CI workflow before proposing new tooling, so an existing check that is unwired or silently broken is reported as the finding.

The skill also states that a repo with no guardrail, meaning no pre-commit hook and no CI job running its lint, typecheck or test command, is itself a finding.

• Mechanical rules (a fixed pattern, banned API, import shape or file location) are meant to get a deterministic check, such as a custom lint rule, pre-commit hook or CI job.
• Judgement calls, such as matching surrounding style, are the kind of thing CODING_STANDARDS.md is for.

Safety notes before you run it

The skill runs no scripts and uses no network access, according to its source. It may, however, search session logs on the machine to find the session you name. Review what it accesses before running it, especially for sensitive sessions.

The skill's suggestions depend on existing lint, test or CI setup, so results are weaker in repositories with little tooling.

• Check which session logs the agent reads if the session is sensitive.
• Expect fewer useful suggestions in repos with no lint, test or CI setup.