claude-skill-codex

日本語 README

A Claude Code skill that delegates implementation tasks to OpenAI Codex CLI as an autonomous sub-engineer.

Claude acts as the PdM (planning, progress monitoring, deliverable review) while Codex acts as the implementation engineer, running unattended in goal mode until verifiable completion criteria are met.

How it works

You: "/codex docs/plans/20260612_refactor.md"
          │
          ▼
Claude (PdM)
  1. Validates the plan: tasks, verifiable completion criteria,
     build/test commands, constraints
  2. Launches scripts/run_codex.sh in the background
          │
          ▼
Codex CLI (engineer, goal mode)
  - Creates a goal via the create_goal tool
  - Implements, builds, tests, fixes — loops autonomously
  - Auto-resumed up to 5 times until the final message
    contains the GOAL_COMPLETE marker
          │
          ▼
Claude (PdM review)
  - Cross-checks git diff against the plan (no out-of-scope changes)
  - Re-runs build/test commands itself (never trusts self-reports)
  - Sends fixes back via `codex exec resume`, or reports to you

Key design points:

• Plan-file driven: goals have a 4,000-char limit, so the goal points to a plan file — the officially recommended pattern
• Marker-based completion detection (GOAL_COMPLETE in the final message) instead of relying on the goal tool, which has known issues in non-interactive mode
• Quality gate: plans without verifiable completion criteria are never submitted (they break Codex's stopping condition)
• Session policy: once triggered, all subsequent implementation work in the session is also delegated to Codex

Requirements

• Claude Code
• Codex CLI v0.128.0+ (goals feature), authenticated (codex login)

Install

git clone https://github.com/xuiltul/claude-skill-codex ~/.claude/skills/codex

That's it. Trigger it in Claude Code with /codex <plan-file> or phrases like "codexで実装" / "implement this with codex".

The default SKILL.md is in Japanese. For an English skill body, swap in the translation:

cd ~/.claude/skills/codex && cp SKILL.en.md SKILL.md

Usage

# With an existing plan file
/codex docs/plans/20260612_add-auth.md

# Without a plan — Claude writes one first, then delegates
codexで実装して: ユーザー認証をJWTベースに移行

The runner script can also be used standalone:

~/.claude/skills/codex/scripts/run_codex.sh \
  -C /path/to/repo \
  -p /absolute/path/to/plan.md \
  [-r 5] [-m gpt-5.5] [-e xhigh] [-L /tmp/codex-runs/...]

Exit codes: 0 = completed, 2 = resume limit reached (incomplete), 3 = codex execution error. Logs go to /tmp/codex-runs/<timestamp>/.

Files

File	Purpose
SKILL.md	Skill definition (Japanese) — workflow, plan template, review checklist
SKILL.en.md	English translation of the skill definition
scripts/run_codex.sh	Goal-mode runner with auto-resume loop
references/codex-cli.md	Codex CLI reference: exec options, goals spec, resume constraints, troubleshooting (Japanese)
references/codex-cli.en.md	English translation of the reference

License

MIT