bmad-walkthrough Skill for Claude Code: Walk Through a Commit or PR

BMad Method skill that guides you through a commit, PR, file or folder one block at a time, so you can review it yourself.

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

Point it at a commit, PR, file or directory and it splits the change into blocks: intent, broad strokes, one slice per concern and a periphery block. It shows one block at a time and waits until you say that block is done. It also writes a review narrative and a review log into a walkthrough folder.

It only works in a project where BMad is set up, because its SKILL.md runs a script from the project's _bmad folder through uv. It tells the agent to install the bmad skill first if it is missing. The folder has 8 files including SKILL.md and no scripts.

Good for

Developers reviewing a PR they did not write
Authors who want to re-read their own AI-written change in small steps
Reviewers who want a written narrative and a log of what they checked

Install bmad-walkthrough

Claude Code

Copy this prompt.

Install the bmad-walkthrough 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.

bmad-walkthrough needs BMad set up in your project: its SKILL.md runs a script from the project's _bmad folder and tells the agent to run the bmad skill's setup when that script is missing. Pick one route, not both. The marketplace manifest lists this skill's folder under the bmad-method plugin, so install bmad-method after you add the marketplace, plus the plugin that holds the bmad skill (the bmad-plugins README names bmad-method and bmad-toolbox). Then ask the bmad skill to run bmad setup. Skills CLI route: it asks which coding tools to install to, so choose Claude Code, then ask the bmad skill to run bmad setup. BMad needs uv for its setup and Python scripts. The README calls v7 a preview alpha with breaking changes between updates.

From the project README. Source.

What's in the skill

When it loads

Guide a human review of a commit, PR, file, or directory. Use when invoked by name

Key facts

Author: BMad Code (owner of the bmad-code-org/bmad-method repo)
License: README and the plugin marketplace manifest say MIT; GitHub reports no detected license
Installs on skills.sh: 12,544 as of 2026-11-02
GitHub stars: 54,859 for the whole bmad-code-org/bmad-method repo, 2026-11-02
Last repo commit: 2026-11-01
Files: 8 files including SKILL.md (workflow, 3 step files, log template); no scripts
Needs: uv, and BMad set up in the project (SKILL.md)

What it includes

Reads the ticket, plan, PR text or commits and asks questions until the intent is clear.
Read · Step 1: Orientation
Writes the narrative and a review log into a new walkthrough folder.
The folder is created under the initiative folder and named after a review slug.
Write · Step 2: Create review narrative
Presents one block, suggests 1 to 3 moves and waits until you call the block done.
Read · Step 3: Walkthrough
Intent, Broad strokes, one Slice per concern, then Periphery.
Read · Blocks
Asks a fresh subagent that has not seen the review so far.
Read · Move: Second opinion
Uses a formal review skill such as bmad-code-review when it is installed.
Read · Move: Formal review
Identifies checks, runs what it can and records what was tested.
Runs code · Move: Test
Starts the app and tells you which buttons to push.
Runs code · Move: Drive
Exercises the change and saves screenshots or a transcript in the walkthrough folder.
Runs code · Move: Demo
Diagrams the block's mechanism and saves the source in the walkthrough folder.
Write · Move: Draw
Proposes a follow-through, such as merging the PR, and waits for your yes.
Runs code · Move: Wrap-up

From the official docs

Permissions

Medium risk

It writes review files into your project and can run your app or tests, but its steps say moves start only when you pick them. Check what Wrap-up proposes before you agree to it.

What it can do

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

Watch out for

Some moves run your app and tests
Test runs checks, Drive starts the app and Demo exercises the change and saves screenshots. The steps say the moves start only when you pick them, so choose them deliberately. github.com
It can offer to commit or push
On a dirty tree it asks whether to commit, and Wrap-up guesses a follow-through such as merging a PR or pushing. The step says it does nothing until you say so. github.com
This is a preview release
The BMAD-METHOD README calls v7 a preview alpha with breaking changes between updates. github.com

Technical details

Scopes	Runs uv run on _bmad/scripts/render_skill.py in your project Writes walkthrough-<slug>/ with a review narrative and a log under your initiative folder Moves can start your app, run tests and save screenshots or diagrams Wrap-up can lead to merging, committing or pushing, but only after you say yes

Questions

What does bmad-walkthrough do?

It guides a human review of a commit, PR, file or directory. The assistant presents one block at a time and records the outcome in a review narrative and a log.

How do I install it?

Use the install box at the top of this page. After installing, ask the bmad skill to run bmad setup, because this skill needs BMad set up in the project.

Does it work in the Claude app or claude.ai?

This page documents no install for the Claude app. The skill needs uv and a project folder with BMad set up, so the box lists Claude Code, Codex and the skills CLI.

Is it safe?

It writes review files into your project and some moves run your app or tests. The steps say a move starts only when you pick it and Wrap-up waits for your yes. Our advice: read what Wrap-up proposes before you agree.

When is a review finished?

Only when you say so. The workflow says a block, and the review as a whole, is done only when you call it done.

bmad-walkthrough vs bmad-code-review?

Walkthrough is you reviewing with the assistant explaining. Its Formal review move uses bmad-code-review if that skill is installed, and prefers it for code.

Information

updated Nov 2, 2026

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

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

Sources

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

Show all 8

README.md · github.com
README.md · github.com
marketplace.json · github.com
SKILL.md · github.com
workflow.md · github.com
step-03-walkthrough.md · github.com
bmad-walkthrough step 1 · github.com
bmad-walkthrough step 2 · github.com