Codex Skills: cómo crear workflows reutilizables sin inflar el contexto del agente

Una Codex Skill es un directorio con un SKILL.md obligatorio y, cuando hace falta, scripts, referencias y assets. La keyword principal es Codex Skills; la intención es de implementación: un developer busca convertir un procedimiento repetido en un workflow que el agente pueda descubrir y ejecutar de forma consistente.

TL;DR

La idea clave es la carga progresiva: Codex conoce al principio solo el nombre y la descripción; lee las instrucciones completas cuando la tarea encaja. Las referencias largas no deben vivir en el prompt permanente. Se cargan solo desde el SKILL.md si el workflow las necesita. Eso conserva contexto para el código y evita que una 'ayuda' acabe empeorando el razonamiento.

Mi postura: empieza por una skill que elimine una decisión repetitiva y verificable —por ejemplo, reproducir un bug de CI o preparar una migración—, no por una que intente convertir al agente en el experto universal de tu empresa. Una skill buena reduce ambigüedad; una enorme solo es otro sitio donde esconder políticas contradictorias.

Qué es una skill y qué no es

Una skill empaqueta una capacidad orientada a tarea. Su description explica cuándo debe activarse; SKILL.md define el procedimiento; los scripts encapsulan operaciones frágiles; las referencias aportan detalle bajo demanda. El resultado ideal es que dos personas obtengan el mismo checklist y la misma evidencia aunque formulen la petición de manera distinta.

No es un sustituto de AGENTS.md. AGENTS.md contiene reglas duraderas del repositorio: comandos de test, fronteras de seguridad, convenciones y rutas sensibles. Una skill contiene un workflow especializado: qué hacer para esta clase de tarea y cómo comprobar que quedó bien. Si copias todo AGENTS.md dentro de cada skill, tendrás varias políticas que divergirán.

Tampoco es una vía para elevar permisos. Una skill puede recomendar un script, pero la sandbox, la política de aprobaciones y las credenciales de la sesión siguen siendo los controles que deciden qué puede ocurrir. Trata cada comando incluido como código de producción: revisable, acotado e idempotente cuando sea posible.

La skill decide el procedimiento; los controles de la sesión y la verificación siguen decidiendo si el cambio es aceptable.

La arquitectura mínima que sí escala

Deja SKILL.md corto y ejecutable. Si necesita 20 páginas de contexto, separa las ramas del proceso y coloca el detalle en references/. Si necesita copiar comandos complejos, muévelos a scripts/ y dale parámetros explícitos. El agente debe leer instrucciones, no reconstruir shell heredada a partir de párrafos vagos.

Usa agents/openai.yaml solo para metadata o dependencias de presentación cuando sea útil; no lo confundas con un mecanismo de autorización. La política real de red, filesystem y aprobación se aplica fuera del paquete. Esa separación evita el error clásico de creer que una lista declarativa protege un secreto o un servicio externo.

Una estructura pequeña suele bastar: SKILL.md para el contrato, scripts/ para pasos repetibles, references/ para documentación que no debe ocupar contexto siempre y assets/ para plantillas consumidas por el resultado. No añadas README, changelog y cinco guías auxiliares por reflejo: son más superficie que el agente tendrá que elegir mal.

Crea un SKILL.md que el agente pueda elegir

El frontmatter solo necesita un nombre estable y una descripción concreta. La descripción es un selector: menciona el resultado, las señales de activación y una frontera. 'Ayuda con desarrollo' no selecciona nada; 'reproduce fallos intermitentes de pytest y guarda evidencia sin cambiar producción' sí.

Después escribe imperativos observables: inspecciona primero, preserva cambios existentes, ejecuta un comando de repro, aplica el cambio mínimo, corre la regresión y reporta evidencia. Evita instrucciones como 'usa tu criterio' precisamente donde el equipo espera uniformidad. El criterio humano debe aparecer como una condición de parada o una aprobación requerida.

Ejemplo mínimo para un repositorio Python:

.agents/skills/pytest-regresion/SKILL.md

---
name: pytest-regresion
description: Reproduce y corrige un fallo de pytest cuando hay un test, un stack trace o un comando que falla. No usar para refactors ni cambios de infraestructura.
---

