Index of every page on this site: llms.txt
All skills
nielsmadan avatar

/code-review

@9fbe49f
Run it yourself

Clean up comments and mechanical loose ends, then review code with comprehensive and quick modes. Use when reviewing code changes, PRs, or specific files for quality, bugs, and best practices.

Use this Skill: https://skilld.dev/gh/nielsmadan/agentic-coding/code-review

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈51 tokens for metadata: the name and description. ≈11k when used: this file. ≈6.3k more on demand in 2 files.

Description uses 2.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈206 characters, or 2.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Code Review: $ARGUMENTS

Review the code related to: $ARGUMENTS

Review grading

Use only these finding priorities, in descending order:

  • Critical Issues (Must Fix): a verified path causes data loss, a security failure, a materially wrong operation, or makes a core workflow unusable without reasonable recovery.
  • Improvements (Should Fix): an ordinary supported workflow demonstrably fails or repeatedly imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
  • Suggestions (Nice to Have): a worthwhile improvement with small practical impact, including optional polish, local simplification, and rare recoverable edge cases.

Grade the demonstrated consequence, realistic reachability, and available recovery against project priorities. A category, missing convention, hypothetical future problem, or confidence that a claim is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep unverified claims in validation gaps, outside the graded finding count; distinguish suggestions from defects. For plans, trace the consequence if implemented and state the assumptions.

Use the short labels Must Fix, Should Fix, and Nice to Have in summaries and ledgers. Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings separate. When called by code-review, return its requested evidence and impact fields; the parent owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.

Reference files (load what the run needs)

File Load when
references/agents.md Step 3c in comprehensive mode — the per-agent briefs for Agents 1–10, plus how language / project / library-use reviews plug in.
references/scoring-and-output.md Steps 4 to 5 in comprehensive mode — verdict and effort scoring, likelihood/blast-radius triage, applying autofix items, and the output format.

Flag parsing, scope resolution, and the preflight cleanup (Steps 1–3b.6) need neither.

Usage

/code-review                          # Preflight cleanup + all 10 review aspects, default scope
/code-review --quick                  # One integrated review pass, no scorer-agent round
/code-review <target>                 # Preflight cleanup + all 10 aspects, scoped to target
/code-review --architecture           # Architecture only
/code-review --functional             # Functional principles only
/code-review --consistency            # Consistency with existing codebase patterns only
/code-review --correctness            # Logic, failure paths, and changing assumptions
/code-review --security --performance # Two aspects
/code-review --logic src/auth/        # One aspect, scoped to target
/code-review --typescript             # TypeScript-specific review only
/code-review --project                # Project's own review-project checks only
/code-review --library-use            # Library-usage review only (vs the repo's library-use reference)
/code-review --all                    # Whole repo
/code-review --changed                # Unstaged changes only
/code-review --staged                 # Staged changes only (errors if nothing staged)
/code-review --unpushed               # Files changed across all unpushed commits (errors if nothing unpushed)
/code-review --multi                  # All aspects + external advisors
/code-review --multi --architecture   # Architecture only + external advisors
/code-review --all --multi            # Whole repo + external opinions
/code-review --re                     # Review, then re-review only what the fixes changed

--re composes with comprehensive aspect selections, --quick, scope flags, or --multi. Invoked after an earlier review in the same conversation, it reviews only what changed since that review (Step 7) instead of starting over.

Review Modes

The default mode is comprehensive: run all selected perspectives independently, then independently score and triage their findings.

Every mode first runs review-tidy --fix over the resolved scope; it coordinates comment cleanup through review-comments and then mechanical cleanup, with formatting last. The cleanup is a preflight edit, not a review perspective: its results are reported separately and are never scored or promoted into Must Fix/Should Fix findings.

--quick runs one thorough integrated review at full reasoning effort, saving time through fewer agents and no separate scoring round. It keeps the normal scope resolution, project-guideline checks, severity output, fix prompt, and optional --re loop, but uses one integrated read-only reviewer and no separate scorer agents. It does not activate automatically from diff size: a tiny auth, migration, or concurrency change may still deserve the comprehensive mode.

--quick composes with a target, one scope flag, or --re. It cannot be combined with aspect flags or --multi; abort with --quick is a complete review preset; remove the aspect flags or --multi.

Aspect Selection

Aspect flags let you run a subset of the review agents instead of all 10. Flags are additive — pass as many as you want. Comment quality is absent from this list because its fix pass always runs before the selected review.

