# 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:**

```bash
/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:

```bash
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](LICENSE). Issues and PRs welcome; a rule that caught a real bug in your codebase
is worth more than one that sounds thorough.

---

<sub>**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</sub>