1. Lee AGENTS.md y conserva los cambios no relacionados.
2. Ejecuta el test indicado; si no hay repro, detente y pide el comando exacto.
3. Añade primero un test de regresión mínimo.
4. Modifica solo el módulo que explica el fallo.
5. Ejecuta pytest sobre el test y la suite afectada.
6. Entrega archivos tocados, comando, resultado y riesgos restantes.

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Carga contexto por capas, no por acumulación

La documentación de Codex describe la carga progresiva para que el listado inicial de skills no consuma el contexto del trabajo. Aprovecha ese diseño: en SKILL.md enlaza una referencia solo cuando hay una bifurcación real, como el proveedor cloud, el framework o un protocolo de seguridad. No precargues tres SDKs por si acaso.

Lo que conviene comprobar

Un patrón útil es 'contrato arriba, detalle abajo'. Arriba: entrada esperada, salida, límites, comando de validación y cuándo parar. Abajo: enlaces a references/postgres.md, references/aws.md o una tabla de compatibilidad. Así una tarea de SQLite no lee reglas de producción para Postgres y el agente conserva espacio para inspeccionar tu código.

Mide el fracaso con una señal simple: si los agentes vuelven a pedir instrucciones que ya existen, falta claridad en el contrato. Si empiezan a leer referencias que no usan o ignoran el código local, la skill está cargando demasiado. La solución rara vez es añadir otro documento; normalmente es separar dos workflows que no comparten intención.

Scripts: encapsula lo frágil, no la decisión

Un script es apropiado cuando la secuencia es mecánica y peligrosa de reescribir: inicializar fixtures, recopilar logs redactados, validar un manifiesto o crear un informe. Pide argumentos explícitos y devuelve códigos de salida útiles. No entierres decisiones de arquitectura, despliegues irreversibles o prompts opacos dentro de un helper.

Haz que el script sea seguro ante reintentos. Comprueba precondiciones, usa rutas relativas al repositorio, no imprimas secretos y ofrece --dry-run antes de mutar un recurso externo. Si una skill necesita una base de datos o cloud, separa la fase de observación de la fase de escritura y deja claro qué aprobación hace falta para cada una.

Un buen contrato de script expresa entrada, salida y fallo: collect_failure.py --test tests/api/test_auth.py puede guardar un artefacto local redactado; no debería llamar a producción porque el nombre del test se parece a un incidente. La capacidad reutilizable debe reducir el radio de explosión, no hacerlo más cómodo.

Validación antes de convertirlo en plugin

Prueba la skill en tres casos: el caso feliz, un input incompleto y un repositorio con cambios locales. El caso incompleto debe detenerse con una pregunta concreta; el repositorio sucio debe preservar el trabajo ajeno. Si el procedimiento no tiene una salida segura en esos dos casos, aún no merece automatizarse ni distribuirse.

Mantén una prueba rápida junto a la skill cuando sea viable: valida el frontmatter, comprueba que las rutas referenciadas existen y ejecuta el helper en modo seco. Para un workflow de código, la evidencia mínima incluye el comando ejecutado, código de salida, diff revisable y test de regresión. 'El agente dijo que funciona' no es una verificación.

No evalúes una skill por lo largo que parece el resultado. Evalúala por reducción de retrabajo: menos instrucciones repetidas, menos cambios fuera de alcance, menos intentos fallidos y una revisión humana más rápida. Si sube la velocidad pero nadie entiende qué hizo, has trasladado el coste al reviewer.

De skill local a plugin distribuible

Mantén la skill local mientras el workflow sigue cambiando cada semana. Cuando ya tiene activación estable, validación repetible y usuarios fuera del repositorio, un plugin es la capa de distribución: puede agrupar skills, conectores, MCP, hooks o plantillas de tareas programadas según la documentación de OpenAI.

Distribuir no elimina el threat model. Revisa especialmente hooks, conectores y servidores MCP: pueden introducir ejecución o acceso a sistemas externos. Un plugin debe declarar dependencias y guiar el setup, pero no pedir permisos amplios 'para que funcione'. El usuario debe poder instalar la parte de lectura sin conceder la parte mutante.

