Try for free

Guides

How to write a code review skill for Claude Code or Codex

A code review skill is a prompt file a coding agent loads when you ask it to review. In Claude Code it is .claude/skills/<name>/SKILL.md, with a name and a description at the top; you run it with /<name>, or Claude picks it when your request matches the description.[1] Codex reads the same SKILL.md format from .agents/skills, and you call a skill with $ or /skills.[2]

IonWarp's eight review agents each run from a prompt file of this shape. Three reads from late September 2026 shaped them. With tools to read the whole repository, 52% of the significant findings in 386 graded reviews rested on code the pull request never touched. Turning the model's reasoning off (142 reviews each way) cut cost by 31% and more than doubled false findings. Halving the turn budget (45 paired reviews) cut cost by 30% but found fewer real issues, so we kept the full budget.

Updated

What goes in a code review skill

  • What counts, and what does not

    One sentence that defines a finding for this review, then short lists of findings to post and findings to skip. Examples teach more than rules: a retry that charges an order twice is a finding; a variable name you would have chosen differently is not.

  • A sweep of every changed file

    The patterns a scan can see: an empty catch, input reaching a query or shell unescaped, a missing auth check, an await inside a loop, a secret in code.

  • A trace of every changed function

    For each function that holds or passes state, walk the real cases: first call and repeat call, success, error and timeout, a value present or missing, events in either order. Check units where a value crosses a boundary, such as cents and dollars. Follow deleted code: what does that job now?

  • For security, who gains what

    For each route the diff changes: who is calling, which ids they control, what check binds them to that scope, and what they can reach. No named attacker and no gain, no finding.

  • Evidence before a finding

    Each finding quotes the line it rests on. A claim about a schema, a type or a function it calls needs that definition read first; no definition, no finding.

  • One output format

    A severity, the file and line, a title that names the consequence, and a suggested fix, as in these code review comment examples. Severity follows the consequence: blocks the merge, should be fixed, or a note.

Run it in Claude Code or Codex

  1. Save the skill

    Claude Code reads .claude/skills/pr-review/SKILL.md and Codex reads .agents/skills/pr-review/SKILL.md. Pick a name other than code-review: Claude Code ships its own /code-review command.[1]

  2. Describe when to use it

    The description is what the agent reads to decide when to load the skill, for example: Review the current branch's diff for defects. Use when asked to review a pull request or a diff.

  3. Run it on the diff

    Type /pr-review in Claude Code or $pr-review in Codex on the branch you want reviewed. On GitHub, Codex code review runs on the pull request instead.

  4. Check, fix, run again

    Treat each finding as a claim: read the line it quotes, fix what holds up, and run the skill again on the new diff.

Sources

  1. Anthropic, Claude Code: Skills, read 2026-10-03.
  2. OpenAI, Build skills, read 2026-10-03.

FAQ

Quick answers

What is a code review prompt?

Instructions that tell a model what to look for in a diff, what to ignore and how to report it. Saved as a skill, it runs the same way every time.

Does Claude Code have a built-in code review command?

Yes. Claude Code ships /code-review, also available as /review, and /security-review for security. A project skill lets you set your own rules for what counts as a finding.

How do I stop an AI reviewer from posting false findings?

Ask for evidence: each finding quotes the line it rests on, and a claim about a schema or a function needs its definition read first. In a late-September 2026 read of IonWarp's CI/CD reviewer, 14 of the 28 findings both graders marked false were claims about how GitHub or a CI vendor behaves, which no repository shows. Tell the reviewer to file only what the repository shows.

Which model should run a code review skill?

It depends on the review. On IonWarp's benchmarks, Muse Spark 1.3 led code review, GLM 5.3 Flash led security and DeepSeek V4 Pro led CI/CD. Our guide to the best LLM for code review has the numbers.

Is a prompt enough, or do I need a review app?

A skill runs when you run it, on your machine. A review app such as IonWarp runs on every pull request, posts its findings on GitHub and tracks each one across pushes until it is fixed or declined.

A first reviewer on every pull request.

Try for free

14 days free, no card. Then Pro is $49 a month per workspace with 5 seats, or Max $149 with 10.