4.1 AI-assisted migration

🎯What you get here

A tested, battle-tested prompt template for converting a Claude project → Codex (and vice versa), a post-migration validation checklist, a list of the 5 pitfalls that catch everyone, and the natural bridge to Track 5 (polyskill).

Detailed content

🎯 The premise — agents migrate agents

Manual migration is costly and has subtle bugs (forgetting a sidecar, changing a path, losing a flag). Solution: open the TARGET agent and ask it to read the current config and generate the equivalent. Migration in minutes, with a chance to catch nuances a human might forget.

Why it works

• The agent knows its own format (native configuration)
• Can CONSULT documentation (web fetch, MCP)
• Iterate quickly over files without getting carpal tunnel
• Note what changed so you can review it

✗ By hand

• 2–4h for a medium-sized project
• Forgets details (sidecar, syntax)
• Doesn't consult up-to-date documentation
• A subtle bug only appears in production

✓ AI-assisted

• 10–30 min for the same project
• Covers details people skip
• Can read official docs during the process
• Report of what changed

Key concepts

Agent migrates agent
Core principle

Doc fetch
Real-time web

Fast iteration
Minutes vs. hours

Human validation
Essential afterward

📋 The prompt template — copy, paste, run

Vague results come from vague prompts. Use this standardized template to ensure complete coverage of the migration:

Template — Claude → Codex

Este projeto foi criado pra Claude Code. Quero usar Codex também.

Faça o seguinte (cobertura completa, não pule etapa):

1. Leia o `CLAUDE.md` atual.
   Gere um `AGENTS.md` equivalente. Mantém instruções,
   convenções e comandos de build/test.
   Remove sintaxe backtick-bang (vira prosa de fallback).

2. Leia `.claude/settings.json`.
   Crie `.codex/config.toml` equivalente. Converte:
   - permissions (allow/deny/ask) → sandbox_mode + approval_policy
   - hooks → entries equivalentes (mesma matcher, mesmo command)
   - env vars → seção [env]
   - MCP servers de .mcp.json → [mcp_servers.<nome>]

3. Pra cada sub-agent em `.claude/agents/*.md`:
   Converte pra `.codex/agents/<nome>.toml`.
   Frontmatter → chaves TOML. Body → string em `instructions = """..."""`.
   Adapta description pra mencionar invocação explícita.

4. Pra cada skill em `.claude/skills/<nome>/`:
   Copia pra `.agents/skills/<nome>/` (note: .agents/, NÃO .codex/).
   Remove campos não-portáveis do frontmatter (allowed-tools,
   disable-model-invocation, model). Converte backtick-bang em prosa.
   Se a skill precisa de MCP, cria `agents/openai.yaml` sidecar.

5. Pra cada slash command em `.claude/commands/*.md`:
   Copia pra `.codex/commands/`. Remove backtick-bang.

6. Antes de terminar: pesquise documentação oficial do Codex
   pra confirmar formatos atuais (sandbox, profiles, MCP).

7. Devolva um RELATÓRIO no final:
   - Arquivos criados (com path)
   - Conversões não-óbvias que fez
   - Coisas que removeu (e por quê)
   - O que NÃO conseguiu portar e precisa ajuste manual

Template — Codex → Claude

It’s the same prompt, with the source and destination reversed. Points to reverse:

