Migrate Agents To Codex

Migrate Agents to Codex

Purpose

Migrates Claude agent definitions from .claude/agents/*.md (YAML frontmatter

• markdown body) to Codex-compatible outputs under .codex/agents/.

Preferred output: standalone TOML custom-agent files. Backward-compatible output only: pure-markdown behavioral specifications.

The migration strips frontmatter, maps fields to native Codex contracts, preserves runtime hints such as model, effort, reasoning_effort, and model_reasoning_effort, normalizes MCP namespaces, and extracts large domain content into companion reference files.

After migration, a native Codex compliance audit (GPT-5.4 inline sub-agent) validates every migrated file passes as a native Codex sub-agent — not a ported Claude artifact. Mechanical output is never final on write alone: every mechanically generated agent requires a recorded manual nativeness review before it may be treated as native. Findings are auto-addressed and a convergence check confirms no regressions were introduced by the fixes.

Pipeline position: CODE → VERIFY (runs during implementation phase). Covers 2 stages: CODE (migration) + VERIFY (adversarial review loop).

Canonical conversation wrapper: .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py Deterministic engine: .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py

Conversation-First Entry

Bare requests should start with a user-facing action menu, not a wall of CLI flags. Follow the shared contract in ../migrate-to-codex/references/conversational-migration-contract.md.

Default menu for underspecified requests:

1. Assess one agent
2. Preview one agent as TOML
3. Migrate one agent live
4. Batch preflight all agents
5. Review one migrated agent for nativeness
6. Explain MCP or skill blockers

Routing rules:

• If the user already says preview example-agent-e, migrate example-agent-c,

or review example-agent-e, route directly.

• In Plan mode, use request_user_input only for the action choice.
• Outside Plan mode, render the same action set as a numbered text menu.
• If the action still needs an agent name, ask for it in plain text.
• Require explicit confirmation before any live write into .codex/agents/ or

any --force overwrite.

Advanced CLI

• Preferred wrappers:
• python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json
• python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json
• python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --agent example-agent-a --json
• Power-user engine:
• python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --format toml

Prerequisites

• Python 3.11+ available
• Sibling skill exists: .codex/skills/migrate-to-codex/ (provides shared functions)
• .codex/agents/ directory will be created by the script if missing
• .codex/config.toml exists with MCP server definitions
• Gold standard reference if present: a previously migrated agent artifact under

.codex/agents/

• Shared conversation contract available at

../migrate-to-codex/references/conversational-migration-contract.md

Format: Markdown vs TOML

Official Codex custom-agent format is TOML under .codex/agents/*.toml.

Use:

• --format toml for new migrations
• --format md only for backward-compatible markdown outputs

Rules:

• If both .md and .toml exist for the same agent, treat .toml as the

runtime-preferred artifact.

• Markdown remains useful as documentation and as a bridge for older migration

runs, but new custom agents should default to TOML.

• Validation must branch by format. A TOML migration is not complete if the

workflow still validates only markdown headings.

Step 1: Assess Complexity & Resolve Dependencies

Context: User provides an agent name, a list, --all, or a bare request that still needs the menu/front-door routing.

Before running the backend:

• bare request -> show the family menu from the shared conversational contract
• explicit action + explicit target -> route directly
• explicit action + missing target -> ask for the target name
• explicit review on an already migrated agent -> skip migration

write logic and jump to Step 5 as a read-only nativeness audit

• live migration -> require confirmation before the write step

1a. Classify

Classify each target agent using the decision tree in [agent-complexity-classifier.md](references/agent-complexity-classifier.md).

Run the assessment path through the backend wrapper or execute directly:

python3 .codex/skills/migrate-agents-to-codex/scripts/run_agent_migration_workflow.py --preview --agent example-agent-a --json
python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --dry-run --json

The script parses each .claude/agents/*.md, extracts frontmatter, counts MCP tools, detects hooks/orchestration patterns, and outputs a classification table with tier, readiness score, sandbox recommendation, dependency blockers, and next actions.

Skip rules:

• Agents with existing native .codex/agents/{name}.toml or legacy

.codex/agents/{name}.md → SKIP (validate only)

• Use --force to overwrite existing agents

Classification output:

Use generated classification output from the current input batch. Do not hard-code source-agent rosters in this skill.

1b. MCP Dependency Preflight

Before resolving skill dependencies or writing any migrated agent, run an MCP dependency preflight against the project-level .codex/config.toml.

Rules:

• Source of truth is the Claude agent frontmatter tools: list only.
• Extract required MCP servers only from tools matching

mcp____.

• Treat ide as a Claude-only built-in integration, not a project MCP

dependency. Record it as unsupported source tooling and drop it from migrated agent dependency requirements.

• Normalize server ids to project config-key form before comparison

(example_server_g → example-server-g, chrome_devtools → chrome-devtools).

• Read only top-level [mcp_servers.] entries from .codex/config.toml.

Nested tables such as [mcp_servers..tools.*] do not count as separate servers.

• Agent-local output must not synthesize [mcp_servers.*] stanzas. Missing

server config is resolved only by editing project .codex/config.toml.

Blocker behavior:

• --agent --dry-run: always print required/configured/missing MCP

servers and preview the generated output.

• --agent in write mode: if missing_mcp_servers is non-empty, print

a blocker report, write nothing, and exit non-zero.

• --all --dry-run: report MCP status for every agent, including all blocked

agents and their missing servers.

• --all in write mode: preflight the full batch first. If any target agent is

blocked, write nothing for the whole batch and exit non-zero.

Source-specific dependency notes:

• Treat unsupported source tooling such as ide as input data, not as an MCP blocker.
• Do not hard-code the current repository's agent roster or dependency state into public guidance.

1c. Resolve Skill Dependencies

For each agent being migrated, cross-reference its skills: frontmatter against what exists in .codex/skills/:

# Extract skills from Claude agent
grep '^  - ' .claude/agents/{name}.md | sed 's/^  - //'

# Check which exist in Codex
ls .codex/skills/

Produce a dependency table:

Agent:  (Tier 3)
Skills: 5 declared, 3 available, 2 MISSING
  ✅ api-proxy-pattern-example              → .codex/skills/api-proxy-pattern-example/SKILL.md
  ✅ frontend-interaction-example  → .codex/skills/frontend-interaction-example/SKILL.md
  ✅ api-contracts-example          → .codex/skills/api-contracts-example/SKILL.md
  ❌ example-url-validator             → NOT IN .codex/skills/
  ❌ example-feature-implementation → NOT IN .codex/skills/

If all skills are available → READY. Proceed to Step 2.

If any skills are missing → BLOCKED. For each missing skill, choose a resolution:

| Resolution | When to Use | Action | |---|---|---| | MIGRATE | Skill is essential to the agent's core workflow | Invoke $migrate-to-codex for this skill BEFORE continuing agent migration | | SUBSTITUTE | A similar Codex skill covers the same domain | Map to the substitute in References, document the rationale | | DROP | Skill is deprecated, merged, or redundant with agent body content | Omit from References, document the rationale |

Present the dependency table to the user with recommended resolutions. Only proceed to Step 2 after all missing skills are resolved (migrated, substituted, or explicitly dropped).

Example resolution table:

| Missing Skill | Recommendation | Rationale | |---|---|---| | example-url-validator | SUBSTITUTE → developing-website-features | URL validation rules are covered in agent body Constraints section | | example-feature-implementation | SUBSTITUTE → integration-testing | Testing patterns overlap; fullstack patterns are in companion ref |

Batch migration note: When migrating --all, run Step 1c across ALL agents first to collect the full set of missing skills. Migrate missing skills in one batch before starting any agent migrations. This prevents redundant skill migrations when multiple agents share the same dependency.

Step 2: Map Fields

Apply the field mapping from [agent-field-mapping.md](references/agent-field-mapping.md).

Key transformations:

| Claude Field | Codex Section | |---|---| | name | # Agent: {Title} | | description | ## Purpose | | tools + disallowedTools | ## Recommended Sandbox + ## Constraints | | model + effort / reasoning_effort / model_reasoning_effort | ## Runtime Configuration | | skills | ## References (.codex/skills/ paths) | | hooks.Stop | ## Runtime Configuration → completion gate | | color, permissionMode | Dropped (documented loss) |

MCP namespace normalization (automated by script):

• example-server-g config server id → mcp__example_server_g__*
• chrome-devtools config server id → mcp__chrome_devtools__*

Skills → References mapping: All skill dependencies were resolved in Step 1b. Map each resolved skill 1:1 to .codex/skills/{name}/SKILL.md. Substituted or dropped skills use the resolution documented in Step 1b.

Runtime hint preservation: If the Claude source already carries concrete Codex runtime hints such as model = "gpt-5.4-mini" and model_reasoning_effort = "medium", preserve them in TOML output instead of down-mapping them to legacy advisory prose.

Body preservation: Preserve as much Claude agent content as possible. Agent spec hard limit: ≤1000 lines. Extract to .codex/agents/references/{name}-domain.md only if exceeding the limit.

Step 2.6: Convert Embedded Delegation Sites

If the source agent or its companion references contain embedded delegation sites, apply the decision process in [subagent-migration-guide.md](references/subagent-migration-guide.md).

Decision rules:

• Reusable named role → create .codex/agents/.toml
• One-off workflow-local prompt slice → keep inline via spawn_agent(...)
• Thin proxy around one MCP call → usually keep inline
• Routing table with several named roles → every reachable role must have a

real Codex agent file before the migration is considered complete

Model guidance:

• Use the intent-based mapping in

[subagent-migration-guide.md](references/subagent-migration-guide.md) Section 2.

• Treat that table as this migration package's policy informed by Codex runtime

guidance, not as an official OpenAI Claude-to-Codex table.

Format note:

• File-backed custom agents should use --format toml.
• Markdown output remains valid for compatibility, but it is not the preferred

target for new reusable sub-agent roles.

Step 2.5: Verify Domain Content (Tier 2-3 only)

WHY THIS STEP EXISTS: Claude agent bodies drift from the codebase. Route constants get renamed, helper functions get deleted, test infrastructure gets replaced. If you copy stale domain examples into the companion reference, the Codex audit will catch them — but at the cost of an extra audit cycle (~500K-1.5M tokens). Verify first, write once.

For every code example, symbol, path, or config pattern in the Claude agent body, verify against the live codebase before including in the Codex output:

| Content Type | Verification Method | |---|---| | Configuration constants (EXAMPLE_CONSTANTS.*) | grep -n "EXAMPLE_" example-project/src/config/settings.config.ts | | Helper function names | grep -rn "functionName(" path/to/module/ | | Directory paths (locales/, i18n/) | ls path/to/directory/ | | Locale directory aliases | Check actual directory names | | Router meta patterns (meta.role vs meta.roles) | grep -n "meta.*role" example-project/src/router/ | | Test infrastructure (stub dependency vs real dependency) | Read test setup files: example-project/tests/fixtures/ | | MCP tools referenced | Check config.toml entries |

Decision rule: If a code example can't be verified in

Output is structurally complete, but it is not final on write alone. Record a
manual nativeness review before treating the generated agent as native.

### Tier 2 (Assisted)

```bash
python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent  --format toml

Script output contains [REVIEW: ...] annotations. Review:

• MCP preflight status: confirm project .codex/config.toml satisfied all

required top-level MCP servers before write mode

• Sandbox recommendation: confirm matches agent's access pattern
• Knowledge Priority ordering: adjust for agent's actual tool preference
• initialPrompt → Initial Action conversion: verify prose is accurate

Tier 3 (Hand-Authored)

python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --agent  --format toml

Script generates a skeleton with [TODO: hand-author] placeholders.

1. Read a representative migrated agent artifact under .codex/agents/
2. Read template: [codex-agent-template.md](references/codex-agent-template.md)
3. Fill domain sections manually (keep ≤40 lines each)
4. Extract verbose content to .codex/agents/references/{name}-domain.md
5. For orchestrator roles: restructure Supervisor Pattern per

[architectural-patterns.md](references/architectural-patterns.md) Pattern 4 + 6

Batch Mode

python3 .codex/skills/migrate-agents-to-codex/scripts/migrate_claude_agents_to_codex.py --all --format toml

Processes all agents. Preflight MCP dependencies → assess → migrate by tier → report.

Step 4: Validate

Automated Checks

Native Codex output is TOML. Use markdown-only checks only when you explicitly request --format md.

# Markdown compatibility output only:
# 1. No frontmatter delimiters (line 1 must NOT be --- or +++)
head -1 .codex/agents/{name}.md | grep -Ev '^(---|\+\+\+)$'

# 2. No Claude primitives or hyphenated MCP namespaces
python3 tools/migration_support/validate_names.py --scan-dir .codex/agents/

# 3. Required sections present
grep -c '## Purpose\|## Constraints\|## Output Contract' .codex/agents/{name}.md

# 4. Under 1000 lines (hard limit)
wc -l .codex/agents/{name}.md

# 5. Starts with # Agent:
head -1 .codex/agents/{name}.md | grep '^# Agent:'

# Native TOML output:
# 1. Valid TOML syntax
python3 - `, or `review `.
- In that entry path, the parent dashboard remains a thin router. This skill
  owns the reviewer prompt, delegated lifecycle, review-report guidance, and
  tracker close-out instructions.
- Shared nativeness handoff helpers live in
  `tools/migration_support/`; workflow
  scripts bootstrap that package before importing s

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zuharz](https://github.com/zuharz)
- **Source:** [zuharz/ccode-to-codex](https://github.com/zuharz/ccode-to-codex)
- **License:** MIT

Install and usage instructions live in the source repository linked above.