Flag Maps to
--correctness / --logic / --defensive Agent 1: Correctness Review (reads review-correctness)
--architecture Agent 2: Architecture Review (delegates to /review-architecture)
--security Agent 3a: Security Review (inline + delegate to /review-security)
--performance Agent 3b: Performance Review (inline + delegate to /review-perf)
--history Agent 4: Historical Context Review (inline)
--test Agent 5: Test Quality (delegates to /test --review)
--interface Agent 6: Interface Design (delegates to /review-interfaces)
--clean-code Agent 7: Clean Code (delegates to /review-cleancode)
--functional Agent 7b: Functional Review (delegates to /review-functional)
--consistency Agent 7c: Consistency Review (delegates to /review-consistency)

Further aspects are conditional add-ons — in the default (no-aspect-flag) run they are included automatically when they apply; with explicit aspect flags they run only if their own flag is passed (see Step 3b.5 for detection):

Flag Maps to
--cli / --react / --swiftui Agent 8b: Project-Shape Review — delegates to review-cli, review-react, or review-swiftui. Auto-included for console entry points, scoped React components, or scoped SwiftUI implementation. Orthogonal to language: it composes with the language review rather than replacing it.
--typescript / --swift / --python Agent 8: Language Review — delegates to the matching review-<language> skill (e.g. review-typescript, review-swift, review-python). Auto-included when the scoped files are of that language.
--project Agent 9: Project-Specific Review — delegates to the project's own review-project skill. Auto-included when that skill exists in the repo.
--library-use Agent 10: Library-Use Review — delegates to review-library-use (checks code against the repo's library-use conventions). Auto-included when the repo has a library-use reference.

Aspect rules:

  • Normalize --logic and --defensive to --correctness before selecting agents; any combination of these flags runs Agent 1 exactly once.
  • In comprehensive mode, no aspect flags → run all 10 core agents, plus any detected language and project-shape reviews, the project review, and the library-use review if present.
  • One or more aspect flags → run only those agents, skip the rest. The conditional add-ons run only if --typescript / --cli / --react / --swiftui / --project / --library-use (or another --<language>) is among the flags.
  • --quick is a complete preset and cannot be combined with aspect flags.
  • --multi composes with any aspect selection.
  • The non-flag portion of $ARGUMENTS is the review target (e.g. src/auth/).

Agents 8–10 are the plug-and-play extension layer (add a language by creating a review-<language> skill; add a shape by creating one like review-cli; a project adds its own review-project). Details in references/agents.md.

Scope Selection

Scope flags determine which files the reviewers inspect. The resolved scope is passed through to every review agent or delegated sub-skill.

Flag Meaning
--staged Review staged changes only (git diff --cached).
--unpushed Review files changed across unpushed commits only (git diff <last-pushed>..HEAD).
--changed Review unstaged changes only (git diff).
--all Review the whole repo (git ls-files).

Scope rules:

  • Exactly one scope flag may be passed. Multiple → error.
  • Default (no scope flag): behave as --staged if anything is staged; otherwise auto-fall back to --changed. Announce the resolved mode at the start of the run so the user isn't surprised. (--unpushed is never auto-selected — it's opt-in only.)
  • Explicit --staged with nothing staged: abort immediately with Nothing staged. Re-run with --all or --changed. (Explicit ≠ default — no silent fallback.)
  • Explicit --unpushed with nothing unpushed: abort immediately with Nothing unpushed. Re-run with --staged, --changed, or --all. If there is no remote/upstream (or the range walks back to the root commit) so the range can't be determined reliably, abort and ask the user to pick another scope. (Explicit ≠ default — no silent fallback.)
  • Target argument wins: if a non-flag target is provided (e.g. /code-review src/auth/), it overrides scope flags entirely. The target is passed to all sub-agents as-is.

Gotchas

  • Both modes silently drop findings that were not traced to a file:line in the code. Comprehensive mode uses independent scorers; quick mode trades that independent validation for a single reviewer's self-filter.
  • The verdict is categorical, not a 0–100 score. A model-written number is not a measurement, and a cutoff between anchors flips when the same claim is scored twice.
  • The verdict means "is this claim true", never "does it matter". A traced duplication or leaky interface passes as surely as a traced crash and lands in Suggestions or Should Fix by impact. Failing true design findings because they are "not a bug" silently deletes most clean-code and interface output. Effort only orders findings within a section; it never drops one.
  • In comprehensive mode, Step 4.5's triage never drops anything silently — every issue routed out of the main severity sections appears in the Improbable / Not Worth Handling appendix with its file:line and a one-line reason. Quick mode omits low/medium-impact improbable findings entirely to stay concise.
  • With --staged, the preflight edits the working-tree copies and does not stage them. Announce that the cleanup must be staged separately; never run git add implicitly.
  • Reviewers run in parallel on one checkout. A reviewer that edits a file, even briefly to mutation-test, makes the others report its edit as a real bug. Every reviewer is read-only; experiments run in a disposable copy (see references/agents.md).

