4.1 Migración asistida por IA

🎯Lo que obtienes aquí

Un prompt-template probado y ajustado para convertir un proyecto Claude → Codex (y viceversa), una lista de verificación de validación posterior a la migración, una lista de las 5 trampas en las que todos caen y el puente natural hacia la Ruta 5 (polyskill).

Contenido detallado

🎯 La premisa — un agente migra a otro agente

La migración manual es costosa y tiene bugs sutiles (olvidar un sidecar, cambiar un path, perder una flag). Solución: abrir el agente DESTINO y pedirle que lea la configuración actual y genere la equivalente. Migración en minutos, con la posibilidad de captar matices que una persona podría pasar por alto.

Por qué funciona

• El agente conoce su propio formato (configuración nativa)
• Puede CONSULTAR documentación (web fetch, MCP)
• Itera rápido sobre archivos sin sufrir dolor carpiano
• Anota qué cambió para que lo revises

✗ A mano

• 2-4h para un proyecto mediano
• Se olvida de algunos detalles (sidecar, sintaxis)
• No consulta documentación actualizada
• Un bug sutil solo aparece en producción

✓ Asistida por IA

• 10-30 min para el mismo proyecto
• Cubre detalles que una persona podría pasar por alto
• Puede leer documentación oficial durante el proceso
• Informe de lo que cambió

Conceptos clave

Un agente migra a otro agente
Principio central

Consulta de documentación
Web en tiempo real

Iteración rápida
Minutos vs horas

Validación humana
Indispensable después

📋 La plantilla del prompt — copia, pega y ejecuta

Un resultado impreciso viene de un prompt impreciso. Usa esta plantilla estandarizada para garantizar la cobertura completa de la migración:

Plantilla — 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

Plantilla — Codex → Claude

Es el mismo prompt, invirtiendo el origen y el destino. Puntos que invertir:

