code-review checks the changes on a branch since a fixed point: the commit, branch or tag you compare against, such as main. It judges them along two axes, two separate questions:
Standards: does the code follow the repo's documented coding standards?
Spec: does the code do what the Issue or Spec behind it asked for?
Each axis runs in its own subagent, at the same time, so neither crowds the other's context. The report shows both side by side, never merged or ranked together. Code can follow every standard and build the wrong thing, or build the right thing and break the repo's conventions. Separate reports stop one hiding the other.
How it works:
Pin the fixed point. If you didn't name one, it asks. It reads git diff <fixed-point>...HEAD; with main, that's git diff main...HEAD. The three dots compare against the merge-base, the commit where your branch left main, so only your branch's changes show. A bad name or an empty diff stops it here.
Find the Spec: Issue numbers in the commit messages, such as Closes #45, a path you give, or a spec file under docs/. If it finds none, it asks you.
Find the standards: every file that says how code should be written, always including CONTRIBUTING.md or CODING_STANDARDS.md if they exist. On top sits a smell baseline: twelve warning signs from Fowler's book Refactoring, such as Mysterious Name and Duplicated Code. The repo's own standards always win over it, and each smell is a judgement call, never a hard fault.
Pin the fixed point.with main, that's git diff main...HEAD
Standards: does the code follow the repo's documented coding standards?
Spec: does the code do what the Issue or Spec behind it asked for?
A report with a ## Standards part and a ## Spec partside by side, never merged or ranked together
Each axis runs in its own subagent, at the same time
When to use it
Reviewing a branch, a pull request or work in progress, or "review since X".
After implement finishes a Ticket, and after implement-spec merges every Ticket into the integration branch.
When not to use it
To write up a finished change for others, use its look-alike pr. That writes the pull request's description; it doesn't judge the code.
A Spec to check against. With none, the Spec axis is skipped and the report says so.
What it creates
A report with a ## Standards part and a ## Spec part, ending with one line: how many findings each axis has, and the worst issue within each. It never picks one winner across the two.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's page on the Skill (updated 2026-08-24) says the design "exists to avoid a generic review skill that does not know your standards". Such a skill "flags what is deliberate in your codebase and misses the invariants your codebase depends on." That's why your repo's own docs come first, and "the repo always overrides".
The header image of Matt's page on the /code-review Skill, updated 2026-08-24. From aihero.dev, 30 October 2026.
In an interview on 2026-09-17, Matt said "one thing that I found works really well is automated review." One agent does the work, and a second "review agent" imposes your coding standards. He doesn't call it a cure. Even "in one line changes", an agent can "produce crap", and that is "something we need to be in a constant battle against."
How it works underneath
Two ideas sit under the Skill.
Fresh eyes. In his end-to-end video (2026-07-16), Matt explains why the axes run in subagents. The main agent "already has written the code", and agents are often "really bad at editing code or improving code they've just written." A subagent starts with "a clear context window". The Skill now says this outright. On 2026-10-29 Matt added "Start every sub-agent with a fresh context window." to its SKILL.md, because "Some Codex models fork the parent conversation when they spawn a subagent." A fork brings the writer's context along. Anthropic's own advice for Claude Code makes the same point about its built-in reviewer: it "isn't swayed by the reasoning that produced the code."
From snapshot/skills/code-review/SKILL.md, lines 6–11: “Two-axis review of the diff between HEAD and a fixed point the user supplies: - Standards: does the code conform to this repo's documented coding standards? - Spec: does the code faithfully implement the originating issue / spec? Both axes run as parallel sub-agents so they don't pollute each other's context, then this skill aggregates their findings.”
Code smells. The baseline comes from Martin Fowler. In 2006 he wrote that "A code smell is a surface indication that usually corresponds to a deeper problem in the system." A smell is a hint to look closer, not proof: "Some long methods are just fine." That's why the Skill labels each smell as "possible", never as a fault.
A real example
In the 2026-07-16 video, Matt runs his whole flow on a real feature. At the end of implement's run, implement loads the review by itself. The repo had no written coding standards, so the review fell back on "some classic ones kind of from Martin Fowler". Both subagents came back. The review had "cross-checked every acceptance criteria against the spec", and only then: "it's now committed against the current branch."
Notice the order in that run: review first, commit after. implement's SKILL.md still says it that way. That order is behind the first failure below.
That run also kept the review inside the session that wrote the code. Matt's page (2026-08-24) prefers a fresh session, because implement's step "runs the review inside the session that just wrote the diff." Since 2026-10-29 the two subagents start fresh. But the writing session still briefs them and cleans up their reports, "verbatim or lightly cleaned".
Where it goes wrong
It can't see uncommitted work. Issue #511 (opened 2026-07-10, still open) says it plainly: the Skill reviews git diff <fixed-point>...HEAD, "which excludes staged and working-tree changes." implement asks for the review before the commit, so the diff can be empty. One user reproduced it on 2026-08-08: the review "failed during fixed-point validation. Standards and Spec reviewers never ran." Matt's page gives the fix: "Commit first, then review, then amend or add a fixup."
Commit first
then review
then amend or add a fixup.
Commit first, then review, then amend or add a fixup.
Its name clashes with Claude Code's. Claude Code ships its own /code-review, which "hunts bugs in the diff". Issue #483 (opened 2026-07-09) reported that installing Matt's Skills means the built-in one "gets clobbered". 37 people gave it a thumbs-up. Matt's page calls it "the most reported problem with the skill". On 2026-10-06 Matt decided not to rename it: "Skill names are not changed because a harness ships a built-in command or skill with the same name". His way through is the plugin's full name, /mattpocock-skills:code-review. If you copied the files with skills.sh instead, rename the folder and the name: field yourself. Be warned: npx skills update "undoes an edit to the frontmatter or a renamed directory."
Its subagents can start more reviews. Issue #573 (opened 2026-07-14) found that the two subagents "regularly invoke /code-review themselves", so each one spawns two more. Matt's page (2026-08-24) called this "a known open bug", and one report "reached more than 50 agents". The deciding word is the current SKILL.md (2026-10-29), which has no guard. That fits Matt's note of 2026-10-06: "The harness should be responsible for stopping infinite subagent loops, not skills." #573 was closed that day as not planned. So: "If you run this unattended, watch the agent count."
It never comes back clean. Each fix adds new code, and smells are judgement calls, so every run finds something new. Matt: "There is no convergence guarantee." Don't loop it "until it comes back clean, because it never will." Anthropic says the same of any reviewer: one "that's asked to find problems will always find" something.
Its findings are leads, not facts. "Sub-agent output is a hypothesis, not evidence." The Skill doesn't re-check each finding against the files, so read the cited rule or Spec line before you act.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't):
On the branch for your booking endpoint, add a CONTRIBUTING.md at the repo's root with one rule, such as "Every route returns a Pydantic model, never a plain dict."
Commit everything, with one commit message that names the Ticket, like Closes #12. Then change one line and leave it uncommitted.
Open a fresh session. Run the review with main as the fixed point. If you installed the plugin, type /mattpocock-skills:code-review main.
Check the report. You should see a ## Standards part and a ## Spec part. Each Standards finding should name your rule or one smell. Each Spec finding should quote a line of the Ticket. Your uncommitted line should be missing.
Fix only the findings with a cited rule behind them. Commit, and stop.
Going deeper's Check questions are asked in Next up.
“Capture the diff command once: git diff <fixed-point>...HEAD (three-dot, so the comparison is against the merge-base). Also note the list of commits via git log <fixed-point>..HEAD --oneline. Before going further, confirm the fixed point resolves (git rev-parse <fixed-point>) and the diff is non-empty.”
From snapshot/skills/code-review/SKILL.md, lines 29–32: “Issue references in the commit messages (#123, Closes #45, GitLab !67, etc.), fetched via the workflow in the tracker doc. 2. A path the user passed as an argument. 3. A spec file under docs/, specs/, or .scratch/ matching the branch name or feature. 4. If nothing is found, ask the user where the spec is.”
From snapshot/skills/code-review/SKILL.md, lines 36–41: “When CODING_STANDARDS.md or CONTRIBUTING.md exists, it must be on the list. On top of whatever the repo documents, the Standards axis always carries the smell baseline below: a fixed set of Fowler code smells (Refactoring, ch.3) that applies even when a repo documents nothing. Two rules bind it: - The repo overrides. A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell. - Always a judgement call.”
From snapshot/skills/code-review/SKILL.md, lines 78–80: “Present the two reports under ## Standards and ## Spec headings, verbatim or lightly cleaned. Do not merge or rerank findings, because the two axes are deliberately separate (see Why two axes). End with a one-line summary: total findings per axis, and the worst issue within each axis (if any).”
From snapshot/skills/code-review/SKILL.md, lines 84–89: “A change can pass one axis and fail the other: - Code that follows every standard but implements the wrong thing → Standards pass, Spec fail. - Code that does exactly what the issue asked but breaks the project's conventions → Spec pass, Standards fail. Reporting them separately stops one axis from masking the other.”
From snapshot/web/aihero.dev/skills-code-review.md, line 135: “This design exists to avoid a generic review skill that does not know your standards. Such a skill flags what is deliberate in your codebase and misses the invariants your codebase depends on.”
From snapshot/web/youtube.com/watch-v-m6myodf0djm.md, line 218: “Doing these in sub agents is really important because if you do it in the main agent, it means that the main agent already has written the code and agents are often”
From snapshot/web/youtube.com/watch-v-m6myodf0djm.md, line 216: “In this repo we don't really have any coding standards documented anywhere, but if it doesn't detect any, then it uses some classic ones kind of from Martin Fowler.”
From snapshot/web/aihero.dev/skills-code-review.md, line 164: “It does not re-verify each claim against the files, so a finding can cite the wrong location or overstate an impact. Read the citation on each finding before you act on it.”
