Claude-Code-Workflow/.claude/skills/codex-skill-designer/specs/conversion-rules.md

Claude → Codex Conversion Rules

Comprehensive mapping rules for converting Claude Code skills to Codex-native skills.

Purpose

Phase	Usage
Phase 1	Reference when analyzing Claude source skill
Phase 2	Apply when generating Codex orchestrator
Phase 3	Apply when converting agent definitions

---

1. API Mapping

1.1 Core API Conversion

Claude Pattern	Codex Equivalent	Notes
Task({ subagent_type, prompt })	spawn_agent({ message }) + wait()	Split create and result retrieval
Task({ run_in_background: false })	spawn_agent() + immediate wait()	Synchronous equivalent
Task({ run_in_background: true })	spawn_agent() (wait later)	Deferred wait
Task({ resume: agentId })	send_input({ id: agentId })	Agent must not be closed
TaskOutput({ task_id, block: true })	wait({ ids: [id] })	Blocking wait
TaskOutput({ task_id, block: false })	wait({ ids: [id], timeout_ms: 1000 })	Polling with short timeout
Agent auto-cleanup	close_agent({ id })	Must be explicit

1.2 Parallel Task Conversion

Claude:

// Multiple Task() calls in single message (parallel)
const result1 = Task({ subagent_type: "agent-a", prompt: promptA })
const result2 = Task({ subagent_type: "agent-b", prompt: promptB })
const result3 = Task({ subagent_type: "agent-c", prompt: promptC })

Codex:

// Explicit parallel: spawn all, then batch wait
const idA = spawn_agent({ message: promptA_with_role })
const idB = spawn_agent({ message: promptB_with_role })
const idC = spawn_agent({ message: promptC_with_role })

const results = wait({ ids: [idA, idB, idC], timeout_ms: 600000 })

// Process results
const resultA = results.status[idA].completed
const resultB = results.status[idB].completed
const resultC = results.status[idC].completed

// Cleanup
;[idA, idB, idC].forEach(id => close_agent({ id }))

1.3 Resume/Continue Conversion

Claude:

// Resume a previous agent
Task({ subagent_type: "agent-a", resume: previousAgentId, prompt: "Continue..." })

Codex:

// send_input to continue (agent must still be alive)
send_input({
  id: previousAgentId,
  message: "Continue..."
})
const continued = wait({ ids: [previousAgentId] })

1.4 TaskOutput Polling Conversion

Claude:

while (!done) {
  const output = TaskOutput({ task_id: id, block: false })
  if (output.status === 'completed') done = true
  sleep(1000)
}

Codex:

let result = wait({ ids: [id], timeout_ms: 30000 })
while (result.timed_out) {
  result = wait({ ids: [id], timeout_ms: 30000 })
}

2. Role Loading Conversion

2.1 subagent_type → MANDATORY FIRST STEPS

Claude: Role automatically loaded via subagent_type parameter.

Codex: Role must be explicitly loaded by agent as first action.

Conversion:

// Claude
Task({
  subagent_type: "cli-explore-agent",
  prompt: "Explore the codebase for authentication patterns"
})

// Codex
spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

---

Goal: Explore the codebase for authentication patterns
Deliverables: Structured findings following output template
`
})

2.2 Role Mapping Table

Claude subagent_type	Codex Role Path
Explore	~/.codex/agents/cli-explore-agent.md
Plan	~/.codex/agents/cli-lite-planning-agent.md
code-developer	~/.codex/agents/code-developer.md
context-search-agent	~/.codex/agents/context-search-agent.md
debug-explore-agent	~/.codex/agents/debug-explore-agent.md
doc-generator	~/.codex/agents/doc-generator.md
action-planning-agent	~/.codex/agents/action-planning-agent.md
test-fix-agent	~/.codex/agents/test-fix-agent.md
universal-executor	~/.codex/agents/universal-executor.md
tdd-developer	~/.codex/agents/tdd-developer.md
general-purpose	~/.codex/agents/universal-executor.md
Bash	Direct shell execution (no agent needed)
haiku / sonnet / opus	Model selection via agent_type parameter

3. Structural Conversion

3.1 SKILL.md → orchestrator.md

Claude SKILL.md Section	Codex orchestrator.md Section
Frontmatter (name, description, allowed-tools)	Frontmatter (name, description, agents, phases)
Architecture Overview	Architecture Overview (spawn/wait/close flow)
Execution Flow (Ref: markers)	Phase Execution (spawn_agent code blocks)
Data Flow (variables, files)	Data Flow (wait results, context passing)
TodoWrite Pattern	update_plan tracking (Codex convention)
Interactive Preference Collection	User interaction via orchestrator prompts
Error Handling	Timeout + Lifecycle error handling
Phase Reference Documents table	Agent Registry + Phase detail files

3.2 Phase Files → Phase Detail or Inline

Simple phases (single agent, no branching): Inline in orchestrator.md

Complex phases (multi-agent, conditional): Separate phases/0N-{name}.md

3.3 Pattern-Level Conversion

Claude Pattern	Codex Pattern
Orchestrator + Progressive Loading	Orchestrator + Agent Registry + on-demand phase loading
TodoWrite Attachment/Collapse	update_plan pending → in_progress → completed
Inter-Phase Data Flow (variables)	wait() result passing between phases
Conditional Phase Execution	if/else on wait() results
Direct Phase Handoff (Read phase doc)	Inline execution or separate phase files
AskUserQuestion	Direct user interaction in orchestrator

4. Content Preservation Rules

When converting Claude skills:

1. Agent prompts: Preserve task descriptions, goals, scope, deliverables VERBATIM
2. Bash commands: Preserve all shell commands unchanged
3. Code blocks: Preserve implementation code unchanged
4. Validation logic: Preserve quality checks and success criteria
5. Error handling: Convert to Codex timeout/lifecycle patterns, preserve intent

Transform (structure changes):

• Task() calls → spawn_agent() + wait() + close_agent()
• subagent_type → MANDATORY FIRST STEPS role path
• Synchronous returns → Explicit wait() calls
• Auto-cleanup → Explicit close_agent() calls

Preserve (content unchanged):

• Task descriptions and goals
• Scope definitions
• Quality criteria
• File paths and patterns
• Shell commands
• Business logic

5. Anti-Patterns to Avoid

Anti-Pattern	Why	Correct Pattern
Using close_agent for results	Returns are unreliable	Use wait() for results
Inline role content in message	Bloats message, wastes tokens	Pass role file path in MANDATORY FIRST STEPS
Early close_agent before potential follow-up	Cannot resume closed agent	Delay close until certain no more interaction
Sequential wait for parallel agents	Wasted time	Batch wait({ ids: [...] })
No timeout_ms	Indefinite hang risk	Always specify timeout_ms
No timed_out handling	Silent failures	Always check result.timed_out
Claude Task() remaining in output	Runtime incompatibility	Convert all Task() to spawn_agent
Claude resume: in output	Runtime incompatibility	Convert to send_input()

6. Conversion Checklist

Before delivering converted skill:

• All Task() calls converted to spawn_agent() + wait() + close_agent()
• All subagent_type mapped to MANDATORY FIRST STEPS role paths
• All resume converted to send_input()
• All TaskOutput polling converted to wait() with timeout
• No Claude-specific patterns remain (Task, TaskOutput, resume, subagent_type)
• Timeout handling added for all wait() calls
• Lifecycle balanced (spawn count ≤ close count)
• Structured output template enforced for all agents
• Agent prompts/goals/scope preserved verbatim
• Error handling converted to Codex patterns