Portabilidad de SKILL.md: Un Vistazo Técnico a Claude Code vs. Codex CLI

El formato SKILL.md es un estándar simple y potente para extender las capacidades de los agentes de codificación. Tanto Claude Code de Anthropic como Codex CLI de OpenAI lo soportan. Esto lleva a una pregunta crítica para los desarrolladores: ¿funciona el mismo archivo SKILL.md en ambos? La respuesta simple es sí, el archivo en sí es portable. La respuesta útil es más compleja, y tiene menos que ver con el formato del archivo y más con el entorno de ejecución que cada agente proporciona.

En SkillProof, instalamos y ejecutamos skills de Claude Code en trabajo real para ver si pasan la prueba. Publicamos los resultados, incluyendo los fallos. De 2090 skills probadas en un entorno de Claude Code, 1291 pasaron (62%), 697 funcionaron solo después de una configuración que el listado debe detallar, y 102 recibieron un veredicto de fallo: algunas se ejecutaron y te dejaron en una situación peor que sin ninguna skill, otras no pudieron ejecutarse en absoluto debido a una CLI faltante, una dependencia muerta o un ejemplo que falla. Nunca hemos ejecutado una skill en Codex CLI. Todo nuestro conjunto de datos se basa en la ejecución con Claude Code.

Sin embargo, nuestro corpus de pruebas contiene un conjunto único y unidireccional de evidencia. Este artículo examina las diferencias técnicas entre cómo los dos agentes manejan SKILL.md y lo que nuestros datos exclusivos de Claude revelan sobre la portabilidad de Codex a Claude.

El Terreno Común: El Formato SKILL.md

Antes de comparar los agentes, es esencial entender qué es un archivo SKILL.md. Es un archivo de texto que combina instrucciones para el agente con metadatos. La estructura es directa:

1. YAML Frontmatter: Un bloque al principio del archivo, delimitado por ---, contiene pares clave-valor. name y description son fundamentales. El agente usa la descripción para decidir cuándo invocar la skill. Una clave opcional allowed-tools nombra herramientas que la skill quiere pre-aprobadas para no detenerse a preguntar a mitad de la ejecución. Es un campo de conveniencia, no un sandbox: no le quita herramientas al modelo. Puedes encontrar un desglose detallado en nuestra referencia de frontmatter.
2. Cuerpo Markdown: Debajo del frontmatter se encuentra el conjunto de instrucciones para el agente, escrito en markdown simple. Esto le dice al modelo cómo lograr la tarea, paso a paso.
3. Archivos Incluidos: Una skill puede incluir otros archivos, como scripts o datos de referencia, que se empaquetan con ella.

Crucialmente, SKILL.md no contiene firmas de función ni esquemas de argumentos. Es un formato de instrucción en lenguaje natural, no un manifiesto estructurado de llamada a funciones. Ese es el dominio de MCP, un protocolo separado y distinto. Para una inmersión más profunda en esto, consulta nuestra comparación de Claude Skills vs. MCP.

Debido a que SKILL.md es solo texto estructurado, cualquier parser compatible puede leerlo. Tanto Claude Code como Codex CLI pueden cargar el mismo archivo sin modificación. La diferencia es lo que sucede después.

Carga y Ejecución: Dos Entornos Diferentes

Aunque el archivo es el mismo, el contexto en el que se ejecuta no lo es. La arquitectura del agente, la configuración predeterminada y las herramientas disponibles definen el entorno de ejecución. Aquí es donde surgen las diferencias prácticas entre Claude Code y OpenAI Codex.

Claude Code

En nuestro trabajo, probamos exclusivamente con Claude Code. Las skills se cargan desde ~/.claude/skills para skills personales y .claude/skills dentro de un proyecto para las de alcance de repositorio. Cuando le das una tarea al agente, este compara tu prompt con el campo description de todas las skills disponibles. También puedes llamar a una directamente por su nombre con un comando de barra (slash command).

Un comportamiento crítico que hemos documentado es su modo de fallo. Si el frontmatter YAML en un archivo SKILL.md está mal formado (una tabulación mal colocada, una comilla faltante), Claude Code no produce un error de validación. La skill simplemente se vuelve invisible para el agente. No aparecerá en la lista y nunca se activará. Este fallo silencioso puede ser difícil de depurar, un tema que cubrimos en nuestro post sobre qué hacer cuando una skill no se activa.

Nuestra metodología implica ejecutar cada skill frente a una tarea del mundo real. Los resultados de nuestras 2090 pruebas muestran que un 'pass' no está garantizado. Las 697 skills que obtuvieron un veredicto de 'setup' requirieron una configuración no trivial que tuvimos que documentar. Los 102 'fails' o no pudieron ejecutarse en absoluto debido a dependencias faltantes o produjeron un resultado peor que no usar una skill.

Codex CLI

