subagent-review is an OpenAI Codex skill for AI code review and multi-agent PR review. It coordinates six read-only subagents for subagent code review, assigns each a distinct lens, and synthesizes their findings into one concise top-level review for pull request review automation.
The skill is designed for PRs where a normal single-pass review is likely to miss important cross-cutting issues: behavioral regressions, security gaps, missing tests, API compatibility, reliability risks, and maintainability problems.
- Codex with custom skill support.
- Subagent support enabled in the Codex environment.
- Access to the repository, branch, PR, or diff being reviewed.
- Resolves a PR, branch, or supplied diff into a review target.
- Collects PR metadata, changed files, diff context, CI status, and repo guidance.
- Spawns six read-only subagents with non-overlapping review lenses.
- Requires evidence-backed findings with severity, impact, confidence, and suggested fixes.
- Deduplicates and ranks findings instead of pasting six reports together.
- Produces a review suitable for a user summary or GitHub PR comment.
See examples/example-review.md for a complete sample invocation and synthesized review.
By default, the skill assigns reviewers across six areas:
- Correctness and behavior
- Security and privacy
- Tests and CI
- API and compatibility
- Performance and reliability
- Maintainability and architecture
The orchestrator can adapt those lenses for the PR type. For example, a frontend-heavy PR may swap in accessibility and responsive behavior, while an infrastructure PR may emphasize deployability, observability, rollback, and environment drift.
Subagents are read-only reviewers. They must not:
- edit files
- post GitHub comments
- approve or request changes
- merge, rebase, or push
- run destructive commands
The parent agent owns synthesis. Weak or speculative claims are discarded unless they have concrete evidence such as a file, line, diff hunk, failing path, or reproducible scenario.
Use the skill explicitly when asking Codex to review a PR:
Use $subagent-review to review https://github.com/owner/repo/pull/123
or:
/subagent-review owner/repo#123
It can also review a local branch or an explicit diff when Codex has access to the repository.
The skill supports four output modes:
summary: final synthesized review onlygithub: ready-to-post PR review bodyfull: synthesized review plus concise per-subagent appendixblocking-only: only P0/P1 findings and critical test gaps
Default mode is summary.
Findings
- [P1] Missing authorization check - app/routes/admin.ts:42
The new handler reads account details before verifying the caller can access the account. Add the existing permission check before loading or returning account data.
Test Gaps
- No regression test covers access from an authenticated user without account membership.
Residual Risk
- CI status was unavailable during review.
Summary
One blocking authorization issue should be fixed before merge. The remaining review notes are test coverage gaps.
For a fuller example, see examples/example-review.md.
Clone or copy this repository into your Codex skills directory:
mkdir -p ~/.codex/skills
git clone https://github.com/jarryd/subagent-review.git ~/.codex/skills/subagent-reviewThen restart Codex so the skill is discovered.
If the skill is already installed, update it with:
cd ~/.codex/skills/subagent-review
git pull.
├── LICENSE
├── SKILL.md
├── README.md
├── agents/
│ └── openai.yaml
├── assets/
│ ├── social-preview.png
│ ├── social-preview.svg
│ └── subagent-review-icon.svg
└── examples/
└── example-review.md
SKILL.md is the runtime instruction file Codex loads when the skill triggers. agents/openai.yaml provides UI metadata for the Codex app.
This skill is intentionally focused on review, not repair. It does not ask subagents to patch code or harden a PR. The useful output is a ranked, evidence-backed review that a maintainer can act on.
assets/social-preview.png is the intended GitHub social preview image. The editable source is assets/social-preview.svg.
MIT. See LICENSE.