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
npx skills add sammcj/agentic-coding --skill self-review -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/self-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/self-review/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill self-review -a codex2Manually: put the files in place
.agents/skills/self-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill self-review -a cursor2Manually: put the files in place
.cursor/skills/self-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sammcj/agentic-coding Skills/self-review/SKILL.md2Manually: put the files in place
.github/skills/self-review/SKILL.md1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill self-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/sammcj/agentic-coding --path Skills/self-reviewManually: put the files in place
.devin/skills/self-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.