Step 1: Locate and Read Project Guidelines

First, find and read any CLAUDE.md files in the repository root and relevant directories to understand project-specific conventions and rules.

Step 2: Identify Relevant Code

Search for and identify all files related to "$ARGUMENTS". Use Glob and Grep to find:

  • Direct implementations
  • Related tests
  • Usages/consumers of this code

Step 3: Resolve Scope and Run the Review

3a. Parse flags

If the removed --comments aspect flag is passed, abort with Comment cleanup now runs automatically before every code review. Use review-comments directly for a standalone comment report.

Strip aspect flags (--correctness, --logic, --architecture, --security, --performance, --history, --test, --interface, --clean-code, --functional, --consistency, --defensive, --typescript, --project, --library-use), scope flags (--staged, --unpushed, --all, --changed), --quick, --multi, and --re from $ARGUMENTS. The remainder is the review target.

If --quick appears with any aspect flag or with --multi, abort with --quick is a complete review preset; remove the aspect flags or --multi. It may compose with a target, one scope flag, and --re.

In comprehensive mode, if any aspect flags are present, launch ONLY the corresponding agents (including the conditional add-ons only when a --<language>/--cli/--react/--swiftui/--project/--library-use flag is passed). Otherwise launch all 10 core agents plus whatever Step 3b.5 detects. In quick mode, follow the single-reviewer branch in Step 3c.

3b. Resolve scope

If a non-flag target was provided, skip this section — pass the target through to every agent as-is.

