Codex Skills Overview

One-Liner

Codex Skills is a specialized skill system for the Codex model — implementing multi-agent parallel development and collaborative analysis through lifecycle, workflow, and specialized skill categories.

vs Claude Skills Comparison

Dimension	Claude Skills	Codex Skills
Model	Claude model	Codex model
Architecture	team-worker agent architecture	spawn-wait-close agent pattern
Subagents	discuss/explore subagents (inline calls)	discuss/explore subagents (independent calls)
Coordinator	Built-in coordinator + dynamic roles	Main process inline orchestration
State Management	team-session.json	state file
Cache	explorations/cache-index.json	shared discoveries.ndjson

Skill Categories

Category	Document	Description
Lifecycle	lifecycle.md	Full lifecycle orchestration
Workflow	workflow.md	Parallel development and collaborative workflows
Specialized	specialized.md	Specialized skills

Core Concepts Overview

Concept	Description	Location/Command
team-lifecycle	Full lifecycle orchestrator	/team-lifecycle
parallel-dev-cycle	Parallel development cycle	/parallel-dev-cycle
analyze-with-file	Collaborative analysis	/analyze-with-file
brainstorm-with-file	Brainstorming	/brainstorm-with-file
debug-with-file	Hypothesis-driven debugging	/debug-with-file

Lifecycle Skills

team-lifecycle

One-Liner: Full lifecycle orchestrator — spawn-wait-close pipeline for spec/implementation/test

Triggers:

/team-lifecycle <task-description>

Features:

• 5-phase pipeline: requirements clarification → session initialization → task chain creation → pipeline coordination → completion report
• Inline discuss: Production roles (analyst, writer, reviewer) inline invoke discuss subagents, reducing spec pipeline from 12 beats to 6
• Shared explore cache: All agents share centralized explorations/ directory, eliminating duplicate codebase exploration
• Fast-advance spawning: Immediately spawn next linear successor after agent completion
• Consensus severity routing: Discussion results routed through HIGH/MEDIUM/LOW severity levels

Agent Registry:

Agent	Role	Mode
analyst	Seed analysis, context collection, DISCUSS-001	2.8 Inline Subagent
writer	Documentation generation, DISCUSS-002 to DISCUSS-005	2.8 Inline Subagent
planner	Multi-angle exploration, plan generation	2.9 Cached Exploration
executor	Code implementation	2.1 Standard
tester	Test-fix loop	2.3 Deep Interaction
reviewer	Code review + spec quality, DISCUSS-006	2.8 Inline Subagent
architect	Architecture consultation (on-demand)	2.1 Standard
fe-developer	Frontend implementation	2.1 Standard
fe-qa	Frontend QA, GC loop	2.3 Deep Interaction

Pipeline Definition:

Spec-only (6 beats):
  RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)

Impl-only (3 beats):
  PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001

