Codex Skills explicado: qué es SKILL.md y cómo usarlo (2026)

- Los datos y cifras de abajo se contrastaron con la documentación oficial al momento de escribir (08/2026); la terminología de Codex Skills/Plugins cambia rápido — verifica la documentación en vivo antes de depender de ella.

¿Qué son las Codex Skills?

Una Codex skill es una carpeta que empaqueta instrucciones — y, opcionalmente, scripts, referencias y assets — en una capacidad reutilizable que Codex incorpora solo cuando la tarea lo pide. En lugar de reexplicar "así hacemos las migraciones de base de datos" en cada sesión, lo escribes una vez como un archivo SKILL.md y Codex lo carga bajo demanda.

Aquí va la distinción que conviene dejar clara de entrada: Codex Skills no es un formato que OpenAI inventara desde cero. SKILL.md es el estándar abierto Agent Skills — "desarrollado originalmente por Anthropic, publicado como estándar abierto y adoptado por un número creciente de productos de agentes", según el propio sitio del estándar. Anthropic lo lanzó primero para Claude Code (octubre de 2025); OpenAI adoptó el mismo formato de archivo para Codex y ChatGPT pocas semanas después. El mismo SKILL.md, dos ecosistemas.

En la práctica, una skill es: un nombre más una description que actúa como disparador (siempre visible para Codex) y un cuerpo en Markdown (que se carga solo cuando hay match). Está pensada para trabajo repetible y con forma de tarea — una rutina de corrección de lint, un checklist de migración, un formato de changelog — no para conocimiento general ni contexto de proyecto siempre activo. Ese es el trabajo de AGENTS.md, que veo más adelante.

Una comprobación útil de sentido común antes de escribir una: ¿pegarías esto en una sesión más que unas pocas veces, y se mantiene básicamente igual cada vez? Si es así, tiene forma de skill. Si los pasos cambian según el archivo o la función que estés tocando, o si es solo conocimiento general de "cómo funciona este repositorio", probablemente pertenece a otro sitio — un doc, un comentario o AGENTS.md.

Anatomía de un archivo SKILL.md

Una skill es una carpeta con el nombre de su slug, con un archivo obligatorio y hasta cuatro opcionales:

my-skill/
├── SKILL.md            (required)
├── scripts/            (optional - executable code)
├── references/         (optional - docs the skill can point to)
├── assets/             (optional - templates, static files)
└── agents/openai.yaml  (optional - Codex-specific UI + MCP metadata)

El SKILL.md en sí es frontmatter YAML seguido de instrucciones en Markdown. Solo dos campos son obligatorios:

---
name: changelog-writer
description: Turn a git diff into a changelog entry. Use when the
  user asks for a changelog, release notes, or "what changed".
---

# Changelog writer

1. Run `git diff --stat` and `git log -5 --oneline`.
2. Group changes by type: Added, Changed, Fixed.
3. Write 3-6 bullet points in the project's changelog format.

name es el identificador; description es el disparador — la única línea que Codex lee para decidir si la skill aplica, así que escríbela con precisión ("usa cuando...") en lugar de algo vago ("ayuda con los changelogs").

El opcional agents/openai.yaml es específico de Codex: no afecta a Claude Code ni a ningún otro cliente, solo a cómo se ve y se comporta la skill dentro de Codex/ChatGPT. Según la documentación actual, cubre tres grupos de campos — interfaz (display_name, short_description, icon_small/icon_large, brand_color, default_prompt), política (allow_implicit_invocation, true por defecto) y una lista de dependencias de herramientas (un servidor MCP que la skill necesita, con su transporte y URL). Los nombres de los campos de este archivo cambian junto con el producto — revisa la documentación en vivo antes de depender de alguno en producción.

Cómo funcionan las Codex Skills (divulgación progresiva)

El mecanismo que hace que las skills sean baratas de tener a mano se llama divulgación progresiva, y funciona en tres etapas, según la documentación oficial:

