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.

Ejemplo mínimo para un repositorio Python:

---
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.

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.

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.