La semana pasada lograste algo programando con IA al estilo vibe coding. Describiste lo que querías, el agente lo construyó, funcionó y lo publicaste. Después, el lunes, necesitaste lo mismo otra vez —el mismo ritual de release, los mismos pasos de onboarding— y escribiste el párrafo completo desde cero. De nuevo.
Ese hueco es lo que cierran los skills de Codex. Un skill es un playbook reutilizable que el agente lee solo cuando una tarea coincide con él, así que aquello que resolviste una vez se convierte en un disparador de una línea para siempre. OpenAI lanzó los agent skills para Codex como paquetes reutilizables de instrucciones —más scripts y recursos opcionales— que ayudan a Codex a completar tareas específicas de forma confiable. Esta guía cubre qué son y cómo escribir tu primero —incluyendo el árbol de carpetas y el frontmatter— sepas o no programar.
Qué es realmente un skill de agente
Un skill es una carpeta. Adentro vive un solo archivo, SKILL.md, escrito en Markdown plano. Ese es todo el piso mínimo:
release/
SKILL.md
Y el archivo en sí:
---
name: release
description: Use when cutting a new release. Bumps the version,
updates the changelog, runs the test suite, drafts release
notes, and tags the commit. Trigger on "ship a release" or
"cut version".
---
# Release playbook
1. Bump the version in package.json (patch unless told otherwise).
2. Move everything under "## Unreleased" in CHANGELOG.md into a
new dated version heading.
3. Run `npm test`. If anything fails, stop and report. Do not tag.
4. Draft release notes from the changelog entries, grouped by
Added / Fixed / Changed.
5. Create an annotated git tag matching the new version.
El frontmatter en YAML pide exactamente dos campos: name y description. El cuerpo son solo instrucciones, en el orden en que se las darías a un empleado nuevo y cuidadoso. Sin esquema JSON, sin SDK, sin paso de compilación. Un fundador sin perfil técnico puede escribir eso en cinco minutos.
Cuando un skill crece más allá de un flujo, agregas subcarpetas opcionales: scripts/ para código auxiliar que pueda ejecutar, references/ para documentos largos que pueda consultar, assets/ para plantillas y un agents/openai.yaml para configuración específica de Codex. Nada de eso es obligatorio para empezar.
En qué se diferencian los skills de los prompts y de AGENTS.md
Un prompt es una instrucción de un solo uso. Lo escribes, el agente actúa, las palabras se evaporan. La próxima vez que necesites el mismo resultado, reconstruyes el prompt de memoria —y te queda un poco mal, porque siempre pasa.
Un skill es el prompt vuelto duradero y autoseleccionable. La diferencia está en ese campo description. Codex lee de entrada el nombre y la descripción de cada skill instalado; cuando describes un objetivo, compara tu pedido contra esas descripciones y carga el playbook correcto por su cuenta. Dices "haz un release", Codex nota que la descripción del skill de release menciona exactamente eso y lo baja del estante. Nunca tienes que acordarte de que el skill existe.
Los skills no son AGENTS.md, aunque la gente que construye los confunde constantemente. AGENTS.md es contexto de proyecto siempre activo —las reglas de la casa que Codex lee en cada tarea ("usamos pnpm, nunca npm; los tests viven en __tests__; nunca toques /legacy"). Los skills se cargan bajo demanda, solo cuando una tarea coincide.
- AGENTS.md = las reglas que el agente siempre conoce.
- Skills = los playbooks que baja del estante cuando el trabajo lo pide.
Pon reglas siempre necesarias en un skill que casi nunca se dispara y el agente no las va a seguir. Pon un ritual de release de nicho en AGENTS.md y habrás inflado el contexto que paga cada tarea. Lo correcto, en la capa correcta.
Cómo dispara Codex un skill
Hay dos formas de disparar un skill, y la segunda es la interesante.
- Invocación explícita. Lo llamas por nombre —el comando
/skillso la sintaxis$skill-name, por ejemplo$release. Útil cuando sabes con precisión qué playbook quieres. - Invocación implícita. Describes el objetivo en español plano y Codex selecciona automáticamente el skill que coincide según las descripciones. Sin comando que memorizar: dices qué quieres hacer y el playbook correcto se carga solo.
La razón por la que puedes instalar decenas de skills sin que el agente se vuelva lento es la divulgación progresiva (progressive disclosure). Codex al inicio lee solo el nombre, la descripción y la ruta de archivo de cada skill —no el cuerpo completo. Carga el SKILL.md entero solo cuando decide usar ese skill. Anthropic llama a la divulgación progresiva el principio de diseño central que hace que los Agent Skills sean escalables. En palabras simples: cien playbooks en el estante cuestan casi nada hasta que se baja uno.
Los skills viven en ámbitos (scopes) que corresponden a para quién es el playbook:
- A nivel de repo —
.agents/skillsen tu proyecto. Playbooks de equipo, versionados en el repo, compartidos con todos los que lo clonan. - Personal —
$HOME/.agents/skills. Tus propios playbooks, disponibles en todos tus proyectos. - Admin / a nivel de sistema —
/etc/codex/skills. Playbooks estándar de la empresa que un administrador define para una máquina o una flota entera. - Integrados (built-in) — skills que vienen con Codex mismo, incluyendo ayudantes que crean e instalan skills por ti.
Codex y Claude Code se apoyan en el mismo estándar
El formato SKILL.md es un estándar abierto y multiherramienta, no el invento de un solo proveedor. Anthropic lo originó con los Agent Skills de Claude Code y lo publicó de forma abierta para lograr portabilidad entre plataformas, y Codex se construye sobre ese mismo estándar. El frontmatter, el modelo de divulgación progresiva y la estructura de carpetas son compartidos, así que un playbook de release es en gran parte portable entre OpenAI Codex y Claude Code. Estás aprendiendo un estándar, no apostando a un proveedor. Y los skills no son cosa solo de programadores: hay skills prearmados para documentos y hojas de cálculo que corren desde una ventana de chat, sin terminal.
Una biblioteca de skills de ejemplo
Algunos playbooks que vale la pena robarse, cada uno anclado en algo que las herramientas hacen de verdad:
release/— el ritual de version-bump-test-tag de arriba. Codex ya lee tu repo, edita archivos, corre tests y hace commit, así que este skill solo vuelve ese bucle de un solo paso.onboarding/— instala y configura las herramientas del equipo para que el agente de cada colaborador se comporte igual, enseñándole a Codex cómo hacen los tickets y el setup.branch-review/— un playbook que orquesta un equipo de subagentes. Una sola oración reparte el trabajo entre tres especialistas: "Review this branch against main. Have pr_explorer map code paths, reviewer find risks, and docs_researcher verify APIs."
Ese último muestra cómo los skills se componen con subagentes —agentes especializados que Codex puede lanzar en paralelo y consolidar en una sola respuesta. Una nota de honestidad que confunde a muchos: Codex solo lanza un subagente cuando se lo pides explícitamente. No se disparan solos.
Casos de uso de negocio para fundadores sin perfil técnico
No necesitas leer código para ninguno de estos.
- Respuestas consistentes a clientes. Un skill
support-triageque clasifica un mensaje entrante, redacta una respuesta con la voz de tu marca y marca lo que necesita un humano. Escrito enteramente en Markdown. - Update semanal a inversionistas. Un skill
investor-updateque arma tus secciones estándar, te pide los tres números de la semana y redacta el correo en tu formato. - Setup de nuevos ingresos. Un skill
onboardingpara que el primer día de una nueva contratación corra idéntico cada vez en lugar de vivir en la cabeza de una sola persona.
El patrón: cualquier cosa que expliques de la misma manera dos veces es candidata a ser un skill.
Checklist de seguridad y revisión
Los skills agregan repetibilidad; no agregan criterio. Corre esto antes de confiar en uno:
- Escribe una
descriptionque diga cuándo, no solo qué. La invocación implícita depende enteramente de eso. Una descripción vaga hace que el skill nunca se dispare —o se dispare en la tarea equivocada. - No metas todo en un solo SKILL.md gigante. Eso anula la divulgación progresiva. Cuando se vuelva inmanejable, divide el contenido a fondo en archivos referenciados.
- Mantén los skills y AGENTS.md en sus capas correctas. Reglas siempre activas en AGENTS.md, playbooks bajo demanda en skills.
- No esperes que los subagentes se lancen solos. No lo hacen —se los pides. Cuida también los valores por defecto de número de hilos y profundidad.
- Incrusta el paso de verificación en el skill. La repetibilidad de un skill no elimina el riesgo de aceptar salida de IA sin revisar. Hornea el comando de test y una instrucción de "detente si falla" directamente en el playbook.
- No asumas dependencia de un proveedor. SKILL.md es un estándar abierto y portable. Escríbelo una vez; córrelo en varias herramientas.
Los skills son el paso de madurez después del vibe coding: el vibe te da la primera versión, el skill la hace confiable, con una compuerta de verificación incorporada.
Guarda los playbooks
Guarda tus skills que funcionan como un conjunto versionado en Command Center, para que el flujo que resolviste una vez se convierta en un activo que todo el equipo reutiliza.
Fuentes y lecturas adicionales
- OpenAI Codex: Agent Skills
- Documentación de OpenAI Codex
- Anthropic: Equipping agents for the real world with Agent Skills
- Anthropic: Documentación de Claude Code
Preguntas frecuentes
¿Necesito saber programar para escribir un skill de Codex?
No. Las partes obligatorias de un SKILL.md son Markdown plano —un name, una description y instrucciones numeradas. Los scripts son opcionales. Si puedes escribir un instructivo claro para un compañero de trabajo, puedes escribir un skill.
¿Cuál es la diferencia entre un skill y AGENTS.md?
AGENTS.md es contexto siempre activo que Codex lee en cada tarea —las reglas permanentes de tu proyecto. Un skill se carga solo cuando una tarea coincide con su descripción. Las reglas permanentes van en AGENTS.md; los flujos repetibles específicos van en skills.
¿Un skill que escriba para Codex va a funcionar en Claude Code? En gran parte, sí. SKILL.md es un estándar abierto que Anthropic originó y publicó para portabilidad entre plataformas, y Codex se construye sobre ese mismo estándar. El formato, el frontmatter y el modelo de divulgación progresiva son compartidos, así que un playbook bien escrito se mueve entre ambos con poco o ningún cambio.
¿Por qué Codex no usa mi skill aunque esté instalado?
Casi siempre es la description. Codex elige skills de forma implícita comparando tu pedido contra las descripciones, así que una difusa ("ayuda con releases") pierde frente a una precisa ("Use when cutting a release; bumps version, runs tests, tags"). Indica cuándo dispararse, no solo qué hace el skill.
Relacionado en Boostor: Comandos slash y skills en Claude Code: cómo configurarlos · Buenas prácticas de AGENTS.md: mantenlo corto · Subagentes de Claude Code: cuándo y cómo