This skill should be used when the user wants to review code, audit a diff, get a second opinion on changes, or run an adversarial review of files in the current working tree. Common triggers include "review this code", "audit this diff", "find issues in", "second opinion on this", "harsh review of", "adversarial review", and "security review of". Picks one or more reviewer personas (adversarial, security, architecture, performance). Reviews local files, `git diff`, or `git diff --staged` only — does not fetch external content. Runs in one of four modes: single-agent (one persona in the current agent), cross-model handoff (independent second opinion via another local AI CLI, with secret-shield preflight + prompt-shield wrap), multi-bg-agent (one persona per parallel background subagent), or agent-team (Claude Code Teams or equivalent on supporting agents). Skip when the user wants formatting fixes (use a linter) or refactoring patterns (use ts-best-practices or ts-best-practices-functional).
This skill should be used when the user wants to review code, audit a diff, get a second opinion on changes, or run an adversarial review of files in the current working tree. Common triggers include "review this code", "audit this diff", "find issues in", "second opinion on this", "harsh review of", "adversarial review", and "security review of". Picks one or more reviewer personas (adversarial, security, architecture, performance). Reviews local files, `git diff`, or `git diff --staged` only — does not fetch external content. Runs in one of four modes: single-agent (one persona in the current agent), cross-model handoff (independent second opinion via another local AI CLI, with secret-shield preflight + prompt-shield wrap), multi-bg-agent (one persona per parallel background subagent), or agent-team (Claude Code Teams or equivalent on supporting agents). Skip when the user wants formatting fixes (use a linter) or refactoring patterns (use ts-best-practices or ts-best-practices-functional).
argument-hint
[<file|dir|diff|staged>]
user-invocable
true
model-invocable
true
code-reviewer
Reviews code in the current working tree through a chosen persona. Reference docs in references/ are loaded on demand — load only the persona and mode refs the user picks.
When to use
Verbatim trigger phrases:
"review this code"
"audit this diff"
"find issues in this"
"second opinion on this"
"harsh review of"
"adversarial review"
"security review of"
When NOT to use
Formatting / style fixes → use a linter (oxlint, eslint, prettier, etc.)
Refactoring patterns → use ts-best-practices or ts-best-practices-functional
Reviewing pull requests from external repos / contributors → out of scope; the skill only reviews local files. If you need PR review, run it inside a trusted CI environment after vetting the source.
Writing new code from scratch → this skill reviews existing code
Inputs
$ARGUMENTS — one of:
File or directory path (src/foo.ts, src/)
diff — review git diff
staged — review git diff --staged
Empty — ask the user what to review
Workflow
1. Determine scope
Resolve $ARGUMENTS to a concrete set of files + diff:
Input
Action
File/dir path
Read the file(s) directly
diff
git diff
staged
git diff --staged
empty
Ask: "What should I review? (file path / diff / staged)"
2. Choose persona(s) — load on demand
Ask the user which review angle. In Claude Code use AskUserQuestion with multiSelect: true; in other agents use the equivalent multi-select prompt. Always present these exact 5 options (4 personas + an "All" convenience option):
All — run every persona; loads all four refs and locks step 3 to a parallel mode
If the user picks "All", treat it as [adversarial, security, architecture, performance]. Don't omit the "All" option even when the user already named a persona in their request — they may want to broaden it.
Only load the references the user actually picked. Don't pre-load all four unless they chose "All" — that's the whole point of progressive disclosure.
If the user picked more than one persona, prefer a parallel mode in step 3 (multi-bg-agent or agent-team). Sequential in-process across multiple personas is slow and pollutes context.
3. Choose mode
Four modes, ordered by review quality (best → worst). The reviewing agent should default to the highest-quality option that's actually available on the host:
Mode
Quality
Best for
Reference
Cross-model handoff
★★★ Recommended
Any review where bias / blind spots matter. A different model on the same machine catches what the current one missed — especially for adversarial / security / architecture lenses. Pair with secret-shield.
Last resort — same agent, same context, same model. Most biased option. Only use if no other CLI is available and parallel spawn isn't supported.
(no extra ref)
Why cross-model is the recommendation: code review is an independence problem. A second model — even a smaller one — has different training data, different priors, and different blind spots, so it surfaces issues the first model rationalizes past. Same-model parallel agents (bg-agent / team) reduce context-pollution but share the model's biases. In-process review compounds both problems: same biases, same context.
First, detect available CLIs — this drives the recommendation:
The script outputs JSON of available AI CLIs on $PATH (codex, gemini, aider, etc.).
Recommendation logic, applied in order:
At least one non-current-agent CLI available → recommend cross-model handoff. Strong default — propose it even when the user didn't explicitly say "second opinion". For multi-persona, you can either pick one CLI and run all personas through it sequentially, or (if multiple CLIs are available) split personas across CLIs.
No other CLI AND ≥2 personas → recommend a parallel same-model mode. Use agent team on hosts with a native team primitive (Claude Code), otherwise multi-bg-agent.
No other CLI AND 1 persona → fall back to in-process. Tell the user explicitly: "no second model on this machine — running same-model in-process; quality is lower".
Never silently default to in-process. If you reach in-process, it's because cross-model wasn't available and parallel modes don't apply. Say so.
Ask the user (AskUserQuestion or equivalent) to confirm the recommended mode before running. Load only the reference(s) for the chosen mode.
4. Run the review
In-process: apply the loaded persona reference as the guiding lens. Read the code in scope, produce findings. If multiple personas were selected and the user accepted in-process anyway, run them one at a time and merge findings using the rules in references/parallel-execution.md §"Step 4 — Merge".
Cross-model: see references/cross-model-handoff.md — uses the bundled invoke-cli.mjs with secret-shield preflight + prompt-shield wrap. Capture the child CLI's stdout verbatim as the review.
Multi-bg-agent / Agent team: see references/parallel-execution.md — fan out one persona per agent with shared scope, collect each agent's findings, merge into one three-tier report with persona tags.
Group findings by severity (error / warn / info — matches our skill-tools tiers)
Use file:line references so the user can click to source
Include a one-line summary at the top
Reference, don't reproduce — describe the issue and point to file:line; do not paste code or diff lines into output (the user already has the file open)
Examples
"review the auth refactor in src/auth/" with adversarial persona
1. Scope: read every file under `src/auth/`.
2. Persona: present 5 options (Adversarial, Security, Architecture, Performance, All); user picks Adversarial. Load `references/personas/adversarial.md`.
3. Mode: run `detect-clis.mjs --available-only` — `codex` is on `$PATH`. Recommend **cross-model via codex** (less biased than running adversarial in the same model). User accepts; load `references/cross-model-handoff.md`.
4. Invoke: `git diff src/auth/ | node scripts/invoke-cli.mjs codex --instructions references/personas/adversarial.md --untrusted-content - --secret-mode redact --timeout 120`. Capture stdout verbatim.
5. Present the review with a header noting the model used (`# Code review (via OpenAI Codex 0.128.0)`).
"all reviews on src/auth/" — multi-persona, no other CLI on this machine
1. Scope: read every file under `src/auth/`.
2. Personas: user picked "All" (option 5) — expand to `[adversarial, security, architecture, performance]`, load all four persona refs.
3. Mode: run `detect-clis.mjs --available-only` — empty. No cross-model option. Host is Claude Code, so recommend **agent team** (same-model parallel; baseline quality). User accepts; load `references/parallel-execution.md`.
4. Resolve scope once, then spawn 4 agents (one per persona) in a single message with `team_name` set. Each agent gets the persona body + scope + output-format spec inlined. Wait for all four. Merge findings: dedupe by `(file, line, normalized-message)`, regroup by severity, tag with persona.
5. Output one combined three-tier report headed `# Code review — agent-team (4 personas)`.
"security review of the staged changes via codex" — cross-model second opinion
1. Scope: `git diff --staged`.
2. Persona: load `references/personas/security.md`.
3. Mode: cross-model (user asked for codex). Run `node scripts/detect-clis.mjs --available-only`. Pick `codex`.
4. Invoke: pipe the diff via stdin and point `--instructions` at the persona ref already on disk. `git diff --staged | node scripts/invoke-cli.mjs codex --instructions references/personas/security.md --untrusted-content - --secret-mode redact --timeout 120`. Capture stdout.
5. Present the verbatim output with a header noting the model used.
Loaded only `references/personas/adversarial.md` because the user picked
"adversarial". Other persona refs stayed on disk. After CLI detection
landed on cross-model, loaded `cross-model-handoff.md` only;
`parallel-execution.md` stayed unloaded.
Pre-loaded all four persona references, `cross-model-handoff.md`, and
`parallel-execution.md` "just in case". Wastes context budget on every
dispatch.
Defaulted to in-process for a single-persona review without first
running `detect-clis.mjs`. Cross-model is the recommended mode whenever
another CLI is available — silently picking in-process gives a more
biased review.
The bad examples violate the skill's design: progressive disclosure (load only what's needed) and independence-by-default (prefer a different model when one is on the machine).
Security
Cross-model mode forwards local file / diff content to a third-party AI CLI on the same machine. That crosses a trust boundary even though the source content is local: code under review can contain embedded secrets (API keys, tokens) and prompt-injection-style markers (intentionally or accidentally). Two complementary mitigations are built into scripts/invoke-cli.mjs and fire when the agent uses the --instructions <file> --untrusted-content <file> form.
Credential exfiltration: the script runs a regex-based secret scan on the content before composing the prompt. Default --secret-mode scan refuses to forward when any known secret format (AWS, GitHub, OpenAI, Anthropic, Slack, Stripe, Google API, JWT, PEM private keys) is detected. --secret-mode redact substitutes [REDACTED-{type}-{n}] placeholders. --secret-mode allow skips the check (use only when you've already audited the content). Source: scripts/secret-shield/.
Prompt injection: the script generates a fresh 12-hex salt per invocation and wraps the content in <untrusted-{{salt}}>...</untrusted-{{salt}}> with an anti-injection preamble before piping to the child CLI. Attacker-embedded closing tags (whether intentional or accidental) can't escape the wrap because they can't predict the salt. Source: scripts/prompt-shield/.
In-process review, multi-bg-agent, and agent-team do not cross trust boundaries — they all run within the same agent harness on the local machine, no external sink, no preflight needed. Cross-model is the only mode where preflight applies. Background and threat model: contributing/prompt-injection.md.