Otherwise, resolve the scope:

  1. If more than one scope flag was passed → error: Pass only one of --staged, --unpushed, --all, --changed.
  2. If --staged was passed explicitly:
    • Run git diff --cached --name-only. If empty → abort: Nothing staged. Re-run with --all or --changed.
    • Resolved scope: staged.
  3. If --unpushed was passed explicitly:
    • Resolve the range: git rev-list HEAD --not --remotes (oldest unpushed commit's parent → HEAD). If empty → abort: Nothing unpushed. Re-run with --staged, --changed, or --all. If there is no remote/upstream, or the range walks back to the root commit, abort and ask the user to pick another scope.
    • Resolved scope: unpushed.
  4. If --changed was passed: resolved scope is changed.
  5. If --all was passed: resolved scope is all.
  6. If no scope flag was passed (default):
    • Run git diff --cached --name-only. If non-empty → resolved scope is staged.
    • Otherwise → resolved scope is changed.
    • Announce the resolution: No scope flag — defaulting to --staged or No scope flag and nothing staged — defaulting to --changed.

Compute the file list once based on resolved scope:

  • staged → git diff --cached --name-only
  • unpushed → git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEAD
  • changed → git diff --name-only
  • all → git ls-files

This file list is passed to inline agents and is also used to build the target argument for sub-skills that don't natively support --changed (see 3c).

3b.5. Detect language & project reviews

Determine which conditional add-on reviews apply. In comprehensive mode these become additional agents. In quick mode their skill/reference text becomes guidance for the single integrated reviewer. Skip this entirely if explicit aspect flags were passed and none of them is --typescript/--cli/--react/--swiftui/--project/--library-use/another --<language> — in that case the user asked for a specific subset and add-ons don't run.

Language detection registry. For each language below, it applies if the resolved file list matches its extensions, or (for the all scope / when the file list is empty) the repo root has its marker file. If it applies and a review-<language> skill is installed, include that agent in comprehensive mode or record its SKILL.md as guidance for quick mode.

Language File extensions Repo marker Skill
TypeScript .ts .tsx .mts .cts tsconfig.json review-typescript
Swift .swift Package.swift, *.xcodeproj, *.xcworkspace review-swift
Python .py .pyi pyproject.toml, setup.py review-python
Rust .rs Cargo.toml review-rust

(To add a language: create a review-<language> skill and add a row here.)

Project-shape detection. Shapes are orthogonal to language — a CLI is reviewed the same way whether it is Python or Rust. If the shape applies and the matching skill is installed, include that agent in comprehensive mode or record its SKILL.md as guidance for quick mode. If the skill is not installed, skip silently.

Shape Detected by Skill
CLI [project.scripts] / [project.entry-points."console_scripts"] in pyproject.toml, [[bin]] or src/main.rs in a Cargo project, bin in package.json, or a main-package cobra/urfave import in Go review-cli
React react in package.json dependencies, and scoped .jsx/.tsx files or files that call hooks (at all scope, the dependency alone) review-react
SwiftUI Scoped SwiftUI view, scene, modifier, or control implementation, or UI resources consumed by it; at all scope, that implementation anywhere in the project. An import or a Swift project marker alone is insufficient review-swiftui

In default reviews, when Swift and SwiftUI both apply, include both reviewers. Explicit aspect flags still select only the requested reviewers. review-swift owns state, identity, lifetime, dependencies, concurrency, and rendering cost; review-swiftui owns presentation and interaction. Pass this boundary to both and deduplicate by the underlying cause.

Project review detection. If the repo defines its own project review skill at .claude/skills/review-project/SKILL.md or .agents/skills/review-project/SKILL.md, include the project review agent in comprehensive mode or record its SKILL.md as guidance for quick mode. If neither exists, skip silently.

Library-use review detection. If the repo has a library-use reference at .claude/skills/library-use/SKILL.md or .agents/skills/library-use/SKILL.md, include the review-library-use agent in comprehensive mode or record the reference as guidance for quick mode. If neither exists, skip silently (suggesting library-docs once is fine, but don't block the review).

Check both paths — .claude/skills/ is where Claude Code puts project skills; .agents/skills/ is where the other harnesses discover them. In some projects the latter is a symlink to the former, so either check finds it; others may only have .agents/skills/.

Announce what got auto-included. In comprehensive mode, use messages such as Detected TypeScript — adding review-typescript or Detected a CLI entry point — adding review-cli. In quick mode, say Detected TypeScript — applying review-typescript guidance in the quick review (and likewise for project and library-use guidance).

3b.6. Preflight cleanup

::: claude codex opencode Before launching any review agent, invoke review-tidy --fix exactly once against the resolved scope. It owns the review-comments invocation and runs formatting after all cleanup edits; do not invoke comment cleanup separately. ::: ::: pi Before launching any review agent, run review-tidy --fix exactly once against the resolved scope — in this session, not as a subagent. pi has no Skill tool, so read its SKILL.md and apply it directly, including its nested review-comments instructions. Do not invoke comment cleanup separately. Cleanup edits files, which the read-only reviewer agent cannot do; agent: names an agent, never a skill. :::

Resolved scope Arguments for review-tidy
staged --staged --fix
unpushed --unpushed --fix
changed --changed --fix
all --all --fix
local path target <target> --fix
other target, such as a PR <resolved local source file list> --fix

Treat its combined output as a preflight cleanup summary, not as review findings. Report how many comments were removed or rewritten and what mechanical fixes were applied, and list the deferred items, but do not send those items through scoring or severity triage. Continue immediately when they find nothing.

If a non-file target has no writable local source files, skip the cleanup and state that it requires a local checkout; do not turn that limitation into a review finding.

Keep the file list resolved in Step 3b even if cleanup edits change git status. Review the current contents of those same files, using the originally resolved diff or target to identify the intended change. With staged scope, explicitly say the cleanup edits are unstaged and must be staged separately; do not mutate the index.

3c. Run the selected mode

Quick mode (--quick)

::: claude codex opencode Do not load references/agents.md. Launch exactly one read-only review agent and give it the resolved scope or target. Use the same model and reasoning effort as a comprehensive reviewer; do not select a faster profile or lower effort for quick mode. It must not delegate to sub-skills or dispatch more agents. ::: ::: pi Do not load references/agents.md. Launch exactly one child via subagent using the builtin reviewer agent, and give it the brief below plus the resolved file list. reviewer grants only read, grep, find, ls — no bash, no edit, no nested dispatch — so it is read-only by construction. Because it has no bash it cannot resolve a scope itself: pass the concrete file list, not --staged. :::

For every harness, retain full review reasoning effort. Give the reviewer this integrated brief:

  • Read the applicable AGENTS.md / CLAUDE.md files and the scoped diff or files. For each changed behavior, trace the path from its callers through the implementation and dependencies to its observable result, including failure paths. Read surrounding code and related tests to check the contracts at each boundary; do not stop at the diff hunks. For a whole-file or whole-repo target, trace the main behaviors in scope.
  • Read review-correctness and apply both passes directly without launching another reviewer. Review correctness, edge cases, error handling, regressions, catch-all else/default branches that would silently absorb a newly added enum or API value, missing or weak tests, security red flags, and interface compatibility. Check performance hazards supported by the traced paths. Also check design and maintainability: module responsibilities, coupling, duplication, interface clarity, hidden shared state, and mutation of caller-owned data. Check consistency: compare each added construct with two or more existing siblings of the same kind and flag divergences in naming, placement, mechanism (errors, logging, config, existing helpers) or registration, citing the precedent file:lines; documented project rules and newer patterns win over older precedent. Tie each concern to concrete code and its consequences.
  • If Step 3b.5 detected language, project-shape, project, or library-use guidance, read those matching SKILL.md files as review references and apply their checks directly. Do not invoke them as skills.
  • Before accepting or dismissing a suspected issue, trace a concrete triggering input or state, inspect callers and excluding guards, and check whether tests exercise the behavior and assert the relevant result. Use targeted checks when available; run any experiment that writes files in a disposable copy. If the reviewer lacks execution tools, request a specific check from the parent, which must resolve it before final filtering or report the remaining uncertainty.
  • Return only actionable findings supported by a concrete code path. For each finding, include severity (Must Fix, Should Fix, or Nice to Have, using Review grading above), file:line, what is wrong, why it matters, a concise fix, the file:line where you traced it, effort (S: one file, local, no interface or test changes; M: several files or new or changed tests; L: a public interface, a migration, or callers in other modules), likelihood (routine, plausible, rare, or theoretical), and blast radius (low, medium, or high). For rare or theoretical, name the reachability reason and cite any excluding guard.
  • After verification, omit findings you did not trace through every link in the code and omit rare/theoretical findings with low or medium blast radius. Keep rare high-blast-radius findings and tag them with the short reachability reason. Tracing decides only whether the claim is true; a true finding that matters little is Nice to Have, not dropped.
  • Tag a finding autofix when its fix cannot change production behaviour, any change in what a test executes is proven by running tests, and a wrong call would be visible in the diff and cheap to revert. It must not need new prose, a design choice, or an edit to exported or public code. Examples: a doc line naming a symbol or flag the diff renamed, an import the diff orphaned, a test name that no longer matches, an unexported identifier renamed to the codebase's naming pattern. When the fix changes what a test executes, append verify: suite if test code moves unchanged, or verify: mutation if it substitutes different test code.
  • Do not edit the shared checkout, even temporarily; keep any experiment writes in a disposable copy.
  • Always return a short coverage statement naming the behaviors traced, callers/dependencies and tests examined, and checks actually run. State any unexamined scope, checks not run, and material unresolved uncertainties; distinguish these from confirmed findings. Do not infer safety from missing evidence.
  • Return No actionable findings. if nothing survives, followed by the coverage statement and any limitations.

After the agent returns, resolve any requested verification checks before final filtering, without launching more reviewers or scorers. Apply its autofix findings yourself after checking each still meets that test, and list them under Applied automatically; a finding that fails the test goes to its severity section instead. Run a verify: item's check first, in a disposable copy with the fix applied: for verify: suite the full test suite must pass under timeout; for verify: mutation the affected tests must pass, then fail once you break the behaviour they assert in the code under test (grep to confirm the break landed). An item whose check fails or cannot run goes to its severity section. Deduplicate the rest and render the surviving items under Critical Issues (Must Fix), Improvements (Should Fix), and Suggestions (Nice to Have), omitting empty sections. Within a section, list S findings first, then M, then L, each prefixed with its effort tag ([S], [M], [L]). Explain what is wrong, why it matters, and how to fix it. Include the coverage statement and material limitations even when there are no findings. Do not show likelihood or blast-radius metadata and do not launch scorer agents. Then continue to Step 5.5.

Comprehensive mode

Load references/agents.md — it carries the brief for each of Agents 1–10.

Launch the selected review perspectives in parallel, queuing successive batches when runtime capacity requires it.

One agent per perspective. Never pair two aspects in one brief to save agents, not even small ones. A capacity limit queues reviewers; it never merges them. A past run paired functional with consistency, and the consistency half came back covering only what its brief listed.

Brief with the scope, not a checklist of where to look. Give each reviewer the resolved scope or file list, the project facts it cannot cheaply discover, and its aspect brief from references/agents.md. Do not list the units, files or precedents it should examine: a reviewer handed "focus on X, Y, Z" reviews X, Y and Z, and the rest of the diff goes unreviewed for that aspect. If a fact about one file matters, state it as context and say the whole file list remains in scope.

::: claude Claude Code caps concurrent subagents at CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Launch up to that many at once, then launch each remaining reviewer as soon as one returns. A launch refused with Concurrent subagent limit reached never ran: despite the message's "Do not retry", queue it and launch it when a slot frees, and never drop the aspect. The same limit applies to the scorer round. :::

::: claude codex opencode Launch workers that return findings without editing files, including temporary edits: a reviewer that mutates a file to test something and restores it still corrupts what the parallel reviewers read. Include the shared rules from references/agents.md in every brief. Disable delegation tools for ordinary reviewers where supported; read-only access alone does not prevent delegation. If a reviewer coordinates verification, name the checks, bound the descendants, and define when it should stop. Workers can read the relevant sub-skill directly when their harness has no Skill tool. ::: ::: pi Launch them read-only, as one subagent workflow. pi fans out through a workflowScript, not through repeated tool calls — one subagent call carrying runs.all([...]), one entry per perspective, every entry on the builtin reviewer agent: ::: ::: pi

{ workflowScript: `
  const results = await runs.all([
    { key: "correctness",    agent: "reviewer", task: "<brief for Agent 1 + resolved file list>" },
    { key: "security", agent: "reviewer", task: "<brief for Agent 3 + resolved file list>" }
  ]);
  return results.map(r => r.output);
` }

::: ::: pi reviewer grants only read, grep, find, ls, so it cannot edit the code it reviews and cannot dispatch further. Use it for the scorer round in Steps 4–5 too. Two pi-specific rules:

  • The agent field takes a pi agent name, never a skill name. The builtins are scout, researcher, worker, reviewer, oracle, delegate; custom agents live in ~/.pi/agent/agents/. { agent: "review-security" } fails the whole workflow with Unknown agent: review-security. Every harness works this way — identity comes from the agent registry, the task comes from the prompt — so this is not a pi quirk.
  • Children reach a sub-skill as a file, not as a tool call. pi has no Skill tool. reviewer runs with inheritSkills: true (set in loadout/settings/pi.json under subagents.agentOverrides), so it sees the skills catalog and loads a SKILL.md with read when a brief names one. :::

Each agent should output a list of issues. For each issue, include: what the problem is, where it is (file + line), and why it matters, and tag safe fixes autofix as defined in references/agents.md. Do NOT assign verdicts or effort — scoring happens in a separate pass.

::: claude codex opencode Sub-agent invocation pattern. When a sub-agent delegates to a sub-skill, pass the resolved scope through directly: ::: ::: pi Sub-agent invocation pattern. Name the sub-skill in the child's task and let it read that SKILL.md itself — delegation works, it just resolves through the filesystem rather than a Skill tool. What does not carry over is the scope flag: reviewer has no bash, so it cannot turn --staged into a file list. Pass the concrete list resolved in Step 3b instead. The table below is therefore read as scope→file-list on pi, not scope→flag. ::: ::: claude codex opencode

Resolved scope Argument passed to sub-skill
staged --staged
unpushed --unpushed
changed --changed
all --all
target given the target itself (e.g. src/auth/)

All delegated review sub-skills (review-architecture, review-security, review-perf, review-interfaces, review-cleancode, review-functional, review-consistency, review-correctness, review-typescript, test --review) accept --staged | --unpushed | --changed | --all. No special-casing needed. The project's review-project skill is expected to accept the same scope flags — if it doesn't, pass it the target/file list instead.

::: Inline agents (no delegation) work directly against the file list computed in step 3b.

Step 3.5: External Advisor Reviews (--multi only)

If --multi flag is present in $ARGUMENTS, also get external opinions:

::: claude codex opencode Use the Skill tool to invoke second-opinion --quick, which queries every external advisor it has configured, in parallel. (The advisor roster lives in the second-opinion skill — don't enumerate it here.) Phrase the prompt according to the resolved scope from step 3b: ::: ::: pi pi has no Skill tool. Read second-opinion/SKILL.md from the skills directory and run its advisor commands yourself with bash, backgrounding them so they run in parallel. Do not dispatch second-opinion as a subagent — it is a skill name, not an agent name. Phrase the prompt according to the resolved scope from step 3b: :::

  • staged → "Review the staged changes (git diff --cached) in this repository."
  • unpushed → "Review the changes across all unpushed commits (git diff against the last pushed commit) in this repository."
  • changed → "Review the unstaged changes (git diff) in this repository."
  • all → "Review the codebase in this repository as a whole."
  • target given → "Review the following target in this repository: <target>."

Then append: "Provide a focused code review in 300 words or less covering: potential bugs or edge cases, security concerns, performance issues, and architecture/pattern violations."

IMPORTANT: Do NOT proceed to Step 4 until the second-opinion results have been fully received. Wait for all background commands to complete and collect their output before continuing. This prevents completion notifications from appearing after the review summary. If an advisor is missing or errors out, continue with whichever responded — don't drop the others.

Steps 4 to 5: Score, Triage, Autofix, Format (comprehensive mode only)

Skip these steps in quick mode; Step 3c already produced the filtered, formatted review. In comprehensive mode, load references/scoring-and-output.md and follow it. In short: score every issue with independent parallel scorers using the exact prompt there (only traced passes, and the verdict means only "is this true"), have those same scorers return impact, effort, likelihood and blast radius so improbable findings route to an appendix instead of the work list, apply the autofix items, then render the severity sections.

When that reference is done, come back here and do Steps 5.5 and 6 — the rendered output is not the end of the run.

Step 5.5: Snapshot the reviewed state

In both modes, after the output is rendered and any autofix items are applied, record what was reviewed so a re-review can find what changed since. In the session's scratch directory:

  • copy every existing file in the Step 3b file list to cr-snapshot/<round>/, keeping its repo-relative path;
  • save git status --porcelain there as status.txt;
  • save the findings list as findings.md: each finding's aspect, file:line, one-line claim and section. Step 6 adds each one's disposition (fixed, declined, or appendix) once known.

Do not use git stash, commits or any other git write for this. The snapshot is local scratch, not history.

Step 6: Offer to Fix

This step is mandatory. Rendering the review output is not the end of the workflow — do not end the turn after printing the findings. If there is at least one Must Fix or Should Fix finding, you MUST call the AskUserQuestion tool so the user picks a fix scope by selection instead of typing one out.

Build the options list from the severity tiers that actually have findings, most-inclusive first:

Option Fixes Include when
"Fix everything" Must Fix + Improvements + Suggestions there are Suggestions (Nice to Have) findings alongside at least one Must Fix or Should Fix finding
"Address Must Fix + Should Fix" Must Fix + Improvements there are both Must Fix and Should Fix findings
"Address Must Fix only" Must Fix there are Must Fix findings
"Fix Should Fix" Improvements there are Should Fix findings but no Must Fix findings
"Don't fix anything" nothing always — last option

AskUserQuestion takes at most 4 options, so when all tiers are populated drop the narrowest fix option (Address Must Fix only) rather than Don't fix anything — the user can still ask for a narrower scope in free text.

Skip this step entirely (no prompt) only when there are no Must Fix and no Should Fix findings — a run that surfaced nothing but suggestions has nothing worth gating on.

Build the options only from the Critical Issues, Improvements, and Suggestions sections. Applied automatically items are already done and are never offered. Never include Improbable / Not Worth Handling items — not even under "Fix everything". Step 4.5 already judged them not worth doing, and offering to fix them reintroduces exactly the noise the appendix exists to remove.

When the user selects a fix option, apply the fixes for exactly the chosen severity tier(s) — no more, no less. Record each finding's disposition in the snapshot's findings.md.

Code written to fix a finding has not been reviewed. Without --re, end the run with a Not yet reviewed line naming the files the fixes changed, and suggest /code-review --re, which reviews only those changes.

Step 7: Re-Review the Fixes (--re)

A re-review checks only what changed since the last snapshot: the fixes, plus anything else edited since. It is not a second full review, and it does not re-run the preflight cleanup on unchanged files.

It runs in two cases:

  • --re was passed and Step 6 applied fixes: continue straight into it.
  • /code-review --re is invoked and an earlier review in this conversation left a Step 5.5 snapshot: skip Steps 1–6 and start here from the latest snapshot. This covers fixes applied after the review ended, by the user or by a calling skill. With no snapshot in the conversation, run a normal review that loops as in the first case.

Announce it, e.g. Re-reviewing the 4 files changed since the review (--re).

7a. Compute the delta

Compare each snapshot file with its current content (git diff --no-index), and compare git status --porcelain with status.txt to find files created, deleted or renamed since. The delta is those hunks and files. If it is empty, say Nothing changed since the review. and stop.

If findings.md has no dispositions because the fixes were made outside Step 6, mark each finding whose file:line falls in the delta as fixed and the rest as declined.

7b. Pick the aspects

Start from the aspect of every finding marked fixed, so each fix is checked against the finding it addressed. Then add aspects for what the delta contains:

The delta contains Add
Changed conditions, control flow, data handling, async or error paths correctness
New or renamed identifiers, files, components, props, exports, keys or strings consistency, interface
New or changed tests, or production changes with no test change test
Changed exported signatures, or code moved between modules architecture, interface
Auth, URLs, input parsing, secrets, shell or SQL security
Loops, queries, render paths or caches performance
Files a language, shape, project or library-use reviewer covered in the original run that reviewer

If the original run used aspect flags, choose only from those aspects, plus correctness when production code changed. History, and functional unless the delta adds state or mutation, are rarely worth a re-review.

7c. Pick the depth

Use the delta's size, not the original run's mode:

Delta How
Renames, moves, strings, comments or config only, under ~30 changed lines, no logic No sub-agents. Check it yourself: confirm each fixed finding is resolved, grep for references to anything renamed or removed (string literals included), run the affected tests under timeout.
Under ~200 changed lines across at most ~6 files, or the original run was --quick One reviewer, using the quick-mode brief from Step 3c with the delta as its scope and the aspects from 7b as its checklist. No scorer round.
Larger Comprehensive mode, limited to the aspects from 7b, one agent each, scored as usual. Re-run external advisors only here, and only if the original run used --multi.

7d. Brief and report

Every re-review brief (or your own check) gets:

  • the delta as the scope, with the original diff and the full files as context only;
  • each fixed finding, to confirm resolved or report as not resolved;
  • each declined or appendix finding, marked as already decided: not to be raised again;
  • the instruction to report only issues in the delta or caused by it.

Render a Re-review of fixes section listing each fixed finding as resolved or not resolved, then any new findings in the usual severity sections. Take a new Step 5.5 snapshot, then run Step 6 as normal. The loop ends when a re-review has no Must Fix or Should Fix findings, or the user picks "Don't fix anything".

Examples

Clean up, then review the default scope with all 10 agents:

/code-review

Runs review-tidy --fix (including comment cleanup), then 10 parallel review agents (correctness, architecture, security, performance, historical context, test quality, interface design, clean code, functional principles, consistency with existing patterns) against staged changes (or unstaged changes if nothing is staged). The cleanup is summarized separately; review findings are prioritized by severity.

Quick review of a routine small change:

/code-review --quick

Runs one integrated read-only reviewer against staged changes (or unstaged changes if nothing is staged). It uses full reasoning effort, traces behavior through callers, dependencies, and tests, and checks design alongside correctness. It applies detected language, project, and library-use guidance directly, verifies suspected issues before filtering, and reports coverage and unresolved uncertainties. It skips the independent scorer-agent round.

Focused single-aspect review:

/code-review --architecture

Runs only the architecture & patterns agent. Use this when you already know which concern you care about and don't want to wait on the other 9 core agents or sift through their output. Flags are additive — combine them (e.g. --security --performance) to run a handful of aspects without running them all.

Whole-repo review:

/code-review --all

Runs the preflight cleanup and all 10 agents against every file in the repo (git ls-files). Use this for a fresh audit of an unfamiliar project, before a major release, or when nothing in the working tree is changed. Composes with aspect flags and --multi, e.g. /code-review --all --architecture --multi.

Cross-model consensus review:

/code-review --multi

Runs the same 10 review agents plus external reviews from every advisor second-opinion has configured, after the preflight cleanup. The output includes a cross-model agreement section highlighting issues where the internal agents and external advisors converge, giving higher confidence to consensus findings. --multi composes with aspect and scope flags, e.g. /code-review --multi --architecture or /code-review --all --multi.

Review, fix, then re-review automatically:

/code-review --re

Runs the review, offers the fix prompt (Step 6), and once fixes are applied, re-reviews only what they changed. It confirms each fixed finding is resolved and checks the new code with the aspects that change touches. A rename-only fix gets no sub-agents at all, and a small fix gets one reviewer. The loop continues until a re-review comes back with no Must Fix/Should Fix findings or the user declines to fix. Run /code-review --re later in the same conversation to re-review fixes made after the review ended.

Troubleshooting

Too many changed files for agents to handle

Solution: Narrow the review scope by targeting a specific directory or file pattern (e.g., /code-review src/auth/) instead of the entire changeset, or break the PR into smaller, focused reviews.

Agent returns shallow or redundant findings

Solution: Ensure the review target is specific enough to give agents meaningful context; vague targets like "everything" produce generic results. Re-run with a focused target and verify that CLAUDE.md contains project-specific patterns the agents can check against.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings7mo4 checks · Risk MEDIUM
  • Gen Agent Trust Hub7mo

    The skill facilitates a complex code review workflow but contains patterns that could lead to command injection and the silent suppression of security findings. It processes untrusted repository code without sufficient isolation, making it vulnerable to indirect prompt injection, and transmits code context to external AI models when specific flags are used.

  • Socket7mo

    1 alert: gptAnomaly

  • Snyk7mo

    Risk: LOW · No issues

  • Runlayer8mo

    2 files scanned · No issues

Signed by skilld at 9fbe49f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 5 days ago
effort
high
Other metadata
argument-hint
[target] [--quick] [--correctness] [--logic] [--architecture] [--security] [--performance] [--history] [--test] [--interface] [--clean-code] [--functional] [--consistency] [--defensive] [--typescript] [--project] [--library-use] [--staged] [--unpushed] [--all] [--changed] [--multi] [--re]

README badge

README badge for nielsmadan/agentic-coding/code-review