writing-agents

Writing Codex Reviewer Skills

Skill File Format

Reviewer skills live in .codex/skills/<skill-name>/SKILL.md. Frontmatter:

---
name: skill-name
description: One-line trigger description for Codex skill matching
user-invocable: false
---

• Keep frontmatter minimal: name, description, and user-invocable.
• Do not include Claude-only fields such as per-agent model routing or allowed tool lists.
• Codex uses the project-level .codex/config.toml model and reasoning effort.

Codex Tool Mapping

• Search file names with rg --files; search contents with rg.
• Run shell checks with exec_command.
• Edit files with apply_patch unless a formatter or mechanical bulk rewrite is more appropriate.
• Track multi-step work with update_plan.
• Dispatch independent reviewer work with spawn_agent only when the user has authorized parallel agent work; collect required results with wait_agent.

Standard 2-Phase Review Process

All review skills should follow this pattern:

Phase 1: Checklist

Run through numbered checks. Report concrete violations immediately. Each item should point to a file path, rg pattern, command, or explicit code invariant.

Phase 2: Deep Analysis

After the checklist:

1. What is the intent of this change?
2. What failure modes are plausible?
3. Are there edge cases the checklist did not cover?
4. Does this change affect other components?

State evidence before findings. If the code is clean, say so and call out residual test gaps.

Severity / Confidence System

Severity

• CRITICAL — Data loss, security vulnerability, crash. Example: SQL injection, auth bypass.
• WARNING — Incorrect behavior under conditions. Example: missing error wrap, N+1 query.
• SUGGESTION — Style, readability. Won't break if ignored.

Confidence

• HIGH (90%+) — Concrete bug visible in code.
• MEDIUM (60-90%) — Looks wrong based on patterns, might be missing context.
• LOW (<60%) — A hunch. Flag for human review.