Audit — Two-Pass Code Audit Skill for Claude Code

A Claude Code skill that runs an adversarial Opus deep review followed by an independent Codex second opinion on recent code changes.

Designed as a pre-commit safety net for vibe-coded features, multi-file bug fixes, and any change where "looks right" isn't good enough. Pass 1 assumes the code is broken until proven otherwise; Pass 2 verifies that a standard review also thinks the final state is clean.

What's in this repo

• SKILL.md — the skill definition: frontmatter, workflow, and the full Opus agent prompt template
• README.md — this file

Prerequisites

• Claude Code — this is a Claude Code skill, not a standalone system prompt.
• Node.js 18.18+ — required by the Codex plugin.
• ChatGPT Plus / Pro / Business / Enterprise, or an OpenAI API key — the Codex plugin uses your Codex authentication. The Free tier's rate limits are too tight for routine audit runs. See Codex pricing for tier details.
• Opus access — the skill targets model: opus (family alias — always resolves to the current Opus release) with effort: xhigh. Both are fixed by design; see Customization.
• Optional but recommended: a project-level CLAUDE.md documenting invariants — the audit checklist cross-references it.

Installation

The skill depends on the Codex plugin for Pass 2. Install both, in this order.

1. Install the Codex plugin for Claude Code

This skill uses openai/codex-plugin-cc for /codex:review (Pass 2) and optionally /codex:adversarial-review (security-critical escalation).

Inside Claude Code, run:

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

/codex:setup checks whether Codex is installed and authenticated. If the Codex CLI is missing and npm is available, it offers to install it for you. To install manually:

npm install -g @openai/codex

If Codex is installed but not signed in, run inside Claude Code:

!codex login

After install, verify:

• /codex:review and /codex:adversarial-review appear in the slash-command list
• codex:codex-rescue appears in /agents

Full plugin docs and troubleshooting: https://github.com/openai/codex-plugin-cc

2. Install this audit skill

Clone or download this repository, then copy SKILL.md into your Claude Code skills directory:

mkdir -p ~/.claude/skills/audit
cp SKILL.md ~/.claude/skills/audit/SKILL.md

3. Verify

Start a new Claude Code session in any project and run /audit. Claude will auto-scope to recent changes (uncommitted edits or unpushed commits) or report there's nothing to audit if the repo is clean. Either response confirms the install.

Usage

With arguments — scope the audit to specific files or paths:

/audit src/routes/admin.ts src/lib/auth.ts

Without arguments — audits the most recent feature or fix from the current session:

/audit

The skill identifies the change automatically — git diff and git status for uncommitted edits, falling back to git log origin/HEAD..HEAD for unpushed commits if the tree is clean. If multiple unrelated changes are in flight, it asks which one to audit.

Heads-up: Live Verification needs a running dev server. Pass 1, section 8 ("Live verification") calls your endpoints on http://localhost:*. Start your dev server before running /audit if you want those checks to actually run — otherwise the live tests fail and only the static portion of the audit produces findings.

Autonomous triggering (recommended)

/audit only runs when invoked manually unless you tell Claude otherwise. To make Claude self-trigger the audit on qualifying changes — without you having to remember — paste the snippet below into your project's CLAUDE.md (or your team's Definition of Done / pre-commit checklist).

The MANDATORY framing and blocker language are intentional. Softer phrasing ("consider running /audit") tends to get skipped under task pressure; the strong wording is what makes the rule actually fire.

**Audit Skill (MANDATORY)** — after completing any of the following, **you MUST run
`/audit`** before committing:
   - A new feature that adds a public surface (new endpoint, command, exported function, or UI flow)
   - A fix that touches 3+ source files (excluding tests and config), or rewrites more than ~30 lines in a single function
   - Any change to authentication, authorization, or access control
   - Any change to database schema, migrations, or data persistence
   - Refactors that move or rename code across multiple modules
   - Public API contract changes (request/response shapes, status codes, error formats)
   - Pagination, filtering, sorting, or aggregation logic
   - Code that combines results from multiple upstream sources (different services, tables, or APIs)
   - Any change to security-sensitive flows (credentials, tokens, webhooks, payments)

**Audit is NOT required for:** docs-only changes, comment-only changes, formatting / linting passes, dependency bumps that don't include accompanying code changes, or revert commits.

The `/audit` skill runs a two-pass code audit: an adversarial Opus deep review followed by a standard Codex second opinion (`/codex:review`). Do NOT skip it — treat audit findings as blockers that must be fixed before the commit. If the audit caps without approval (max 2 Opus passes, max 3 Codex iterations), escalate to the user — do not push past it.

Adapt the trigger list to your project's risk surface — add domain-specific patterns (e.g. "any change to billing logic", "any change to RLS policies", "any change to webhook signature verification") or remove items that don't apply.

How it works

Pass 1 — Opus deep audit (adversarial). A general-purpose subagent running on Opus reads the change, runs verification commands (live endpoint calls, type checks, grep sweeps), and produces a structured report covering:

• Type safety (nullability, as casts, any, ! assertions)
• API contracts (request validation, response shape, status codes, auth)
• Data consistency (pagination, filter sync, label maps)
• State and side effects (DB constraints, idempotency, error paths)
• Auth and access control (role coverage, public endpoints, identity fields)
• Dead code and cleanup (orphaned imports, CSS, types)
• Edge cases (empty state, null propagation, boundaries, concurrency)
• Live verification (endpoint calls across auth tiers)
• Open investigation (anything off-checklist that smells wrong)

The agent does not edit code — it reads and reports.

Pass 2 — Codex independent review. After Pass 1's findings are fixed, /codex:review runs a standard PR-review-style second opinion on the final state. The two passes serve different purposes:

Adversarial Codex escalation. /codex:adversarial-review replaces the standard Pass 2 only for security-critical changes — auth/crypto enforcement code or when the user explicitly flags the change as security-sensitive. See SKILL.md for the exact triggers; reaching for it by default produces noise and leaves no escalation path when something truly warrants it.

Iteration caps. Opus max 2 passes, Codex max 3 iterations. If either caps without verdict: approve, the skill escalates to the user with a diagnosis instead of looping further. Commit only after Codex returns verdict: approve.

Customization

The skill ships configured for a Bun + TypeScript project. Adapt for your stack by editing the allowed-tools line in SKILL.md:

The audit checklist itself is also stack-opinionated. It assumes TypeScript types, HTTP endpoints, and a frontend↔backend split — sections like Type Safety (as casts, ! assertions) and Live Verification (curl to localhost) won't map cleanly to Python data pipelines, Rust CLIs, Go services, or libraries without a web surface. For those stacks, edit the agent prompt template in SKILL.md (between the === BEGIN OPUS AGENT PROMPT === markers) — drop or rewrite the sections that don't fit, add stack-specific checks (e.g., "Pydantic model validation", "trait bounds and lifetimes", "FFI safety", "context cancellation"), tighten the report format, or swap in your team's severity definitions.

Don't tune model: or effort:. This skill is intentionally pinned to the latest Opus on xhigh effort. Audit quality drops sharply on smaller models or lower effort, and the opus alias already auto-tracks new releases, so there's nothing to maintain.

The one frontmatter dial worth tweaking is description: — it controls when Claude auto-suggests the skill. Tighten or loosen the trigger phrasing if it fires too often or not often enough.

License

Free to use, modify, and share.