1. Descubrimiento — al arrancar, Codex carga solo el name y la description de cada skill. Suficiente para saber que una skill existe, pero no para usarla todavía.
2. Activación — cuando tu prompt hace match con la description de una skill, Codex lee el cuerpo completo del SKILL.md al contexto.
3. Ejecución — Codex sigue las instrucciones, ejecutando scripts empaquetados o incorporando archivos de references/assets según lo que la skill pida.

La etapa de descubrimiento tiene un presupuesto estricto: la lista inicial de skills (el name más la description de cada skill instalada, combinados) está limitada al 2 % de la ventana de contexto del modelo, o a 8.000 caracteres cuando se desconoce el tamaño de la ventana de contexto — lo que aplique. Ese es un techo real que la competencia rara vez menciona: instala demasiadas skills verbosas y algunas simplemente no entrarán en la lista.

De ahí se siguen dos consecuencias prácticas. Primero, escribe descriptions ajustadas — deja espacio para otras skills, y una vaga ("ayuda con el código") no se dispara de forma fiable, mientras que una precisa ("usa cuando la persona pida un changelog...") sí. Segundo, no pongas nada sensible al tiempo solo en la description; si únicamente importa una vez que la skill ya está en marcha, ponlo en el cuerpo, no en la línea del disparador.

Dónde busca Codex las skills (alcance y precedencia)

Codex rastrea varias ubicaciones en busca de skills, de la más específica a la más general. Para un nombre que hace match, gana la ubicación más específica:

Dos maneras de activar una skill una vez que Codex puede verla:

• Explícita — escribe $skill-name en el Codex CLI o en el IDE (o /skills para explorar), @skill-name en ChatGPT.
• Implícita — solo describe la tarea en lenguaje natural; Codex la compara con la description de cada skill visible y la invoca automáticamente.

Haz commit de las skills con alcance de repositorio en .agents/skills/ para que las reciba todo el equipo; guarda tus costumbres personales en la carpeta de alcance de usuario para que te acompañen entre proyectos.

Cómo instalar y crear una Codex skill

Dos caminos: instalar una que escribió otra persona, o construir la tuya.

Instalar una skill ya existente

Dentro de una sesión de Codex, ejecuta la skill instaladora integrada:

$skill-installer linear

Apúntala a un nombre del catálogo actual, o a una URL de GitHub, y clona la skill en tu carpeta de skills (alcance de usuario por defecto; pasa una ruta de proyecto si la quieres con alcance de repositorio). Un apunte sobre actualidad que conviene conocer: el catálogo de skills de OpenAI ya se movió una vez. El openai/skills en GitHub lleva un aviso de discontinuación que apunta a openai/plugins — y, al momento de escribir esto, ese repositorio sucesor también ha sido archivado (solo lectura, sin reemplazo listado). Ninguno de los dos repositorios de GitHub es un catálogo activo y fiable ahora mismo. Trata la página de documentación oficial como el único enlace en el que vale la pena confiar, y espera que la lista de fuentes por defecto de $skill-installer siga cambiando — verifica a qué resuelve en realidad antes de ejecutarla dentro de un script.

Construye la tuya con el creador interactivo

$skill-creator

Este te guía por nombrar la skill, escribir la description que sirve de disparador y redactar el cuerpo de forma interactiva, y luego guarda la carpeta en tu ruta de skills. Para una skill que vas a reutilizar tú misma, tres hábitos importan más que la herramienta en sí:

1. Escribe la description como un disparador, no como un resumen — "usa cuando X" le gana a "ayuda con X".
2. Mantén el cuerpo con forma de tarea. Si estás documentando contexto de proyecto siempre cierto en vez de un trabajo específico, eso pertenece a AGENTS.md, no a una skill.
3. Prueba las dos rutas de invocación — llámala explícitamente con $your-skill primero para confirmar que el cuerpo funciona, luego actívala implícitamente con lenguaje natural para confirmar que la description de verdad se dispara.

