Skip to main content
skill CX Codex

self-review · sammcj — Claude Code skill for critical self-review of changes

self-review — a skill that critically reviews your recent changes and fixes what it finds. Small edits it handles itself; larger ones go to a sub-agent.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill self-review -a claude-code
Open on GitHub

What self-review does

The skill picks one of two paths based on change size. For a single file or one focused fix, it re-reads the edit with a sceptical eye: correctness, completeness, regressions, over-engineering, unwarranted verbosity. Then it fixes the issues directly.

For work that spans multiple files, features or fixes, the skill delegates to the critical-reviewer sub-agent. That reviewer works outside your conversation context, so it keeps review reasoning out of your context and gives an unbiased read. It returns prioritised findings, each with a severity and a file:line location. You triage by severity and apply what is valid.

When delegating, the skill wants a high-signal brief: changed file names from git diff --name-only, the original task, scope boundaries, and notes about intentional oddities. Terse notes beat prose. For very complex reviews the skill suggests the most capable model available, such as fable; normal reviews can run on opus. Parallelise only on independent slices, and if slices share an interface, one reviewer must see both sides. The review loop caps at 3 cycles.

What it helps with

  • Catch regressions in your own edits
  • Spot over-engineering in a change
  • Hand large reviews to an unbiased sub-agent
  • Sort findings by severity and file:line
  • Keep review reasoning out of your context

Example prompts for the agent

  • Review my latest changes with the self-review skill
  • Run critical-reviewer on the auth module, here is the file list
  • Self-review recent edits and fix what you find

How to install self-review

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill self-review -a claude-code

2Manually: put the files in place

~/.claude/skills/self-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/self-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about self-review

How do I install self-review in Claude Code?

Run npx skills add sammcj/agentic-coding --skill self-review -a claude-code. The skill lands at ~/.claude/skills/self-review/SKILL.md.

What does the self-review skill do?

It re-reads your recent changes with scepticism and fixes what it finds. For small changes it reviews directly; for larger ones it delegates to the critical-reviewer sub-agent.

When should I delegate the review instead of doing it myself?

When the change touches several files, features or fixes. A fresh reviewer catches what you have talked yourself into during the task.

Source text

SKILL.md · Apache-2.0
---
name: self-review
description: Use to critically self-review your changes, or when you want to delegate the review to a sub-agent.
argument-hint: "[optional focus or extra context]"
---

Critically review your recent changes and fix any issues you find. Choose one of the two paths below, based on the size of the change. When in doubt, delegate - the cost is low and the unbiased read is the point.

## Option A: Review it yourself (small or simple changes)

For a single file, or one focused fix or feature: Re-read what you changed with a sceptical eye - correctness, completeness, regressions, over-engineering, unwarranted verbosity.

Then fix what you find directly.

## Option B: Delegate to the reviewer (larger changes)

For changes spanning multiple files, features, or fixes: Delegate to the `critical-reviewer` subagent(s) for a fresh, unbiased read, then act on what they report.

- A fresh reviewer catches what you've talked yourself into, and keeps the review reasoning out of your context.
- The reviewer is read-only and returns prioritised findings (each with a severity and a `file:line` location); you triage by severity and apply the fixes.

When you delegate:

