# Migrate Agents To Codex

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-zuharz-ccode-to-codex-migrate-agents-to-codex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zuharz](https://agentstack.voostack.com/s/zuharz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zuharz](https://github.com/zuharz)
- **Source:** https://github.com/zuharz/ccode-to-codex/tree/main/.codex/skills/migrate-agents-to-codex

## Install

```sh
agentstack add skill-zuharz-ccode-to-codex-migrate-agents-to-codex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
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/`:

```bash
# 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)

```bash
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

```bash
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`.

```bash
# 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:'
```

```bash
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zuharz-ccode-to-codex-migrate-agents-to-codex
- Seller: https://agentstack.voostack.com/s/zuharz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.