Skip to main content
Agent skill

Code Review

Use when reviewing code — a diff, a merge request, a file, a directory, or a feature. Produces structured code-review findings, filters out false positives and nitpicks, and prints a concise verdict report. Trigger when the user asks to review a diff, review an MR, or check code for bugs, security issues, or rule violations.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/code-review && curl -fsSL 'https://raw.githubusercontent.com/croffasia/itsaplan/main/.agents/skills/code-review/SKILL.md' -o ~/.claude/skills/code-review/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Code Review when an AI agent needs a reusable SKILL.md workflow for this job: Use when reviewing code — a diff, a merge request, a file, a directory, or a feature. Produces structured code-review findings, filters out false positives and nitpicks, and prints a concise verdict report. Trigger when the user asks to review a diff, review an MR, or check code for bugs, security issues, or rule violations.

When not to use it

Skip Code Review when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/code-review && curl -fsSL 'https://raw.githubusercontent.com/croffasia/itsaplan/main/.agents/skills/code-review/SKILL.md' -o ~/.claude/skills/code-review/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/code-review/SKILL.md. For a shared project, commit the folder at .claude/skills/code-review/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Code Review skill for this task: Use Code Review when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Code Review

Three-stage method: produce findings, filter them, report verdict.

Stages 1 and 2 are internal reasoning. Never print them. Only the Stage 3 report reaches the user.

## Review target

- User named a target (file, directory, feature, commit range, MR) → review that. - No target named → review current diff (uncommitted changes, or the branch diff against the main branch).

Read the code with workspace tools. When code is supplied inline in the prompt, review what is supplied and read further files only for context.

## Stage 1 — Reviewer

Review target. Collect findings.

### Review algorithm (follow this order)

1. Read project rules — MANDATORY. Read every instruction file covering the reviewed code: root AGENTS.md plus nested ones in the touched directories, and any docs they point to. Project rules override skill rules on conflict 2. Load skills — MANDATORY. Load workspace skills matching the reviewed stack and area (framework, language, UI text, testing). Read their rule files via workspace tools, never from memory 3. Big picture — scan the whole change set for cross-file context 4. Analyze change — split core change vs plumbing. Core design wrong → focus there 5. Full-file context — check the change makes sense: imports used, removed items not referenced, control flow correct 6. API compatibility — check callers match changes 7. Apply skill rules — check violations from this change only, not pre-existing code 8. Apply project rules — check violations of AGENTS.md 9. Deduplicate — skip findings already covered by existing review comments 10. Verify relevance — each finding must fit actual code context (file type, framework, stack), not generic rule mismatch 11. Verify against source — re-read the cited lines. Drop findings referencing code, symbols, imports, or behavior that does not exist in the file. Never describe code from memory or assumption 12. Check the fix — proposed fix must be the smallest change that solves the problem. Drop or rewrite fixes that add abstractions, layers, options, or generalization the problem does not need 13. Keep — only confidence >= 80, reviewed code only, no linter catches or nitpicks. Fix line says WHAT to fix in 1 sentence, not HOW

### Focus on

- Data loss, security holes (XSS, injection, secrets in code) - Runtime crashes, unhandled errors, null/undefined access - Broken core logic, wrong conditions, off-by-one errors - Race conditions, missing await, wrong async handling - API contract violations, wrong types passed between components - Functions whose behavior contradicts their name or return type - Stub or placeholder implementations merged without TODO/FIXME markers - Public functions where invalid but plausible input gives silently wrong results instead of error - Unreachable code paths or dead branches caused by change - New exports or public API surface not consumed anywhere - Obvious performance pitfalls: O(n²) or worse in loops over collections, sync blocking in async paths, missing pagination on unbounded queries, repeated expensive operations that should be cached or batched - Hardcoded values that clearly should be configurable or computed (e.g., hardcoded URLs, credentials, environment-specific paths, magic numbers used as thresholds or limits) — flag as suggestion unless marked TODO - Functions that claim operation by name but have trivial implementation that does not do it (e.g., `isFileExists` returning constant without checking filesystem, `sendEmail` with empty body) — flag unless marked TODO - Misused dependencies — components, functions, composables or utilities called with wrong arguments, wrong types, ignored return values, missing required props/options, or invoked in way that violates their contract (when signature visible in provided context) - Reinvented shared utilities — new logic that duplicates existing shared helper/component/composable from project (e.g., hand-rolled deep clone, date formatter, query builder, or validator) when equivalent visible in provided context; flag and point to existing one to reuse

### Do NOT check

Code style, naming, missing comments, test coverage, performance micro-optimizations.

### Finding fields

Track per finding, in your head, not printed at this stage:

- file and line - title: short, one line - problem: what is wrong - fix: what to fix, one sentence - severity: critical (confidence 90-100) = data loss, security, crash, broken logic. suggestion (confidence 80-89) = everything else - source: which rule triggered the finding. One of `skill:<skill-name>/<rule-name>`, `repository-rules` (AGENTS.md), `general` (Focus on section)

Source priority when a finding matches several categories: repository-rules > skill > general. Use the highest-priority source that applies.

## Stage 2 — Filter

Act as senior code review editor. Filter findings list. Keep ONLY ones that are:

1. **Real issues** — not false positives, not nitpicks, not style preferences 2. **Actionable** — developer clearly understands what to fix 3. **High confidence** — you agree with finding after review 4. **Critical severity** — NEVER drop findings with severity "critical". May adjust description but must keep in output. Believe critical finding is false positive → downgrade severity to "suggestion" instead of removing.

Remove findings that are:

- Hallucinated — cited line, symbol, or behavior not present in the actual code - Overengineered fixes — solution heavier than the problem (new abstraction, config, or layer where a local change is enough) - Duplicates or overlapping with other findings - Too vague or speculative - About pre-existing code patterns (not from this change) - Nitpicks disguised as suggestions - False positives from incomplete context

For each kept finding, may adjust confidence, severity, or description.

Then pick a verdict: approve, request_changes, or comment.

Verdict rules:

- approve: no findings kept - request_changes: at least one critical finding - comment: only suggestions

## Stage 3 — Console report

Do NOT edit, write, or fix any code. This skill only reviews and reports.

Print the kept findings as plain text for a human reading a terminal. No preamble, no closing summary, no extra commentary, only the report below.

Format:

``` Verdict: <verdict> (<N> critical, <M> suggestions) Reviewed: <what was reviewed>, <K> files

CRITICAL <file>:<line> <title> [<source>] <problem> Fix: <fix>

SUGGESTIONS <file>:<line> <title> [<source>] <problem> Fix: <fix> ```

Example:

``` Verdict: request_changes (1 critical, 1 suggestion) Reviewed: uncommitted changes, 3 files

CRITICAL apps/api/src/planner/issues.ts:118 Transaction never committed The early return on a validation error leaves the transaction open, so the connection leaks. Fix: commit or roll back before returning. [general]

SUGGESTIONS apps/web/src/features/board/Column.tsx:64 Board key hardcoded "IAP" is written inline instead of coming from props. Fix: take the key from the project prop. [repository-rules] ```

Rules:

- Critical findings first, then suggestions. Omit an empty section. - No findings at all: print only `Verdict: approve (no issues found)` plus the `Reviewed:` line. - One line per field. Problem and fix stay one sentence each. No paragraphs, no tables, no JSON. - Source tag in brackets so the reader knows whether it came from project rules, a skill, or built-in checks. - Sort findings inside a section by file, then by line.

Intended uses

  • Use Code Review when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.