- **If the change is large or complex.** Consider calling the sub-agent with the fable model (if it's available) as it's the most powerful AI model.
- **Provide a high signal brief.** The agent operates outside of this conversation's context. Give it: the list of changed files (names only, e.g. `git diff --name-only`), the task you were originally asked to do and what was in / out of scope, and anything intentional that looks wrong but isn't.
- **Parallelise only on independent slices.** Spawn one reviewer per group of changes that don't interact (by subsystem, layer, or requirement), and give each an explicit boundary - the files or area it owns - so they don't overlap. When slices share an interface or contract, brief at least one reviewer on both sides, or use a single reviewer - a fresh reviewer that sees only one side can't catch the interaction. Don't split for its own sake.
- **Stay fresh by default.** A fresh reviewer gives the unbiased read that makes self-review worth doing. Fork only if the review genuinely needs this conversation's nuance; never fork it for the adversarial read, since a fork inherits this agent's bias and defeats the point.
- **Write the brief in terse notes.** Keywords and bullets, not full prose; the reviewer is a capable model, not an audience.
- **For very complex changes pick the best model.** If the work to review is very complex, use the most capable model available (e.g. `fable`), for normal reviews use the default model (`opus`).

After each reviewer agent has finished and returned it's findings (unless there is a good reason to wait for all findings, or instructed otherwise):

1. Action the (valid) findings.
   - **Fix what's real.** Apply the fixes for genuine findings, then verify (build, tests, lint). Push back on findings that are wrong rather than changing correct code to satisfy them.
2. If you make large amounts of changes, loop back and run another review cycle (maximum loops: 3).

---

`$ARGUMENTS`

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Code review and refactoring →

self-review by other authors comes first.

self-review lingzhi227 The self-review skill reviews an academic paper with the NeurIPS form, three reviewer roles, and score aggregation. Use it to assess a draft before submission. CX Codex +1 1,700installs Self-Review wrg32786 The Self-Review Claude Code skill sends substantial code changes through a focused second review. It targets multi-file edits, hot paths, prompts, and work that still feels uncertain. CX Codex +1 ★ 26repo stars tooluniverse-self-review mims-harvard tooluniverse-self-review evaluates current work against original requirements and surfaces verified gaps, risks, and next fixes without scoring. CX Codex +1 111installs self-improvement-ci pskoett self-improvement-ci — a CI-only skill that groups recurring pull request check failures and proposes rules so the same breakage stops coming back. CX Codex +1 550installs self-eval Alireza Rezvani The self-eval skill rates AI work on two axes, checks for inflated scores, and keeps an evaluation history. Use it after a task, code review, or work session. CX Codex +1 575installs loop-architect https://ft.ia.br loop-architect is a Claude Code skill that guides iterative workflow design, from goal refinement and verification criteria to reviewer selection and termination guards. CX Codex +1 ★ 141repo stars paper-self-review Galaxy-Dawn paper-self-review is a Claude Code skill that checks academic paper structure, reasoning, and whether evidence supports its claims. It runs for self-review before a journal or conference submission. CX Codex +1 702installs performance-review-self-assessment thedesignproject The performance-review-self-assessment Claude Code skill guides employees through a quarterly self-assessment. It covers accomplishments, challenges, leadership principles, and progress on development goals. CX Codex +1 ★ 107repo stars

From the same set73

The whole set →
deferred-task-execution deferred-task-execution delays command execution in Claude Code for a specific duration or until a chosen time. Handy when builds or scripts need to wait. CX Codex +1 ★ 173repo stars compression-editor compression-editor is a Claude Code subagent that shortens prose, instructions, skills, and docs without losing meaning. It skips source code and summarisation. CX Codex ★ 173repo stars explain Explains code, systems, and algorithms using terminal ASCII diagrams or standalone interactive HTML step-through pages. CX Codex +1 ★ 173repo stars openspec-bootstrap openspec-bootstrap sets up OpenSpec in a repository by preparing its schema and config. Use it for a first-time setup or edits to openspec/config.yaml. CX Codex +1 ★ 173repo stars writing-fragments The writing-fragments skill interviews you about a writing topic and saves promising bits in one Markdown file. Use it to gather ideas before deciding how an article should be structured. CX Codex +1 ★ 173repo stars code-simplification code-simplification is a Claude Code skill that spots hard-to-follow code and suggests refactors. It comes into play during code review or when reducing unnecessary abstractions. CX Codex +1 ★ 173repo stars domain-model Skill to actively shape your domain model: challenges terms against the glossary, stress-tests boundaries with scenarios, records glossary and decisions in CONTEXT.md and ADRs. CX Codex +1 ★ 173repo stars critical-reviewer The critical-reviewer subagent reviews recent code, documents, plans, or designs and returns prioritised findings. Use it for a fresh critical review before applying fixes yourself. CX Codex ★ 173repo stars

Project sponsors

Companies that keep this analytics open