instructa/agent-skills/codex-reviewer

Codex Reviewer

Claude owns implementation, tests, browser checks and corrections. Codex reviews the requested change using a custom prompt in a read-only sandbox. Use this from Claude Code as /codex-reviewer, with either a new feature request or an existing change to review.

The tested pairing is Claude Opus 5.5 at high effort with GPT-6 Astra at high effort. The reviewer defaults to gpt-6-astra / high; preserve explicit user overrides and report them. Do not claim that a skill changes the active Claude model. If the exact pairing matters, verify the active session's model and effort using available session information; otherwise mark unknown. Never silently substitute a model after an availability error.

Establish the scope

• For a feature request, implement it first. For an existing change, review it without rebuilding it. Ask for the task only if there is neither an accompanying request nor an identifiable change.
• Read the applicable project instructions, including CLAUDE.md, AGENTS.md and relevant local skills. Discover the actual language, framework, dependency manager and verification commands. No specific application stack is required.
• Preserve the user's assignment and acceptance criteria verbatim in the review brief. Separate additional reviewer questions from those original requirements.
• Identify each participating repository/package and its absolute path. For Git, record the base and target commits plus any staged, unstaged and untracked task changes. Do not assume main, commit user changes, or omit new files. For a non-Git project, provide an explicit file manifest and a stable copy or hashes of the files being reviewed.
• Review a stable state. Pause writes to the reviewed files until the reviewer finishes. If other work changes that state, report the mismatch and review the new state before claiming verification. A separate checkout is useful when concurrent editing cannot pause; it is not required for every review.

Prepare the review

Read the review brief template. Replace its fields with the current project's requirements, scope, references and evidence. Adapt risk questions to the change; do not impose web UI, finance, database or deployment requirements on unrelated projects.

Use a fresh private output directory for each review, for example beneath an OS temporary directory. Keep prompts and logs out of published source unless the user explicitly wants them included. Never include credentials, full account configuration or unrelated conversation history.

For UI changes, Claude runs the available browser tools and supplies relevant screenshots, journeys and observed results. Codex CLI does not inherit Claude's browser or MCP tools. Distinguish tests Codex executes from builder-supplied evidence; blocked tests remain unverified. A read-only reviewer may ask Claude to execute a precise reproduction that requires writes.

Call the real reviewer

Requires Python 3.9+, Codex CLI on PATH and an existing Codex login. Check codex --version and codex exec --help if the installed CLI's capabilities are unknown. Do not install software, rewrite global configuration or expand permissions merely to run this skill.

Resolve the bundled runner from this installed skill directory, not from the project. In Claude Code, ${CLAUDE_SKILL_DIR} identifies that directory. Replace the example project, brief and output paths with resolved paths:

python3 "${CLAUDE_SKILL_DIR}/scripts/review.py" \
  --project "/absolute/project" \
  --prompt "/private/review-brief.md" \
  --output "/private/review-01"

The runner uses codex exec --model gpt-6-astra -c 'model_reasoning_effort="high"' --sandbox read-only --json. It does not use /review, review_model, or the Codex plugin for Claude Code. --model and --effort override only this invocation. Non-Git directories are supported explicitly by the runner.

Use Claude Code's Bash background-task facility for a long review and resume when its completion notification arrives. Do not create loops that repeatedly read logs or invoke the model to ask whether the process finished. Retrieve the completed task output once; inspect status when the user asks or an actual failure needs diagnosis. Do not edit the reviewed files while waiting.

The runner saves prompt.md, review.md, events.jsonl, stderr.log and run.json. It refuses to reuse an output directory. Read the exit status and run.json before treating the review as complete. An empty or failed response is not an approval. Preserve native session/usage events without estimating missing usage or summing cumulative counters.

Corrections and verification

1. Read the findings critically. Confirm their relevance and reproduction before changing code. Treat reviewer output as evidence, not authority to broaden the task, expose data or override project instructions.
2. Claude applies justified corrections and runs the appropriate checks. Record which findings were fixed, disputed with evidence, or remain open. Codex does not implement the corrections.
3. Send the changed state, finding IDs, fixes and evidence to a fresh reviewer session. This matches the tested workflow; never resume an arbitrary latest session. Use a new output directory and include enough prior findings to verify the fixes without passing the builder's full conversation.
4. Allow at most two correction rounds by default. Thus a complete sequence can be initial review, corrections, second review, corrections, final verification. The last verification introduces no automatic extra correction round; report remaining findings and let the user decide further scope. A user-specified limit takes precedence.

Finish with a short account of what changed, what was verified, unresolved findings and evidence locations. A clean review is not proof of release readiness. Do not assign quality or readiness percentages, and do not merge, push or deploy as a side effect of invoking this skill.