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
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]
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.
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.
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
- Anthropic, Claude Code: Skills, read 2026-10-03.
- OpenAI, Build skills, read 2026-10-03.