También puedes crear la carpeta y el archivo a mano — mkdir -p .agents/skills/my-skill && touch .agents/skills/my-skill/SKILL.md — el creador interactivo es una comodidad, no un requisito.

Codex Skills vs AGENTS.md vs Plugins — ¿cuál necesitas?

Tres primitivas, tres funciones. No compiten — la mayoría de las configuraciones reales de Codex usan dos, o las tres, a la vez.

El planteamiento oficial, casi literal: una skill "empaqueta instrucciones y recursos de apoyo para una tarea o flujo de trabajo específico", mientras que un plugin "es un paquete instalable que puede incluir skills, conectores, o ambos". Así que un plugin no es un cuarto formato que compita con las skills — es una capa de empaquetado que puede entregar una o varias skills juntas, además de cosas que no son skills, como conectores.

AGENTS.md está en un carril completamente distinto: no se carga bajo demanda, está siempre en el contexto — que es justo por qué el consejo para él va en sentido contrario al de una skill. Mantenlo corto (comandos, reglas duras, rutas clave), no largo, porque cada línea cuesta tokens en cada turno. Para la guía completa sobre escribir uno esbelto, mira AGENTS.md vs CLAUDE.md vs SKILL.md; para el orden de búsqueda del propio AGENTS.md de Codex, mira la guía del AGENTS.md de Codex.

En la práctica los tres se apilan, no se sustituyen. Un repositorio típico podría mantener un AGENTS.md corto para comandos de build/prueba y reglas duras, un puñado de skills para trabajos repetibles como notas de versión o un patrón específico de refactorización, e instalar un paquete de plugin que entrega varias skills relacionadas más un conector de una vez. Ninguno de los tres reemplaza a los otros; cada uno solo responde a una pregunta distinta sobre cuándo Codex debería saber o hacer algo.

¿Son las Codex Skills lo mismo que las Claude Code Skills?

En lo esencial, sí — y hay una fuente primaria de verdad para eso, no solo una impresión. agentskills.io, el propio sitio del estándar, lista "Claude Code" y "ChatGPT & Codex" uno al lado del otro como clientes compatibles, y afirma que el formato "fue desarrollado originalmente por Anthropic, publicado como estándar abierto y adoptado por un número creciente de productos de agentes".

Vale la pena ser precisa aquí: ninguna página única de OpenAI dice "compatible con Claude Code" con esas palabras exactas. La afirmación de compatibilidad cruzada se apoya en la lista de clientes del propio estándar más análisis independientes de terceros, no en una cita de OpenAI — así que así es como este artículo lo plantea: el mismo estándar abierto, no un respaldo oficial de OpenAI a Claude Code.

Lo que de verdad viaja entre las dos herramientas: el propio archivo SKILL.md — name, description, el cuerpo en Markdown y las carpetas scripts//references/assets. Escribe una skill en una herramienta y el archivo central funciona en la otra, con los extras no leídos y todo.

Lo que no viaja son los extras específicos de cada cliente, que la otra herramienta simplemente ignora:

• Codex añade agents/openai.yaml para los metadatos de UI de ChatGPT de escritorio y las dependencias de herramientas MCP.
• Claude Code añade context: fork (ejecuta la skill en un subagente aislado) y disable-model-invocation (bloquea el disparo automático de skills con efectos secundarios) — mira el desglose completo en Claude Code Skills explicado.

Conclusión práctica: construye una skill sin frontmatter específico de cliente y ya es portable por defecto. Añade un campo solo de Codex o solo de Claude y la otra herramienta simplemente lo ignora — no se rompe, solo no hace nada ahí.

¿No quieres escribir la tuya? Kits listos de skills y flujos de trabajo