AGENTS.md → CLAUDE.md
.codex/config.toml → .claude/settings.json (TOML → JSON)
.codex/agents/*.toml → .claude/agents/*.md (TOML struct → markdown frontmatter+body)
.agents/skills/ → .claude/skills/ (it can stay in .agents/, but Claude expects .claude/skills/)
Sidecar openai.yaml → skill frontmatter (allowed-tools, etc.)
Fallback prose can become backtick-bang (optional)

💡Save as a skill or slash command

This template is a natural candidate to become a slash command (/migrate-from-claude) or skill (migrate-claude-to-codex) in the target agent. You only run /migrate-from-claude and it works.

Key concepts

Order matters
Doc fetch first

Explicit list
By file type

Final report
Asks for an explanation

Symmetric reverse
Reverse direction

✅ Post-migration checklist

An agent can say “migrated” and have skipped something. 5 minutes of validation saves hours of “why isn't this working?” Check off each item:

🗂️ File structure

☐ AGENTS.md exists at the root (or CLAUDE.md, in the opposite direction)
☐ .codex/config.toml exists (or .claude/settings.json)
☐ .codex/agents/ has one .toml per sub-agent
☐ .agents/skills/ has one folder per skill (NOT in .codex/skills/)

⚙️ Technical validation

☐ Open Codex in the project — loads without a parse error
☐ List available agents — they all appear
☐ List skills — they all appear
☐ $ + skill name auto-completes
☐ MCP servers connect (if applicable)

🧪 Functional smoke test

☐ Invoke a simple skill ($skill or natural language prompt)
☐ Run a sub-agent ("use agent X to...")
☐ Run a slash command
☐ Verify that hooks (if any) fire on the right events
☐ Check whether backtick-bang was converted (it doesn't become literal text)

📝 AGENTS.md sanity check

☐ Build/test commands are still at the top
☐ Core conventions preserved
☐ No Claude-only syntax (backtick-bang, Task tool refs)
☐ Reasonable size (< 2KB)

Key concepts

Validation ≠ faith
Doesn't trust the agent

Smoke test
Invoke one of each

Critical paths
.agents vs .codex

Dead syntax
Residual bang

⚠️ The 5 most common pitfalls

Almost EVERY migration includes at least one of these. When you know about them, you spot them early. Without that knowledge, you spend hours debugging.

1. Skill in .codex/skills/ instead of .agents/skills/

Symptom: "$skill doesn’t trigger, but the file is there".

Fix: move the entire folder to .agents/skills/<nome>/. Refresh Codex (Plugins → reload).

2. Backtick-bang copied without fallback

Symptom: Skill works in Claude, but in Codex it returns a strange response with `!git status` text type.

Fix: replace with prose ("before you start, run git status and read the result"), or put the logic in a script.

3. Long description truncated (limit ~8K)

Symptom: Skill triggers on only some prompts; not all triggers work.

Fix: move triggers and examples to the first 1–2 KB of the description. The rest (additional context) can go afterward—and may be truncated.

4. Agents in Markdown instead of TOML

Symptom: Codex doesn’t list the agents, or there’s a parse error on startup.

Fix: convert frontmatter to TOML keys, body to instructions = """...""". Rename the extension to .toml.

5. Expecting auto-dispatch of sub-agent in Codex

Symptom: "Why isn’t my code-reviewer being called when I ask for a review?".

Fix: call by name — "use the code-reviewer agent to review X". Codex doesn’t auto-trigger based on the description (see T3.1).

Key concepts

Correct path
.agents/skills/

Bang → prose
Semantic fallback

Front-loading
Triggers at the top

Named invocation
"use agent X"

🔁 Synchronized maintenance — the "tax"

Initial migration is an event. Maintenance is recurring. Every important change to CLAUDE.md needs to be replicated in AGENTS.md (and vice versa). Same for skills. Same for sub-agents. Without discipline, they diverge within weeks.

The simple rule: “changed here, changed there”

Whenever you edit:

📘 CLAUDE.md → updates AGENTS.md
⚙️ .claude/settings.json permissions/hooks → updates .codex/config.toml
👤 .claude/agents/<x>.md → updates .codex/agents/<x>.toml
🧩 .claude/skills/<x>/SKILL.md → updates .agents/skills/<x>/SKILL.md

🔧 Manual tools

• Pre-commit hook that warns about divergence
• PR template checklist
• Slash command /sync-runtimes
• Diff between the two files by the agent

🦜 Automatic solution (skills)

• polyskill resolves for skills
• Single source in definition.md
• Build emits both sides
• Drift policy detects out-of-band edits

💡Recommended hybrid setup

Use polyskill for skills (largest surface area and change) + manual discipline for CLAUDE.md/AGENTS.md/settings/agents (change little; doing it by hand is feasible). This is the practical balance.

Key concepts

"Changed here, changed there"
Simple rule

Pre-commit hook
Warns about divergence

Polyskill automatically
For skills

Manual for the rest
Settings/agents

🤝 Partial migration — skills only

It's not all or nothing. You can keep Claude Code as your main agent and use Codex ONLY to run 2-3 critical skills (or vice versa). Share source code and keep only duplicate skills.

When it makes sense

• Skill that ROCKS in Codex and is mediocre in Claude (or vice versa)
• You want Codex only for a "second opinion" on tricky cases
• Team has 1–2 developers who prefer the other runtime, but haven't migrated everything
• Limited free plan, supplemented by the other one

🎯

Minimum scope

Port ONLY the 2-3 skills you use most. Keep the rest in the main agent only.

📂

Minimal AGENTS.md

A simplified version of CLAUDE.md, focused on what these skills need to work.

🚫

No sub-agents

Skip converting sub-agents if you don't use them regularly in this runtime.

Key concepts

It's not all or nothing
Migrates what matters

Primary agent
Still just one

Critical skills
Choose a few

Polyskill scope
Resolve these skills

🚀 Next step — polyskill

After the initial migration and the experience of keeping both sides in sync manually, comes the “okay, I don’t want to do this by hand anymore.” That’s where the Track 5: polyskill.

What polyskill solves (and what it doesn’t)

✓ Solves:

• Duplicate skills (single source)
• Silent drift (file hash)
• Codex description limit (auto front-load)
• Backtick-bang → prose
• Sidecar openai.yaml (auto-generates)

✗ Does NOT solve:

• CLAUDE.md ↔ AGENTS.md (manual)
• settings.json ↔ config.toml (manual)
• Claude ↔ Codex sub-agents (manual)
• Model differences between runtimes

🦜Who benefits most

Those who benefit most from polyskill are people with 5+ regularly used skills. For 1-2 skills, maintaining them by hand is still manageable. For 10+, polyskill becomes indispensable.

Key concepts

Canonical source
definition.md

Runtime adapters
claude, codex, ...

Drift policy
Hash + reconcile

Threshold
~5 skills+

🎯Module summary

✓

Agent migrates agent — don't do it by hand; ask the destination to do it.

✓

Use the standardized prompt template — covers AGENTS.md, config.toml, agents, skills, commands.

✓

5-minute post-migration checklist — structure, technique, smoke test, sanity check.

✓

5 common pitfalls: path, bang, description, TOML, dispatch — when you know, you detect it immediately.

✓

Maintenance = "changed here, changed there" — discipline + polyskill for skills.

✓

Partial migration is valid — only critical skills, one primary agent.

✓

Polyskill solves skills, not everything — clear limits on what it automates.

Next track:

T5 — polyskill cross-runtime (spec, architecture, drift policy, complete CLI)

← Back to Track 4 Track 5: polyskill →