Mapa de la ruta
Contenido detallado
🔄 Migración asistida por IA + mantenimiento en paralelo
No migras a mano. Le pides al agente nuevo que migre para sí mismo.
En vez de copiar/renombrar/convertir a mano, abres el agente de DESTINO (Codex si vienes de Claude, y viceversa) y le pides que lea la configuración actual y cree la equivalente.
La migración manual lleva horas y tiene errores sutiles. Un agente la hace en minutos y puede detectar matices (sintaxis TOML, sidecar) que tú pasarías por alto.
Principio de que "un agente migra a otro agente", investigación de documentación como parte del prompt y validación posterior por parte de una persona.
Prompt explícito que le dice al agente: lee CLAUDE.md y genera un AGENTS.md equivalente; lee .claude/agents/ y genera .codex/agents/ en TOML; lee .claude/skills/ y copia/adapta a .agents/skills/; investiga la documentación de ambos para asegurarte.
Quien envía un prompt vago obtiene resultados vagos. La plantilla estandarizada garantiza una cobertura completa: AGENTS.md + .codex/ + .agents/ + adaptación de agents a TOML.
El orden del prompt, pedir explícitamente la investigación de la documentación, enumerar los archivos esperados y pedir un informe de lo que cambió.
Lista de lo que SIEMPRE debes comprobar después de que el agente diga «migrado»: AGENTS.md tiene instrucciones equivalentes; los agents en TOML se cargan sin errores; las skills aparecen en el comando de listado; los MCP servers se conectan; los permisos tienen sentido.
El agente puede decir «listo» y haberse saltado algo. La lista de verificación es la póliza. Cinco minutos de validación te ahorran horas de «por qué esto no funciona».
Validación por funcionalidad (no solo por archivo), prueba de smoke (invocar una skill sencilla), revisar openai.yaml en las skills con dependencias de MCP.
(1) Skill en .codex/skills en lugar de .agents/skills; (2) backtick-bang copiado sin alternativa; (3) description larga truncada; (4) agents en markdown en lugar de TOML; (5) se espera auto-dispatch en Codex.
Son los 5 errores que aparecen en casi toda migración. Si los conoces, los detectas de inmediato. Si no, pasas horas depurando «por qué no se activa».
Path de carpeta correcto, conversión de inyección, límite de description, formato TOML, invocación explícita.
Después de la migración inicial, cada cambio grande en CLAUDE.md tiene que convertirse en un cambio en AGENTS.md (y viceversa). Lo mismo con las skills. Es el «impuesto» de mantener ambos runtimes.
Sin disciplina, ambos divergen en semanas y acabas con dos proyectos diferentes. La disciplina manual funciona; polyskill (T5) lo automatiza para las skills.
Regla «si cambia aquí, cambia allá», hook o checklist pre-commit, detección de divergencias, polyskill como solución para skills (no para CLAUDE.md/AGENTS.md).
Puedes tener Claude Code como agente principal y Codex solo para ejecutar skills específicas (o viceversa). No es todo o nada. Comparte el código fuente y mantén duplicadas solo las skills.
Reduce el costo de duplicación. Mucha gente migra todo creyendo que lo necesita, cuando bastaría con portar 2-3 skills críticas a Codex.
Agente principal vs. auxiliar, alcance mínimo de duplicación, «skill políglota» portada con polyskill (T5).
Después de la migración inicial y de la experiencia de mantener ambos lados, llega el «ok, ya no quiero hacer esto manualmente». Ahí entra la Ruta 5: polyskill. Una sola fuente, dos outputs, política de drift.
Para tener contexto del problema antes de ver la solución. Quien entiende lo difícil que es mantener dos skills divergentes valora mucho más polyskill.
Source of truth canónica, adaptadores por entorno de ejecución, compilación automatizada, hash de divergencia, ida y vuelta entre Claude ↔ Codex.