AGENTS.md → CLAUDE.md
.codex/config.toml → .claude/settings.json (TOML → JSON)
.codex/agents/*.toml → .claude/agents/*.md (estructura TOML → frontmatter+contenido Markdown)
.agents/skills/ → .claude/skills/ (puede seguir en .agents/, pero Claude espera .claude/skills/)
Sidecar openai.yaml → frontmatter de la skill (allowed-tools, etc.)
La prosa de respaldo puede convertirse en backtick-bang (opcional)

💡Guárdalo como skill o slash command

Esta plantilla es una candidata natural para convertirse en un slash command (/migrate-from-claude) o skill (migrate-claude-to-codex) en el agente de destino. Solo ejecutas /migrate-from-claude y funciona.

Conceptos clave

El orden importa
Primero, consulta de documentación

Lista explícita
Por tipo de archivo

Informe final
Pide una explicación

Inverso simétrico
Invierte la dirección

✅ Lista de verificación posterior a la migración

El agente puede decir «migrado» y haberse saltado algo. 5 minutos de validación te ahorran horas de «por qué esto no funciona». Marca cada elemento:

🗂️ Estructura de archivos

☐ AGENTS.md existe en la raíz (o CLAUDE.md, en la dirección inversa)
☐ .codex/config.toml existe (o .claude/settings.json)
☐ .codex/agents/ tiene uno .toml por subagente
☐ .agents/skills/ tiene una carpeta por skill (NO en .codex/skills/)

⚙️ Validación técnica

☐ Abrir Codex en el proyecto — carga sin errores de parseo
☐ Listar los agents disponibles — aparecen todos
☐ Listar las skills — aparecen todas
☐ $ + el nombre de la skill se autocompleta
☐ Los servidores MCP se conectan (si corresponde)

🧪 Prueba funcional básica

☐ Invoca una skill sencilla ($skill o prompt natural)
☐ Ejecuta un sub-agent ("usa el agent X para...")
☐ Ejecuta un slash command
☐ Verifica que los hooks (si los hay) se activen en los eventos correctos
☐ Comprueba si backtick-bang se convirtió (no queda como texto literal)

📝 Revisión de cordura de AGENTS.md

☐ Los comandos de build/test siguen arriba
☐ Se preservan las convenciones centrales
☐ Sin sintaxis exclusiva de Claude (backtick-bang, referencias a la herramienta Task)
☐ Tamaño razonable (< 2KB)

Conceptos clave

Validación ≠ fe
No confía en el agente

Prueba de humo
Invoca uno de cada

Paths críticos
.agents vs .codex

Sintaxis obsoleta
Bang residual

⚠️ Las 5 trampas más comunes

En casi TODAS las migraciones aparece al menos una de estas. Si lo sabes, lo detectas antes. Si no, pasas horas depurando.

1. Skill en .codex/skills/ en vez de .agents/skills/

Síntoma: "$skill no se activa, pero el archivo está ahí".

Fix: mover la carpeta completa a .agents/skills/<nome>/. Actualiza Codex (Plugins → reload).

2. Backtick-bang copiado sin fallback

Síntoma: La skill funciona en Claude; en Codex devuelve una respuesta extraña con `!git status` tipo texto.

Fix: cambiar por prosa ("antes de empezar, ejecuta git status y lee el resultado"), o poner la lógica en un script.

3. Description larga truncada (límite ~8K)

Síntoma: La skill se activa solo con algunos prompts; no funcionan todos los triggers.

Fix: mover los triggers y ejemplos a los primeros 1-2KB de la description. El resto (contexto adicional) puede ir después, y puede truncarse.

4. Agents en markdown en lugar de TOML

Síntoma: Codex no muestra los agents, o se produce un error de parseo al iniciar.

Fix: convertir el frontmatter en claves TOML, el body en instructions = """...""". Cambia la extensión a .toml.

5. Esperar el auto-dispatch de sub-agent en Codex

Síntoma: "¿Por qué no se está llamando a mi code-reviewer cuando pido una revisión?".

Fix: llamar por el nombre — "usa el agente code-reviewer para revisar X". Codex no se activa automáticamente por description (ver T3.1).

Conceptos clave

Path correcto
.agents/skills/

Bang → prosa
Fallback semántico

Carga inicial
Activadores al principio

Invocación nominal
"use agent X"

🔁 Mantenimiento sincronizado — el "impuesto"

La migración inicial es un evento. El mantenimiento es recurrente. Todo cambio importante en CLAUDE.md debe replicarse en AGENTS.md (y viceversa). Lo mismo con las skills. Lo mismo con los sub-agents. Sin disciplina, divergen en semanas.

La regla simple: "si cambió aquí, cambió allá"

Siempre que edites:

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

🔧 Herramientas manuales

• Hook de pre-commit que avisa si hay divergencias
• Lista de verificación de la plantilla del PR
• Slash command /sync-runtimes
• Diff entre los dos archivos generado por el agente

🦜 Solución automática (skills)

• polyskill resuelve para las skills
• Source única en definition.md
• La compilación genera ambos lados
• La política de drift detecta ediciones fuera de banda

💡Esquema híbrido recomendado

Usa polyskill para skills (elemento con mayor superficie y cambios) + disciplina manual para CLAUDE.md/AGENTS.md/settings/agents (cambian poco, es viable hacerlo a mano). Ese es el equilibrio práctico.

Conceptos clave

"Cambió aquí, allá"
Regla simple

Hook pre-commit
Avisa cuando hay divergencias

Polyskill automático
Para las skills

Manual para lo demás
Settings/agents

🤝 Migración parcial — solo skills

No es todo o nada. Puedes mantener Claude Code como agente principal y usar Codex SOLO para ejecutar 2-3 skills críticas (o viceversa). Comparte el código fuente y mantiene duplicadas solo las skills.

Cuándo tiene sentido

• Skill que ROCK en Codex y es mediocre en Claude (o al revés)
• Quieres Codex solo para una «segunda opinión» en casos difíciles
• En el equipo hay 1-2 desarrolladores que prefieren el otro runtime, pero no migraron todo
• Plan gratuito limitado, se complementa con el otro

🎯

Ámbito mínimo

Porta SOLO las 2-3 skills que más usas. El resto queda solo en el agente principal.

📂

AGENTS.md mínimo

Versión simplificada del CLAUDE.md, enfocada en lo necesario para que estas skills funcionen.

🚫

Sin sub-agents

Omite la conversión de sub-agents si no los usas habitualmente en ese runtime.

Conceptos clave

No es todo o nada
Migra lo que importa

Agente principal
Sigue siendo uno solo

Skills críticas
Elige pocas

Alcance de polyskill
Resuelve estas skills

🚀 Próximo paso — polyskill

Después de la migración inicial y de la experiencia de mantener ambos lados sincronizados manualmente, llega el «ok, ya no quiero hacer esto a mano». Ahí entra la Ruta 5: polyskill.

Qué resuelve polyskill (y qué no resuelve)

✓ Resuelve:

• Skills duplicadas (source única)
• Drift silencioso (hash del archivo)
• Límite de description de Codex (front-load automático)
• Backtick-bang → prosa
• Sidecar openai.yaml (se genera automáticamente)

✗ NO resuelve:

• CLAUDE.md ↔ AGENTS.md (manual)
• settings.json ↔ config.toml (manual)
• Sub-agents Claude ↔ Codex (manual)
• Diferencias de modelo entre runtimes

🦜Quiénes ganan más

Quienes más ganan con polyskill son quienes usan regularmente 5+ skills. Para 1-2 skills, el mantenimiento manual todavía es viable. Para 10+, polyskill se vuelve indispensable.

Conceptos clave

Source canónica
definition.md

Adaptadores de runtime
claude, codex, ...

Política de drift
Hash + reconciliación

Threshold
~5 skills+

🎯Resumen del módulo

✓

Un agente migra a otro agente — no lo hagas a mano, pídele al destino que lo haga.

✓

Usa el prompt-template estandarizado — cubre AGENTS.md, config.toml, agents, skills, commands.

✓

Lista de verificación posterior a la migración en 5 min — estructura, técnica, smoke test, sanity check.

✓

5 trampas comunes: path, bang, description, TOML, dispatch — al saberlo, lo detecta de inmediato.

✓

Mantenimiento = «si cambió aquí, cambió allá» — disciplina + polyskill para skills.

✓

La migración parcial es válida — solo skills críticas, un único agente principal.

✓

Polyskill resuelve las skills, no todo — límites claros de lo que automatiza.

Siguiente ruta:

T5 — polyskill cross-runtime (spec, arquitectura, política de drift, CLI completo)

← Volver a la Ruta 4 Ruta 5: polyskill →