bmad-retrospective Skill (BMad) for Claude Code: What It Does and How to Install It

Makes Claude review a finished epic against its commits, plans and tickets, then write a sourced retrospective with a verdict.

Installs: 10K; on skills.sh
Stars: 54.9K; on GitHub
Files: 10; besides SKILL.md
Updated: Nov 2026; last repo commit

This skill is the retrospective step of the BMad Method. Claude gathers what a finished epic left behind, analyzes it, and writes a retrospective document. Every finding must point to a file, line, commit or log, or it is dropped. The document ends with action items and a verdict: accepted, accepted-with-open-items or rejected.

It only works in a project with BMad set up, and it needs uv. It is a runner: SKILL.md runs a script from your project's _bmad folder and follows the workflow it prints. A headless mode with -H skips confirmations for automation.

Good for

Teams using the BMad Method who finish epics and want a retro
Orchestrators that need a machine-readable accepted or rejected verdict
Tech leads who want findings tied to files, commits and logs

Install bmad-retrospective

Claude Code

Copy this prompt.

Install the bmad-retrospective skill in Claude Code. Run this command:

/plugin marketplace add bmad-code-org/bmad-plugins

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires uv.

The skill only runs inside a project that has BMad set up, so install the BMad pieces and then ask the bmad skill to run bmad setup. It needs uv, Git and Python 3.10 or newer per the README, and it runs local scripts, so there is no Claude app upload route. The skills CLI route is interactive: pick bmad-retrospective, plus bmad and bmod-method, which the README names as the setup hub and the module record for this skill. The plugin route installs bmad-method (21 skills, counted from the bmad-plugins tree). The BMad README names a second plugin bmad-core-tools while the bmad-plugins repo lists bmad-toolbox, so check the marketplace listing.

From the project README. Source.

What's in the skill

When it loads

Review a finished epic folder in the ticket tree against the evidence it left behind — the epic file, each ticket's story file and plan, diffs, commits — and produce a retrospective with sourced findings, action items, and an acceptance decision. Use when the user says "run a retrospective" or "lets retro the epic [epic]". Supports -H/--headless

Key facts

Author: BMad Code (bmad-code-org; maintainers of BMAD-METHOD)
License: NOASSERTION
Installs on skills.sh: 9,984 (Nov 2, 2026)
GitHub stars: 54,859 for the whole BMAD-METHOD repo (Nov 2, 2026)
Last repo commit: Nov 1, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: warn, Snyk: pass
What it includes: 11 files including SKILL.md: workflow.md, 5 reference files, customize.toml, bmod.toml, git_evidence.py and its test
Needs: BMad set up in your project (the _bmad folder), uv and Git
License sources: The crawl found none (NOASSERTION); the README badge and the bmad-plugins marketplace say MIT
Release line: The skills in this repo are part of BMad V7 preview alpha, per the README

What it includes

SKILL.md runs uv run _bmad/scripts/render_skill.py to print the workflow
The script lives in your project after BMad setup. If it is missing, Claude offers to set BMad up with the bmad skill.
Runs code · Activation: render_skill.py
Pick an epic folder, id or slug, or choose from finished epics
Runs tickets.py status. Headless mode needs an epic named up front.
Runs code · Choose the epic
Inventories the epic file, tickets, plans, story files and diff ranges
Runs git_evidence.py for each plan range, and records missing evidence.
Runs code · Phase 1: Gather
Aggregate views, diff review with bmad-review, and a behavior check
The behavior check exercises the changed flows end to end when runtime behavior changed. Every finding needs a source.
Runs code · Phase 2: Analyze
Runs bmad-party-mode on the findings if you ask
Never runs in headless mode.
Read · Phase 3: Team discussion (opt-in)
Action items, decision records and an acceptance verdict
Verdicts are accepted, accepted-with-open-items or rejected. Any unfinished ticket forces rejected from the machine.
Write · Phase 4: Decide
Writes epic-<slug>-retrospective.md in the epic folder
SKILL.md says the document and approved decision records are the only writes; it does not mark tickets or edit plans.
Write · Phase 5: Finalize
Skips confirmations and records assumptions in the document
For automation. Needs an explicit epic.
Runs code · Headless mode (-H)
activation_steps_prepend, activation_steps_append, persistent_facts, on_complete
Lets you add steps, standing facts or a post-completion step.
Read · customize.toml hooks

From the official docs

Permissions

Medium risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It runs a script from your project
SKILL.md runs uv run --no-cache on _bmad/scripts/render_skill.py and follows what it prints as the workflow. Review that script, because it comes from your BMad install. github.com
The behavior check can run your app
Phase 2 says to exercise changed flows end to end when the epic changed runtime behavior. Run it in a development environment. github.com
Headless mode skips confirmations
With -H it takes the epic from the invocation, skips every confirmation and records assumptions in the document. The Phase 4 acceptance fail-safe still applies. github.com
The plugin route adds 21 skills
The bmad-method plugin in the bmad-plugins repo has 21 skills (counted from its tree). That tree shows no hooks or MCP config files. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only switch. SKILL.md says its only writes are the retrospective document and approved decision records.
Sign-in and keys	SKILL.md and the workflow do not mention any account or key.
Scopes	Runs uv run against _bmad/scripts/render_skill.py in your project Runs git_evidence.py, which measures git commits and file changes Writes epic-<slug>-retrospective.md and approved decision records

Questions

What does the bmad-retrospective skill do?

It makes Claude review a finished epic against the evidence it left: the epic file, tickets, plans, diffs and commits. Claude writes a retrospective with sourced findings, action items and an acceptance verdict.

Does it work without BMad installed?

No. SKILL.md runs a script from your project's _bmad folder. If the script is missing, it says BMad is not set up and offers to set it up with the bmad skill. It also uses a ticket tree that BMad creates.

How do I install it?

Use the install box at the top of this page. The BMad README documents a skills CLI route and Claude Code and Codex plugin marketplaces. After installing, ask the bmad skill to run bmad setup. It needs uv and Git.

What is the acceptance verdict?

One of accepted, accepted-with-open-items or rejected, judged against the epic file's Requirements and Done when. Any unfinished ticket forces a machine verdict of rejected, though a human can override it interactively.

Does it change my code or tickets?

SKILL.md's finalize step says the retrospective document and any decision records you approve are its only writes. It does not mark tickets, or edit plans, story files or the epic file. Fixes are proposed as action items.

Can it run unattended?

Yes, with -H or --headless and an epic named. It skips confirmations and records each assumption in the document. The acceptance fail-safe still applies.

Is it safe?

It runs a project script through uv, runs git read commands through a bundled script, and may exercise your app for the behavior check. Check the epic and the scripts in your _bmad folder before a headless run.

Information

updated Nov 2, 2026

Repository: bmad-code-org/bmad-method
Folder: skills/bmad-retrospective

bmad-code-org/bmad-method skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 10

BMAD-METHOD README · github.com
bmad-plugins README · github.com
bmad-plugins marketplace.json · github.com
bmad-retrospective SKILL.md · github.com
workflow.md · github.com
customize.toml · github.com
acceptance-verdict.md · github.com
retro-document.md · github.com
evidence-gathering.md · github.com
git_evidence.py · github.com