No migres a ciegas desde catálogos antiguos. El repositorio openai/skills indica que ahora dirige los ejemplos actuales al repositorio de plugins y a la guía de Build plugins. Usa la documentación actual como fuente de empaquetado y conserva tests de la skill antes de cambiar el canal de distribución.

Errores que convierten una skill en deuda

Descripción genérica que se activa para tareas incompatibles.
Duplicar AGENTS.md y terminar con políticas distintas en cada skill.
Meter documentación extensa en SKILL.md y agotar el contexto antes de mirar el repositorio.
Llamar a scripts con secretos implícitos, rutas absolutas o efectos externos no anunciados.
Confundir metadata de plugin con una barrera de permisos.
No definir condición de parada cuando faltan datos, permisos o un comando de reproducción.
Distribuir el workflow antes de haber probado éxito, fallo seguro y repositorio sucio.

Checklist de publicación interna

El nombre es estable y la descripción expresa tarea, activadores y límites.
SKILL.md contiene entrada, salida, pasos verificables y condición de parada.
Las reglas globales permanecen en AGENTS.md y no se copian sin motivo.
Las referencias grandes se cargan solo cuando una rama del workflow las necesita.
Los scripts aceptan argumentos, no exponen secretos y separan dry-run de escritura.
La skill preserva cambios ajenos y declara qué no puede hacer.
Existe una prueba del caso feliz, del input incompleto y del árbol de trabajo sucio.
Una persona puede revisar comando, diff y resultado sin confiar en una narración del agente.

Preguntas frecuentes

¿Qué es una Codex Skill?

Es un paquete local de instrucciones para un workflow concreto. Incluye como mínimo un directorio y SKILL.md; puede incluir scripts, referencias y assets si aportan una capacidad que no conviene reescribir en cada tarea.

¿Una skill sustituye a AGENTS.md?

No. AGENTS.md gobierna el repositorio y sus reglas duraderas; una skill describe un procedimiento especializado. Usa ambos para que las reglas globales no se dupliquen ni entren en conflicto.

¿Las skills otorgan permisos al agente?

No. La sandbox, las aprobaciones, las credenciales y los controles del host siguen aplicando. Una skill no debe presentarse como una excepción de seguridad.

¿Cuándo debo añadir un script?

Cuando un paso sea mecánico, repetible y verificable. Si encapsula una decisión de producto, un despliegue irreversible o una acción externa amplia, conserva esa decisión fuera del helper y exige aprobación.

¿Cuándo convierto una skill en plugin?

Cuando el workflow ya es estable, tiene validación y necesita instalarse o compartirse entre varios proyectos o equipos. Empieza local: distribuir demasiado pronto fija una mala interfaz.

¿Puedo usar la misma skill en Claude Code y Codex?

El formato SKILL.md pertenece al estándar abierto de Agent Skills, pero la disponibilidad, rutas, metadata y capacidades del host pueden diferir. Verifica el comportamiento y permisos en cada entorno antes de declararla portátil.

Cómo crear una Codex Skill reutilizable y verificable

Elegir una tarea repetida. Selecciona un workflow con entrada, salida y evidencia claras; evita procedimientos que aún dependen de decisiones de arquitectura abiertas.
Escribir el selector. Crea nombre y descripción que expliquen cuándo usar la skill y cuándo no, para impedir activaciones genéricas.
Definir el contrato. En SKILL.md fija pasos, límites, condición de parada y comando de validación; deja AGENTS.md para reglas globales.
Separar el detalle. Mueve documentación grande a references y operaciones mecánicas a scripts con argumentos explícitos.
Aislar efectos. Añade comprobaciones, dry-run y aprobación para operaciones externas; nunca conviertas la skill en un atajo de permisos.
Probar fallos seguros. Ejecuta caso feliz, input incompleto y repositorio con cambios locales; conserva evidencia reproducible.
Medir utilidad. Revisa si reduce reintentos, cambios fuera de alcance y tiempo de revisión, no solo si genera más texto.
Distribuir después. Empaqueta como plugin únicamente cuando activación, dependencias y validación estén estables y documentadas. > ### Límite sano > > Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.