Escribir skills a mano está bien cuando quieres un flujo de trabajo exacto y personal. Si prefieres partir de una biblioteca curada en lugar de un SKILL.md en blanco, esa es la brecha que AgentKit llena con honestidad — mira cómo encaja en Codex en concreto en usando AgentKit dentro de Codex, o ve directo a agentkit.best. Una distinción rápida, ya que los nombres se confunden: este es el AgentKit de afiliado (agentkit.best, CLI ak) — no el propio producto AgentKit/Agent Builder de OpenAI.

Para ser directa sobre el límite: la función nativa de Skills de Codex es gratuita, incluida en tu plan de ChatGPT — nada de esto exige una compra. AgentKit es un complemento aparte y de pago: un kit curado de skills, subagentes y flujos de trabajo listos que se instala en Codex con ak kit init engineer --target codex --global y luego se ejecuta vía $ak:cook en lugar de que escribas cada SKILL.md a mano. Es la opción de "alguien ya lo construyó y lo probó", no un requisito para que las Skills funcionen.

FAQ

¿Son gratuitas las Codex Skills?

Sí. Las Skills son una función nativa de Codex incluida en tu plan de ChatGPT — escribir, instalar y ejecutar tus propios archivos SKILL.md no cuesta nada extra. Solo aparece un costo si eliges comprar un kit listo de terceros en lugar de construir el tuyo.

¿Cuál es la diferencia entre una Codex skill y AGENTS.md?

Una skill es bajo demanda: se carga solo cuando una tarea hace match con su description. AGENTS.md está siempre cargado: se mantiene en el contexto en cada turno. Usa una skill para un trabajo específico y repetible; usa AGENTS.md para comandos y reglas que siempre deban conocerse.

¿Funcionan las Codex Skills en Claude Code?

El archivo central SKILL.md sí — las dos herramientas leen el estándar abierto Agent Skills, y agentskills.io lista ambas como clientes compatibles. Los extras específicos de cada cliente no cruzan: el agents/openai.yaml de Codex lo ignora Claude Code, y los campos context: fork / disable-model-invocation de Claude Code los ignora Codex.

¿Dónde pongo una Codex skill personalizada?

Para todo el repositorio: .agents/skills/ en la raíz del repositorio (haz commit para que tu equipo también la reciba). Personal, en todos los proyectos: $HOME/.agents/skills. Codex también revisa el directorio de trabajo actual y su padre, además de ubicaciones de admin e incluidas con el sistema, en ese orden.

¿Puedo instalar la skill de otra persona?

Sí — ejecuta $skill-installer desde dentro de Codex, apuntándolo a un nombre de catálogo o a una URL de GitHub, y clona la skill en tu carpeta de skills. Revisa el SKILL.md y los scripts de cualquier skill de terceros antes de instalarla, igual que revisarías una nueva dependencia.

¿Sigue siendo openai/skills el catálogo oficial de skills?

No. openai/skills en GitHub está discontinuado y apunta a openai/plugins — y, al momento de escribir esto, openai/plugins también ha sido archivado (solo lectura). Ninguno de los repositorios es un catálogo activo; usa la documentación oficial en learn.chatgpt.com/docs/build-skills.

Conclusión

Una Codex skill es una carpeta, un archivo SKILL.md y una description que sirve de disparador — nada más exótico que eso. Es bajo demanda donde AGENTS.md es siempre activo, portable a Claude Code porque ambos leen el mismo estándar abierto Agent Skills, y gratuita porque viene dentro del propio Codex. Empieza en pequeño: elige una tarea que no paras de reexplicarle a Codex, escribe una description ajustada y deja que la divulgación progresiva la mantenga barata. Si prefieres no escribir una biblioteca desde cero, un kit curado como AgentKit es el atajo de pago — no un requisito. Mira cómo encaja AGENTS.md junto a las skills en la guía del AGENTS.md de Codex, o empieza por qué es Codex si todavía estás ubicándote.