A code review skill that only reports demonstrated failures

TL;DR

• The rule that separates it from most AI review: nothing gets reported without a demonstrated failure — every finding names the input, state or sequence that produces the wrong outcome, and anything that cannot be traced to one is dropped silently.
• It reviews in the order a senior engineer actually reviews: design, spec conformance, correctness, complexity, tests, naming, blast radius — because design problems are the expensive ones.
• It reads the existing PR comments after its own audit, never before, so it is not anchored to someone else's framing.
• It is one Markdown file plus one lazy-loaded reference — roughly 1,700 words of judgment, not a 2,000-item checklist.

What it is and who it is for

Code Review Skill is a code review skill for AI coding agents — Claude Code, Cursor, Codex, Gemini CLI and anything that reads SKILL.md. The README describes the target in one line: one agent, one pass, about 1,700 words.

It is for the person who has stopped reading AI review output. The README's diagnosis is that most AI code review produces a wall of plausible findings where half are real and half are guesses and the reader cannot tell which, so the reader stops reading. This skill makes the opposite trade.

What it does differently

Evidence or silence. No failure scenario, no finding. There is no "possible issues, unverified" appendix — that appendix is the noise the reader was avoiding, relabelled.

Never guesses where it can read. A finding conditioned on unfinished research — "this breaks unless the backend validates it" — is not allowed when the backend is right there in the repository.

Honest severity. Impact times likelihood, with explicit floors, because a Critical label on a low-impact finding costs more credibility than the finding was worth.

Design before details. And it applies a counter-test to any refactor: count the concepts a reader must hold. If the "cleaner" version leaves that count unchanged, complexity was relocated rather than reduced.

Fresh eyes first. Existing review comments on the pull request are read after the audit, never before, because reading them first anchors the reviewer and costs the findings only fresh eyes produce.

Diff scope only. Pre-existing problems in untouched files are not findings.

The classes that get missed. Authorization checked for login but not for this specific object. Scope creep reported as a finding rather than a bonus. A migration that is not reversible mid-rollout. A changed environment variable or port that breaks everyone's local build. A bulk dependency bump with no changelog read.

Deletes its own weak findings. A final pass drops anything the reviewer could not defend out loud to the author — which the README says removes more bad findings than any checklist adds good ones.

Defers to your repository. CONTRIBUTING.md, CLAUDE.md, AGENTS.md, .cursor/rules/ and the lint config all outrank the skill, and anything the linter or type-checker already reports is off the table.

How to use it

In Claude Code, through the plugin marketplace:

/plugin marketplace add artificialguybr/code-review-skill
/plugin install code-review

For any other agent, the skill is one Markdown file with no dependencies, no API keys and no external service:

git clone https://github.com/artificialguybr/code-review-skill /tmp/crs
cp -r /tmp/crs/skills/code-review ~/.claude/skills/code-review   # or .claude/skills for one project

Cursor reads .cursor/skills/, Codex .codex/skills/, Gemini CLI .gemini/skills/ — same directory, different destination.

Then ask in the shape you already use:

review my changes
review this branch against main
review PR #418
is this safe to merge?
review my changes and fix what you find

A pull request number routes through gh. Otherwise the skill pins the merge base with your tracking branch and reviews git diff <base>...HEAD with three dots, so commits that landed on the base branch do not pollute the review — the same discipline as comparing a model against its own baseline rather than a moving target.

Why it is short

The whole skill is two files: skills/code-review/SKILL.md, which is always loaded, and references/traps.md, which holds the per-language defects plus dependency review and loads only on demand. The README's argument is that the heaviest code review skills are not the best ones, and that a 2,000-item checklist makes a model work the list instead of reading the code.

Approving like a colleague

Two rules cover the judgment that tools usually get wrong. Approve when the change definitely improves code health, even if imperfect — "not how I would have written it" is not a defect. But no rubber stamps either: an unearned "looks good to me" tells everyone downstream that the change was checked when it was not.

Never fix by suppression. When the skill is asked to fix its own findings, each fix gets the regression test that would have caught it, and no widened catch, disabled lint rule or loosened assertion.

When to use it, when not to

Use it for a real review of a branch or a pull request, especially when you want to know which of the findings are actual defects, and when the diff touches authorization, migrations or dependencies where the missed classes are expensive.

Do not use it as a substitute for a test suite. The skill reads code and proposes the test that would have caught each finding; it does not run your suite. And do not expect it to catch pre-existing problems in files the change does not touch — that scope limit is deliberate, and it is why the review stays cheap.

Sources

1. Code Review Skill — repository — rules, review order, install commands, file structure and licence quoted above.
2. README.md — install and usage commands, license.

Project page: Code Review Skill

The skill is MIT-licensed and accepts issues and pull requests; the README's own preference is a rule that caught a real bug over one that sounds thorough.

FAQ

How long is the review? One pass, roughly 1,700 words of judgment in SKILL.md, plus a reference file that loads only when a language-specific or dependency question comes up.

Why does it drop findings? Because a finding that cannot be traced to a demonstrated failure is a guess; dropping it is what keeps the report readable, and the README says that removes more bad findings than a checklist adds good ones.

Does it read existing PR comments? Yes, but only after its own audit, so it is not anchored to someone else's framing.

Will it fix what it finds? When asked, yes. Each fix comes with the regression test that would have caught the finding, and no widened catch, disabled lint rule or loosened assertion.