Full-lifecycle (9 beats):
  [Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001

Beat Cycle:

event (phase advance / user resume)
      ↓
  [Orchestrator]
      +-- read state file
      +-- find ready tasks
      +-- spawn agent(s)
      +-- wait(agent_ids, timeout)
      +-- process results
      +-- update state file
      +-- close completed agents
      +-- fast-advance: spawn next
      +-- yield (wait for next event)

Session Directory:

.workflow/.team/TLS-<slug>-<date>/
├── team-session.json           # Pipeline state
├── spec/                       # Specification artifacts
├── discussions/                # Discussion records
├── explorations/               # Shared exploration cache
├── architecture/               # Architecture assessments
├── analysis/                   # Analyst design intelligence
├── qa/                         # QA audit reports
└── wisdom/                     # Cross-task knowledge accumulation

---

parallel-dev-cycle

One-Liner: Multi-agent parallel development cycle — requirements analysis, exploration planning, code development, validation

Triggers:

/parallel-dev-cycle TASK="Implement feature"
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
/parallel-dev-cycle --auto TASK="Add OAuth"

Features:

• 4 specialized workers: RA (requirements), EP (exploration), CD (development), VAS (validation)
• Main process inline orchestration (no separate orchestrator agent)
• Each agent maintains one main document (complete rewrite per iteration) + auxiliary log (append)
• Automatically archive old versions to history/ directory

Workers:

Worker	Main Document	Auxiliary Log
RA	requirements.md	changes.log
EP	exploration.md, architecture.md, plan.json	changes.log
CD	implementation.md, issues.md	changes.log, debug-log.ndjson
VAS	summary.md, test-results.json	changes.log

Shared Discovery Board:

• All agents share real-time discovery board coordination/discoveries.ndjson
• Agents read at start, append discoveries during work
• Eliminates redundant codebase exploration

Session Structure:

{projectRoot}/.workflow/.cycle/
├── {cycleId}.json                     # Main state file
├── {cycleId}.progress/
│   ├── ra/                         # RA agent artifacts
│   │   ├── requirements.md        # Current version (complete rewrite)
│   │   ├── changes.log           # NDJSON full history (append)
│   │   └── history/              # Archived snapshots
│   ├── ep/                         # EP agent artifacts
│   ├── cd/                         # CD agent artifacts
│   ├── vas/                        # VAS agent artifacts
│   └── coordination/               # Coordination data
│       ├── discoveries.ndjson      # Shared discovery board
│       ├── timeline.md             # Execution timeline
│       └── decisions.log            # Decision log

Execution Flow:

Phase 1: Session initialization
    ↓ cycleId, state, progressDir

Phase 2: Agent execution (parallel)
    ├─ Spawn RA → EP → CD → VAS
    └─ Wait for all agents to complete

Phase 3: Result aggregation & iteration
    ├─ Parse PHASE_RESULT
    ├─ Detect issues (test failures, blockers)
    ├─ Issues AND iteration < max?
    │   ├─ Yes → Send feedback, loop back to Phase 2
    │   └─ No → Proceed to Phase 4
    └─ Output: parsedResults, iteration status

Phase 4: Completion and summary
    ├─ Generate unified summary report
    ├─ Update final state
    ├─ Close all agents
    └─ Output: Final cycle report

Version Control:

• 1.0.0: Initial cycle → 1.x.0: Each iteration (minor version increment)
• Each iteration: Archive old version → Complete rewrite → Append changes.log

Workflow Skills

analyze-with-file

One-Liner: Collaborative analysis — interactive analysis with documented discussions, inline exploration, and evolving understanding

Triggers:

/analyze-with-file TOPIC="<question>"
/analyze-with-file TOPIC="--depth=deep"

Core Workflow:

Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute

Key Features:

• Documented discussion timeline: Capture understanding evolution across all phases
• Decision logging at every key point: Force recording of key findings, direction changes, trade-offs
• Multi-perspective analysis: Support up to 4 analysis perspectives (serial, inline)
• Interactive discussion: Multi-round Q&A, user feedback and direction adjustment
• Quick execute: Direct conversion of conclusions to executable tasks

Decision Recording Protocol:

Trigger	Content to Record	Target Section
Direction choice	Choice, reason, alternatives	#### Decision Log
Key findings	Finding, impact scope, confidence	#### Key Findings
Assumption change	Old assumption → New understanding, reason, impact	#### Corrected Assumptions
User feedback	User's raw input, adoption/adjustment reason	#### User Input

---

brainstorm-with-file

One-Liner: Multi-perspective brainstorming — 4 perspectives (Product, Technical, Risk, User) parallel analysis

Triggers:

/brainstorm-with-file TOPIC="<idea>"

Features:

• 4-perspective parallel analysis: Product, Technical, Risk, User
• Consistency scoring and convergence determination
• Feasibility recommendations and action items

Perspectives:

Perspective	Focus Areas
Product	Market fit, user value, business viability
Technical	Feasibility, tech debt, performance, security
Risk	Risk identification, dependencies, failure modes
User	Usability, user experience, adoption barriers

---

debug-with-file

One-Liner: Hypothesis-driven debugging — documented exploration, understanding evolution, analysis-assisted correction

Triggers:

/debug-with-file BUG="<bug description>"

Core Workflow:

Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify

Key Enhancements:

• understanding.md: Timeline of exploration and learning
• Analysis-assisted correction: Verify and correct assumptions
• Consolidation: Simplify proven-misunderstood concepts to avoid confusion
• Learning preservation: Retain insights from failed attempts

Session Folder Structure:

{projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
├── debug.log           # NDJSON log (execution evidence)
├── understanding.md    # Exploration timeline + consolidated understanding
└── hypotheses.json     # Hypothesis history (with determination)

Modes:

Mode	Trigger Condition
Explore	No session or no understanding.md
Continue	Session exists but no debug.log content
Analyze	debug.log has content

---

collaborative-plan-with-file

One-Liner: Collaborative planning — multi-agent collaborative planning (alternative to team-planex)

Triggers:

/collaborative-plan-with-file <task>

Features:

• Multi-agent collaborative planning
• planner and executor work in parallel
• Intermediate artifact files pass solution

---

unified-execute-with-file

One-Liner: Universal execution engine — alternative to workflow-execute

Triggers:

/unified-execute-with-file <session>

Features:

• Universal execution engine
• Support multiple task types
• Automatic session recovery

---

roadmap-with-file

One-Liner: Requirement roadmap planning

Triggers:

/roadmap-with-file <requirements>

Features:

• Requirement to roadmap planning
• Priority sorting
• Milestone definition

---

review-cycle

One-Liner: Review cycle (Codex version)

Triggers:

/review-cycle <target>

Features:

• Code review
• Fix loop
• Verify fix effectiveness

---

workflow-test-fix-cycle

One-Liner: Test-fix workflow

Triggers:

/workflow-test-fix-cycle <failing-tests>

Features:

• Diagnose test failure causes
• Fix code or tests
• Verify fixes
• Loop until passing

Specialized Skills

clean

One-Liner: Intelligent code cleanup

Triggers:

/clean <target>

Features:

• Automated code cleanup
• Code formatting
• Dead code removal

---

csv-wave-pipeline

One-Liner: CSV wave processing pipeline

Triggers:

/csv-wave-pipeline <csv-file>

Features:

• CSV data processing
• Wave processing
• Data transformation and export

---

memory-compact

One-Liner: Memory compression (Codex version)

Triggers:

/memory-compact

Features:

• Memory compression and merging
• Clean redundant data
• Optimize storage

---

ccw-cli-tools

One-Liner: CLI tool execution specification

Triggers:

/ccw-cli-tools <command>

Features:

• Standardized CLI tool execution
• Parameter specification
• Unified output format

---

issue-discover

One-Liner: Issue discovery

Triggers:

/issue-discover <context>

Features:

• Discover issues from context
• Issue classification
• Priority assessment

Related Documentation

• Claude Skills
• Feature Documentation

Best Practices

1. Choose the right team type:

   • Full lifecycle → team-lifecycle
   • Parallel development → parallel-dev-cycle
   • Collaborative analysis → analyze-with-file

2. Leverage Inline Discuss: Production roles inline invoke discuss subagents, reducing orchestration overhead

3. Shared Cache: Utilize shared exploration cache to avoid duplicate codebase exploration

4. Fast-Advance: Linear successor tasks automatically skip orchestrator, improving efficiency

5. Consensus Routing: Understand consensus routing behavior for different severity levels

Usage Examples

# Full lifecycle development
/team-lifecycle "Build user authentication API"

# Parallel development
/parallel-dev-cycle TASK="Implement notifications"

# Collaborative analysis
/analyze-with-file TOPIC="How to optimize database queries?"

# Brainstorming
/brainstorm-with-file TOPIC="Design payment system"

# Debugging
/debug-with-file BUG="System crashes intermittently"

# Test-fix
/workflow-test-fix-cycle "Unit tests failing"

Statistics

Category	Count
Lifecycle	2
Workflow	8
Specialized	6
Total	16+