Codex CLI es un agente de codificación de terminal de código abierto de OpenAI. No es un wrapper de API; es una herramienta independiente que lee una base de código, realiza ediciones en múltiples archivos y ejecuta comandos en tu entorno local. Añadió soporte para SKILL.md en diciembre de 2025, inicialmente como una característica experimental.

Las rutas de descubrimiento han cambiado desde ese lanzamiento, lo cual es importante saber si estás siguiendo una guía antigua. La documentación actual de OpenAI lista .agents/skills en el directorio de trabajo y sus padres para skills de alcance de repositorio, $HOME/.agents/skills para las personales, y /etc/codex/skills para skills a nivel de máquina. La ubicación original ~/.codex/skills es la que todavía verás en la mayoría de los READMEs de skills de terceros. Una skill puede ser invocada explícitamente escribiendo $ y seleccionándola de la lista, o puede ser activada implícitamente si una tarea coincide con su descripción.

Su archivo de configuración principal es ~/.codex/config.toml, y su conjunto de instrucciones principal puede personalizarse a través de un archivo llamado AGENTS.md. Esto proporciona un punto de entrada diferente para la personalización en comparación con el modelo centrado en skills de Claude Code.

Entonces, ¿Codex soporta SKILL.md? Sí, de forma nativa. El formato de archivo es un ciudadano de primera clase. La divergencia proviene del entorno que proporciona para que ese archivo se ejecute.

Portabilidad Unidireccional: Lo que Muestran Nuestros Datos

Este es el núcleo del problema. Nunca hemos probado una skill en Codex CLI. No podemos proporcionar una tasa de éxito para Codex o una comparación directa y lado a lado basada en nuestros propios datos de prueba. Afirmar lo contrario sería inventar un conjunto de datos.

Lo que sí podemos proporcionar es una mirada honesta a un patrón específico en nuestros resultados de prueba de Claude Code. De las 2090 skills que hemos probado, nuestras notas muestran que 47 de ellas mencionan o asumen un entorno de Codex. Estas skills fueron escritas para Codex, pero las ejecutamos en un entorno de Claude Code. Esto nos da una visión única y unidireccional de la portabilidad.

Los resultados para esas 47 skills son:

• Aprobadas: 11
• Configuración: 34
• Fallidas: 2

Esto cuenta una historia clara: un archivo SKILL.md escrito para Codex tiene una alta probabilidad de requerir configuración manual para ejecutarse en Claude Code. No es porque el archivo sea inválido, sino porque las instrucciones de la skill dependen de herramientas o rutas que no existen en el nuevo entorno.

Veamos ejemplos específicos de nuestro catálogo:

• Generate 2D Map (Veredicto: Setup): El README original de la skill declara explícitamente que es para Codex/Grok y lista rutas de instalación como ~/.codex/skills y ~/.grok/skills, no el ~/.claude/skills que su listado afirmaba. Su pipeline principal necesita un par de herramientas integradas de generación y visualización de imágenes que Claude Code no tiene. La probamos en la única rama que no necesita imágenes —construyendo un mapa ortogonal de Tiled como JSON— y la skill empató exactamente con el modelo base: arreglos de tiles idénticos byte por byte, metadatos de aparición y salida idénticos. El archivo se cargó; la parte por la que valía la pena instalarla no se ejecutó.

• Generate 2D Sprite (Veredicto: Setup): Esta skill tiene el mismo problema. Depende fuertemente de capacidades de generación de imágenes que vienen con Codex y Grok pero no con Claude Code. Puede planificar una hoja de sprites, pero no puede ejecutar el paso final de producir el arte.

• Ablation Planner (Veredicto: Setup): La mecánica principal de esta skill implica delegar el trabajo de diseño a una herramienta específica de Codex. Al ejecutarla en nuestro entorno de Claude Code, esa herramienta no estaba disponible. El paso tuvo que realizarse manualmente, lo cual es la definición de un veredicto de 'setup'.

Estos ejemplos muestran que el archivo SKILL.md es portable, pero la lógica de la skill puede no serlo. Las instrucciones son solo texto; si le indican al agente que use una herramienta que no está allí, el proceso se detendrá.

Por el contrario, 11 de estas skills orientadas a Codex pasaron sin problemas. Skills como Better Codex y PinMe Share pasaron nuestras pruebas en Claude Code. Ambas aportan su valor en el texto en lugar de en herramientas de un proveedor específico. Better Codex es una capa de comportamiento de puro prompt sin archivos o scripts externos, y aun así superó al modelo base en una tarea de análisis de configuración, donde el modelo de referencia fallaba silenciosamente con valores que contenían un signo de igual. PinMe Share se instala desde un único SKILL.md válido sin referencias colgantes, y su ventaja es el conocimiento exacto de una CLI de npm común: emitió el comando de subida canónico y los pasos de autenticación requeridos, mientras que el modelo base adivinó el comando y omitió el inicio de sesión. Esa es la forma de una skill portable. Necesita una herramienta que puedas instalar, no una integrada que venga con el agente de un proveedor.

