Code Review Skill

A code review skill for AI coding agents — Claude Code, Cursor, Codex, Gemini CLI, and anything that reads SKILL.md.

One agent. One pass. ~1,700 words.

Most AI code review produces a wall of plausible findings. Half are real, half are guesses, and the reader can't tell which — so they stop reading. This skill makes the opposite trade: nothing gets reported without a demonstrated failure. Every finding names the input, state, or sequence that produces the wrong outcome, and findings that can't be traced to one get 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 and the only ones that get harder to fix after merge.

Install

Claude Code:

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

Any agent — it's one Markdown file, no dependencies, no API keys, 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.

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 PR number routes through gh; otherwise it pins the merge-base with your tracking branch and reviews git diff <base>...HEAD (three dots, so commits that landed on the base branch don't pollute the review).

What it does differently

Evidence or silence. No failure scenario, no finding. No "possible issues, unverified" appendix — that's the noise you were avoiding, relabelled.

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

Honest severity. Impact × likelihood, with explicit floors. A Critical label on a Low finding costs more credibility than the finding was worth.

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

Fresh eyes first. Existing review comments on the PR get read after the audit, never before — reading them first anchors you and costs you the findings only fresh eyes get.

Diff scope only. Pre-existing problems in untouched files aren't findings.

Catches the classes that get missed. Authorization checked for login but not for this specific object. Scope creep as a finding, not a bonus. A migration that isn't reversible mid-rollout. A changed env var 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 it couldn't defend out loud to the author — which removes more bad findings than any checklist adds good ones.

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

Approves like a colleague. Approve when the change definitely improves code health, even if imperfect — "not how I'd have written it" is not a defect. But no rubber stamps either: an unearned "LGTM" tells everyone downstream the change was checked when it wasn't.

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

Why it's short

skills/code-review/
├── SKILL.md              # the review, always loaded
└── references/
    └── traps.md          # per-language defects + dependency review, loaded on demand

The heaviest code review skills are not the best ones, and a 2,000-item checklist makes a model work the list instead of reading the code. SKILL.md is ~1,700 words of judgment and rules — the parts a good reviewer needs told to them, not the parts they already know. The one reference file holds the concrete stuff that's only sometimes relevant, so a small review stays cheap.

License

MIT — see LICENSE. Issues and PRs welcome; a rule that caught a real bug in your codebase is worth more than one that sounds thorough.

---

_{Keywords: code review · AI code review · automated code review · agent skill · Claude Code skill · Claude skill · Cursor skill · Codex skill · Gemini CLI skill · SKILL.md · pull request review · PR review · diff review · git diff · code quality · security review · SQL injection · IDOR · N+1 query · performance review · design review · code smells · refactoring · technical debt · test quality · severity triage · maintainability · LLM code review · agentic code review · developer tools}