bmad-review Skill: Review Code and Documents Through Several Lenses

Reviews a diff, pull request or document through separate lenses, such as adversarial and edge-case, and reports the findings.

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

bmad-review is a BMad Method skill for reviews. It runs only when you ask for a review of a diff, a pull request or a document and actually say "review", or when another skill names it. Its description says never to run it uninvited, including on edits Claude just made.

It runs five lenses by default and each applies to code, documents or both. Findings come back as one JSON array, a markdown report or both, with a location, trigger condition, fix and consequence for each. It needs the BMad setup, because it runs uv run scripts from _bmad/scripts.

Good for

Developers who want a second, harsher pass on a diff before merging
Authors who want a document tightened for structure and prose
Teams that want review findings in a consistent JSON shape
BMad users whose other skills polish drafts through this skill

Install bmad-review

Claude Code

Copy this prompt.

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

npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-core-tools --skill bmad-review

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 Node.js, Git, uv.

bmad-review belongs to the bmod-core-tools module and needs the bmad skill, which sets up the _bmad folder in your project. The README needs uv for BMad setup and Python scripts. These are the v7 preview alpha skills from the main branch, which the README says change often. There is no Claude app upload route, because the skill runs uv scripts inside a project folder. The plugin marketplace repo lists the plugins as bmad-method and bmad-toolbox, while the main README calls the second one bmad-core-tools. The plugin tree holds skills only, with no hooks or MCP files.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

Runs one or more installed review lenses — adversarial critique, edge cases, verification gaps, structure, prose — and reports triaged findings. Use when, and only when, the user asks you to review a diff, a pull request, or an artifact — code or documents, one or many — and actually says "review"; an explicit skill:bmad-review directive from another skill counts as that ask. A request to act on feedback from an earlier review is a change, not a review. Never invoke this uninvited, including on edits you just made.

Sections in SKILL.md

Inputs
Conventions
Execution
Output

Key facts

Author: BMad Code (bmad-code-org)
Repository: bmad-code-org/bmad-method
Installs on skills.sh: 12,897 as of 2026-11-02
GitHub stars: 54,859 for the whole repo, 2026-11-02
Last commit to the repo: 2026-11-01
Files: 12 files including SKILL.md (7 in references/, 2 in scripts/ plus a test, bmod.toml and customize.toml)
License: MIT per the repo LICENSE file and README (GitHub license detection reports NOASSERTION)
Module: Part of bmod-core-tools; needs the bmad skill and uv
Status: README calls these v7 skills a preview alpha
Lenses: adversarial, edge-case-hunter, verification-gap, structure, prose

What it includes

Critiques anything; needs at least ten concrete findings
The adversarial lens treats an empty list as a signal to re-check and requires at least ten concrete findings.
Try: “Review this diff with the adversarial lens.”
adversarial
Traces behavior in code, diffs and tickets for edge cases
Applies to content with behavior to trace. It alone also receives the change's own narrative, such as commit messages, when you provide it.
edge-case-hunter
Looks for behavior in code that tests do not pin down
Applies to code, when run inside a repo where tests can be searched and read.
Files · verification-gap
Editorial lens for how a document is organized
Critiques organization only and holds content sacrosanct. It proposes cuts, merges and moves, and the report can include word-count reduction estimates.
structure
Copy-edit lens that runs on top of the structure findings
Fixes clarity inside the existing structure, skips code blocks and frontmatter, and phrases uncertain fixes as "Consider: ...?".
prose
Writes a diff to a temp file, runs lenses, then assembles JSON, markdown or both
For a branch or uncommitted work, Claude writes a unified diff to a uniquely named file in the system temp directory. Lenses run as parallel subagents when available. A report_path setting can write the report to a file.
Runs code · Staging and output
Counts words per heading section for editorial estimates
A Python script (3.11 or newer) that outputs word counts as JSON so reduction percentages use real numbers.
Runs code · scripts/word_metrics.py

From the official docs

Permissions

Low risk

The skill copies your diff to a temp file and runs setup scripts from your project. Do not run it on diffs that contain secrets.

What it can do

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

Watch out for

It runs scripts from your project
The skill calls uv run on scripts in _bmad/scripts, put there by the bmad skill. word_metrics.py needs Python 3.11 or newer. github.com
Your diff is copied to a temp file
For branches and uncommitted work, Claude writes the unified diff to the system temp directory, including untracked files. Avoid it on diffs with secrets. github.com

Technical details

Scopes	Runs uv run scripts from the project's _bmad/scripts folder Writes a staged diff to a uniquely named file in the system temp directory Writes a report to report_path when that setting is filled

Questions

What does bmad-review do?

It reviews code or documents through several lenses and reports triaged findings in one consistent shape.

How do I install bmad-review in Claude Code or Codex?

Use the install box at the top of this page. It installs the skill with the bmad hub skill and its module record. Then ask bmad to run bmad setup in your project.

When does it run?

Only when you ask for a review and say "review", or another skill directs it. The description says never to invoke it uninvited, and that acting on earlier feedback is a change, not a review.

Can I choose which lenses run?

Yes. Name them in your request, or use skill:bmad-review lenses=structure,prose. If you name lenses, only those run.

Is it safe?

It writes a temporary diff file and can write a report if report_path is set, and it runs uv scripts from your project. Keep secrets out of the diff, and read any report it writes.

Is there a ranking or severity in the findings?

No. SKILL.md says no severity, priority or ranking appears anywhere in the output.

Does it work in the Claude app?

The install box leaves out a Claude app upload route, because the skill runs uv scripts inside your project folder. Use Claude Code, Codex or another coding tool that supports skills.

Information

updated Nov 2, 2026

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

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

Sources

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

Show all 11

BMAD-METHOD README · github.com
bmad-plugins README · github.com
bmad-plugins marketplace.json · github.com
bmad-review SKILL.md · github.com
customize.toml · github.com
scripts/word_metrics.py · github.com
bmad-review lens-prose.md · github.com
bmad-review lens-structure.md · github.com
bmad-review lens-verification-gap.md · github.com
bmad-review lens-edge-case-hunter.md · github.com
bmad-review editorial-common.md · github.com