🟣 Anatomía de Codex

Archivo Markdown en la raíz del proyecto que Codex inyecta en el prompt del sistema al inicio de la sesión. Cumple la misma función que CLAUDE.md; solo cambia el nombre.

Quien migra desde Claude Code copia el CLAUDE.md y le cambia el nombre. Funciona en el 90% de los casos. El 10% restante son detalles problemáticos: la sintaxis backtick-bang (inyección dinámica) no funcionará y las descripciones demasiado largas pueden truncarse.

Jerarquía global (~/.codex/AGENTS.md) frente al proyecto, ausencia de inyección dinámica nativa, tamaño ideal más conservador que Claude.

Codex separa lo que es específico tuyo (.codex/ — config.toml, agents/) en lugar de lo que es spec abierta (.agents/skills/ — sigue el estándar Agent Skills). Convención que respeta la separación entre configuración y extensión.

Quien espera «todo en una sola carpeta», como en Claude, se confunde. Las skills de Codex están en ~/.agents/skills/ globalmente y en ./.agents/skills/ por proyecto.

Estándar «config en .codex, extensiones en .agents», interoperabilidad con otras tools que usan .agents/, separación de responsabilidades.

Archivo en ~/.codex/config.toml o ./.codex/config.toml: modelo predeterminado, perfil de aprobación, modo sandbox, servidores MCP, proveedores de modelos, acceso a la red.

Codex usa TOML en lugar de JSON. La sintaxis es diferente: las claves van en [section], arrays en [[array.section]]. No es más difícil, pero es DIFERENTE.

Sintaxis TOML básica, profiles ([profiles.work]), niveles de sandbox, sobrescritura del proveedor del modelo, interpolación de env.

Los subagentes en Codex son archivos .toml en .codex/agents/. Tienen campos como name, description, model, tools e instructions (cadena multilínea con el system prompt).

Quien viene de Claude espera markdown. El agente de Codex se define con estructura: no escribes un «system prompt en prosa», completas los campos de una struct.

Cadena multilínea en TOML ("""..."""), invocación EXPLÍCITA (sin despacho automático), espacio de nombres por archivo, paralelismo manual.

En Codex, sub-agents NO se activan automáticamente por la descripción. Tienes que llamarlos por su nombre: "use o agent code-reviewer para revisar X". Sin esto, el agente simplemente no se ejecuta.

Es el error n.º 1 de quienes migran. "¿Por qué no se llama a mi agent?" — porque no lo llamaste. Escribes la descripción pensando que lo activa, pero no lo activa. Compensación: previsibilidad vs. conveniencia.

Invocación por nombre, ventaja de control (sin sorpresas), desventaja de ergonomía, patrón "menciono el agent en el prompt".

Codex tiene un sandbox configurable en config.toml: read-only (solo lee), workspace-write (escribe en el proyecto), full (libre). Y modos de aprobación que controlan cuándo pedir confirmación.

Es el nivel de granularidad de seguridad de Codex. Más explícito que el de Claude Code y configurado vía toml. Confuso al principio, pero robusto una vez que lo entiendes.

Sandbox por sesión vs. global, alcance de escritura en el filesystem, control de acceso a la red, perfiles que se combinan (danger-full-access, safe-readonly).

Codex también admite slash commands personalizados, generalmente como archivos en .codex/commands/ o mediante skills con prefijo. La sintaxis de argumentos y el namespacing difieren de Claude.

Para portar tus comandos slash favoritos. La mayoría se convierte 1:1; algunos necesitan adaptación (especialmente si usan inyección dinámica de Claude).

Convención de carpetas, frontmatter mínimo, ausencia de backtick-bang, alternativas para la inyección dinámica (script + prompt).

Las Skills de Codex están en ~/.agents/skills/<nome>/ (global) o ./.agents/skills/<nome>/ (proyecto). ¿Por qué? Porque .agents/ es la convención de la spec abierta — funciona con cualquier tool compatible.

Quién lo espera .codex/skills/ coloca la skill allí y no funciona. Un detalle pequeño, una gran consecuencia: la skill es invisible para el agente.

Convención abierta vs. propietaria, portabilidad automática a otras herramientas, recarga manual (Plugins → refresh).

El archivo SKILL.md en sí es prácticamente idéntico: frontmatter YAML con name e description, cuerpo en Markdown. La especificación Agent Skills define exactamente estos 4 elementos como comunes.

Saber EXACTAMENTE qué es común permite escribir la mayor parte de la skill una sola vez. Todo lo que quede fuera de estos 4 elementos requiere un adaptador.

Los 4 pilares (SKILL.md, name, description, body + scripts/references/assets); todo lo demás es específico del runtime.

Archivo opcional agents/openai.yaml dentro de la carpeta de la skill. Carga metadatos específicos de la interfaz (marca, ícono), declaraciones de servidores MCP requeridos y flags de comportamiento.

Sin el sidecar, tu skill funciona, pero pierde algunos refinamientos: aparece sin ícono ni branding, y las dependencias de MCP deben instalarse manualmente. Con el sidecar, la instalación queda lista para usar.

Estructura YAML del sidecar, campos compatibles (mcp_servers, branding, hidden), opt-in (no bloquea el funcionamiento básico).

Codex tiene un límite no documentado (~8K caracteres) para el tamaño de la description de una skill cuando se indexa en el catálogo. Si lo supera, la description se trunca y la skill pierde activadores.

Una skill grande importada de Claude puede tener una descripción larga que funciona bien allí y falla en Codex. Polyskill se adelanta a eso y la reescribe.

Límite oculto, comportamiento silencioso (no da error), técnica de «front-loading» (mover los activadores al principio), polyskill como solución automática.

Codex no interpreta backtick-bang como ejecución de shell antes del prompt. Las skills de Claude que dependen de esto necesitan una adaptación: convertirlo en una instrucción en prosa ("ejecuta `git status` y analiza") o en un script llamado.

Es la diferencia que más rompe la portabilidad de las skills de Claude. Polyskill hace la traducción automática como prosa de respaldo.

Inyección en build-time frente a runtime, prosa de respaldo, script delegado, idempotencia.

Servidores MCP declarados en [mcp_servers.<nome>] dentro del config.toml, o en un sidecar openai.yaml de la skill. La misma especificación MCP, el mismo protocolo, una declaración diferente.

Para conectar Slack, Gmail, GitHub, etc. a Codex. El comando, los args y las env vars son iguales que en Claude; solo cambia el formato del archivo (TOML/YAML en lugar de JSON).

Mapeo JSON↔TOML para MCP, sidecar como ubicación recomendada para las dependencias de una skill, interpolación de variables de entorno en TOML.

Codex usa $nome-skill en lugar de /nome-skill para invocar una skill explícitamente. La misma idea, distinta sigla. Slash sigue existiendo para los comandos integrados.

Reflejo de escribir / en Codex resulta en un comando interno, no en una skill. Pequeña fuente de fricción que desaparece después de 1 día de uso.

Separación entre slash (built-in) y dollar (skill), nomenclatura kebab-case, autocompletado disponible, alias posible.