Diferencias Clave de un Vistazo

Una comparación directa resalta las concesiones al considerar codex cli o claude code para programar con skills.

Característica	Claude Code	Codex CLI
Ruta de Skill	~/.claude/skills (personal), .claude/skills (proyecto)	$HOME/.agents/skills (personal), .agents/skills (repositorio), /etc/codex/skills (máquina)
Configuración	settings.json, más CLAUDE.md para instrucciones	~/.codex/config.toml, más AGENTS.md para instrucciones
Sandboxing	Opcional (Opt-in); las variables de entorno se heredan del shell padre	Activado por defecto en workspace-write, red desactivada a menos que se habilite
SKILL.md malformado	Falla al cargar silenciosamente	(Comportamiento no probado por nosotros)

La Concesión del Sandbox

La diferencia más significativa en los entornos de ejecución es el comportamiento predeterminado del sandboxing.

Codex CLI, según su documentación, opera con una postura de seguridad predeterminada más estricta. En su modo de escritura en el espacio de trabajo (workspace-write), el acceso a la red está deshabilitado a menos que lo habilites explícitamente en config.toml. Las escrituras en el sistema de archivos están limitadas al espacio de trabajo actual, y la política de aprobación del agente por defecto es pedir confirmación antes de realizar una acción. Este es un modelo de 'denegación por defecto' (default-deny).

Claude Code, según lo documentado por Anthropic, adopta un enfoque diferente. El sandboxing es algo que activas en lugar de desactivar, e incluso con él activado, el shell hereda el entorno del proceso padre por defecto. Esto significa que si tienes credenciales como AWS_ACCESS_KEY_ID exportadas en tu sesión de terminal, una skill invocada por Claude Code puede potencialmente leerlas. Eso hace que las skills que se comunican con servicios externos o credenciales locales funcionen de inmediato, y pone sobre ti la carga de gestionar esa exposición.

Ningún enfoque es inherentemente mejor; es una concesión. El modelo de Codex prioriza la seguridad por defecto, requiriendo potencialmente más configuración para hacer funcionar una skill con acceso a la red. El modelo de Claude Code prioriza la funcionalidad inmediata, exponiendo potencialmente más del entorno anfitrión. Una skill que ejecuta un shell para llamar a una API con curl podría funcionar sin más en Claude Code pero estar bloqueada por defecto en Codex CLI.

La Regla de Decisión: Juzga el Entorno, no el Archivo

Entonces, Claude Code vs Codex CLI: ¿cuál deberías usar para las skills?

Nuestros datos proporcionan una respuesta honesta, aunque incompleta. El formato de archivo SKILL.md en sí no es el factor decisivo. El mismo archivo se cargará en ambas plataformas. La verdadera decisión depende del entorno de ejecución y de las dependencias de las skills que quieres ejecutar.

1. Verifica las Dependencias de Herramientas: ¿La skill depende de herramientas integradas y específicas del agente (como la generación de imágenes en Generate 2D Map)? Si es así, no será portable.
2. Verifica las Dependencias de CLI Universales: ¿La skill solo usa herramientas de línea de comandos ubicuas? Tiene una alta probabilidad de ser portable, como lo demuestran las 11 skills orientadas a Codex que pasaron en nuestro entorno de Claude Code.
3. Considera tu Preferencia de Sandbox: ¿Prefieres un sistema que está bloqueado por defecto y requiere permisos explícitos (Codex CLI)? ¿O prefieres uno que funciona con menos fricción de inmediato pero hereda todo el contexto de tu entorno (Claude Code)?

No podemos declarar un ganador universal porque no hemos probado en ambas plataformas. La elección depende de tus necesidades específicas y tu postura de seguridad. Lo que podemos decir con certeza es que asumir que una skill funcionará solo porque el archivo SKILL.md es compatible es un error. El entorno lo es todo.

Lectura relacionada: AGENTS.md vs Claude Skills cubre la otra mitad de la cuestión multi-herramienta: el archivo de instrucciones que cada agente lee antes de cargar cualquier skill. Y si estás eligiendo entre agentes de terminal por motivos distintos a las skills, Claude Code vs Cursor analiza esa concesión.

En SkillProof, nuestro valor reside en eliminar esta incertidumbre para el ecosistema de Claude Code. Hacemos las pruebas para que tú no tengas que hacerlo. Cada veredicto de 'pass' en nuestro catálogo representa una skill que instalamos y ejecutamos en Claude Code, en trabajo real. Para un punto de partida curado, nuestros paquetes de skills por rol recopilan diez skills probadas para una función laboral —desarrollador, revisión de seguridad, marketing, diseño y cuatro más— por $10 el paquete, con el veredicto de cada skill indicado de antemano.