Skip to main content
Todas las guías
Contenido de la guía

Contenido de la guía

Tiempo de estudio: 14 min
#ai_agents#codex#skills#workflows#automation#openai
Intermedio14 min

Codex Skills para principiantes: automatización de flujos de trabajo con agentes de IA

Guía práctica para crear y ejecutar Skills en Codex: anatomía de SKILL.md, activación explícita y automática, diferencias entre skills, scripts y tools, Skills API y límites de seguridad.

Publicado:

1. Qué es una Skill en Codex: de prompts puntuales a flujos reutilizables

Durante el desarrollo continuo con Codex, los ingenieros suelen repetir una y otra vez las mismas instrucciones introductorias: qué archivos examinar, qué normas de arquitectura aplicar, qué pruebas ejecutar y cómo formatear el resultado. Tener que reiterar estos requisitos en cada nueva sesión reduce la velocidad de desarrollo e introduce discrepancias involuntarias.

Una Codex Skill (habilidad) es un flujo de trabajo reutilizable y estructurado para una categoría concreta de tareas. Diseñar una Skill no implica reentrenar (fine-tuning) el modelo: los pesos neuronales de la IA permanecen intactos. En su lugar, el agente recibe un protocolo procedural que carga dinámicamente en su ventana de contexto solo cuando surge la tarea correspondiente.

mermaid
flowchart LR subgraph AdHoc ["Enfoque Tradicional (Prompts Manuales)"] User1["Usuario"] -->|Escribe reglas repetitivas en cada turno| Prompt["Prompt Extenso Ad-Hoc"] Prompt --> Agent1["Codex"] end subgraph Modular ["Arquitectura Basada en Skills"] User2["Usuario"] -->|Comando Directo: $code-review| Agent2["Codex"] SkillsDir["Repositorio de Skills (SKILL.md)"] -->|Carga Automática de Protocolos| Agent2 Agent2 --> Output["Resultado Estandarizado"] end
Nota

En el ecosistema oficial de OpenAI, las Skills ya constituyen el estándar para la automatización de flujos. Por ejemplo, al actualizar un proyecto hacia nuevas familias de modelos, OpenAI suministra la Skill openai-docs, que incorpora las novedades del SDK sin necesidad de que el usuario busque y pegue manuales extensos.

2. Criterios de elección: cuándo crear una Skill y cuándo basta un prompt

Una Skill está diseñada principalmente para flujos que presentan una marcada repetibilidad, una secuencia procedimental estricta o requisitos formales de entrega.

Criterio de evaluaciónPrompt ad-hoc convencionalCodex Skill
Frecuencia de usoTarea exploratoria puntualEscenario recurrente (diario o antes de cada release)
Complejidad del flujo1–2 pasos básicosPipeline de múltiples etapas con validaciones intermedias
Recursos complementariosNo necesariosRequiere scripts auxiliares, manuales de estilo o checklists
Requisitos de salidaTexto libre no estructuradoEstructura formal fija (tabla markdown, esquema JSON)
Límites de seguridadConfiguración de la sesiónPermisos estrictamente definidos (solo lectura vs. escritura)

Casos de uso ideales para una Skill

  • Auditoría previa al despliegue: Ejecución de linters, detección de sentencias residuales de depuración (console.log, TODO) y validación de tipos TypeScript.
  • Revisión estandarizada de pull requests: Validación de directrices de arquitectura sin aplicar modificaciones no autorizadas en el código.
  • Compilación de notas de versión: Extracción de pull requests fusionados, categorización semántica y actualización de CHANGELOG.md.
  • Modernización de componentes: Migración paso a paso de patrones obsoletos conforme a plantillas corporativas.
Consejo

La regla de tres del desarrollador: Si se encuentra explicando por tercera vez a Codex la misma secuencia de instrucciones («primero lee este archivo, luego ejecuta este test, no modifiques nada y presenta el resultado en una tabla»), es el momento exacto de empaquetar ese flujo en una Skill.

3. Mecánica de activación: llamada explícita con $name vs. emparejamiento automático

Codex admite dos mecanismos complementarios para activar habilidades: la invocación directa por parte del usuario y el emparejamiento semántico autónomo.

Invocación explícita

El usuario referencia directamente la habilidad anteponiendo el símbolo de dólar $ a su nombre:

bash
$code-review revisa los cambios recientes en feature/auth

Esta modalidad garantiza una predictibilidad total: Codex activa de inmediato la Skill indicada, adopta sus instrucciones como guía prioritaria y las aplica a los argumentos de la solicitud.

Emparejamiento semántico automático

Si no se indica el prefijo $name, Codex analiza el texto del usuario y lo compara con los campos description de todas las habilidades disponibles:

mermaid
flowchart TD Req["Prompt: 'Prepara las notas de versión para v2.1.0'"] --> Router{"Enrutador Semántico de Intención"} Router -->|Coincidencia: description release-notes| LoadSkill["Carga .codex/skills/release-notes/SKILL.md"] Router -->|Sin coincidencia| Standard["Turno de chat convencional sin Skill"] LoadSkill --> Exec["Ejecución del Pipeline Estandarizado"]
text
Descripción precisa (alta tasa de activación correcta): description: Audita archivos modificados en busca de regresiones, errores de tipo y estilo antes del release. Usar en revisiones de PR. Descripción ambigua (señal débil): description: Ayuda a los desarrolladores a escribir mejor software.

4. Anatomía de una Skill y estructura de SKILL.md: metadatos y recursos

Una Skill mínima está compuesta únicamente por el archivo SKILL.md. Los flujos más completos pueden incorporar scripts auxiliares, guías de referencia y plantillas dentro de su carpeta.

text
project-review/ ├── SKILL.md # Archivo central (metadatos + instrucciones) ├── scripts/ └── check-deps.sh # Script para comprobaciones automáticas ├── references/ └── styleguide.md # Manual de estilo del equipo └── templates/ └── report-template.md # Plantilla para el informe final

Anatomía de SKILL.md

El documento se divide en dos bloques: un encabezado YAML Frontmatter al inicio y las directrices procedimentales en Markdown.

markdown
--- name: project-review description: Realiza auditorías de código previas al release, valida tipos TypeScript y genera informes sin modificar el código fuente. --- Instrucciones de auditoría: 1. Ejecutar "npm run typecheck" para detectar errores de compilación. 2. Analizar el git diff respecto a la rama principal main. 3. Clasificar los hallazgos en tres niveles: Crítico, Advertencia, Sugerencia. 4. Queda estrictamente prohibido modificar archivos de forma autónoma. 5. Formatear el resumen final conforme a templates/report-template.md.
Importante

Principio de concisión: Evite sobrecargar SKILL.md con explicaciones teóricas extensas. Cuanto más directo y estructurado sea el texto, menos espacio ocupará en la ventana de contexto y con mayor fidelidad seguirá el agente las instrucciones.

5. Ámbitos de almacenamiento: Skills de proyecto vs. Skills personales globales

Codex clasifica las habilidades en dos ámbitos de almacenamiento según su alcance operativo:

mermaid
flowchart TD subgraph GlobalScope ["Skills Globales Personales (~/.codex/skills/)"] G1["Formateador personal de mensajes de commit"] G2["Generador rápido de cabeceras de licencia"] end subgraph ProjectScope ["Skills a Nivel de Proyecto (.codex/skills/)"] P1["Linter de arquitectura del repositorio"] P2["Generador de migraciones de base de datos"] P3["Lista de verificación para despliegues a producción"] end Dev["Desarrollador"] -->|Preferencias individuales| GlobalScope Team["Equipo en Git"] -->|Estándares compartidos| ProjectScope

Skills a nivel de proyecto (.codex/skills/ o .agents/skills/)

Ubicadas en la raíz del repositorio y controladas mediante Git.

  • Propósito: Estandarización de procesos para todo el equipo de desarrollo.
  • Ventaja: Cualquier desarrollador o runner de CI/CD que clone el repositorio dispone de las mismas herramientas de inmediato.

Skills personales globales (~/.codex/skills/)

Alojadas en el directorio personal del usuario del sistema operativo.

  • Propósito: Flujos de trabajo individuales de productividad del desarrollador.
  • Ventaja: Disponibles en cualquier proyecto y terminal de la máquina de trabajo.

6. Taller práctico: creación de una Skill de revisión con $skill-creator

La vía más rápida para crear una nueva habilidad consiste en emplear la herramienta integrada $skill-creator de Codex.

Paso 1. Iniciar el asistente de creación

En su sesión de Codex, introduzca:

bash
$skill-creator

A continuación, describa el flujo de trabajo deseado en lenguaje natural:

text
Crea una Skill de proyecto llamada "pr-validator". Objetivo: validar archivos modificados en el pull request actual. Reglas: 1. Ejecutar npm run lint y npm test. 2. Comprobar si los módulos nuevos en src/ incluyen pruebas unitarias. 3. Prohibir al agente modificar archivos de código de forma autónoma. 4. Presentar los resultados en una tabla: Archivo, Línea, Problema, Severidad.

Paso 2. Comprobar los archivos generados

El asistente generará la carpeta .codex/skills/pr-validator/ con su archivo SKILL.md:

markdown
--- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity |

Paso 3. Probar la Skill en una sesión limpia

Inicie una nueva sesión de Codex y pruebe la habilidad registrada:

bash
$pr-validator revisa mi rama antes de abrir el pull request

Verifique que el agente ejecute los comandos de prueba, no altere los archivos de trabajo y devuelva el formato de tabla solicitado.

7. La tríada operativa del agente: Skill, Script y Tool

Es común confundir las nociones de Skill, Script y Tool (MCP). Cada elemento cumple una función técnica distinta y complementaria.

mermaid
flowchart TD subgraph Triad ["Tríada de Capacidades del Agente"] Skill["SKILL<br><i>'Razonamiento y Protocolo'</i><br>Define la lógica, el contexto y la secuencia"] Script["SCRIPT<br><i>'Cálculo Determinista'</i><br>Ejecuta operaciones rápidas y exactas en disco"] Tool["TOOL (MCP)<br><i>'Sentidos y Actuadores'</i><br>Proporciona acceso a APIs, terminal y bases de datos"] end Skill -->|Orquesta| Script Skill -->|Utiliza| Tool Script -->|Se ejecuta vía| Tool

Tabla comparativa de la tríada

ComponenteRol en el sistemaModelo de ejecuciónEjemplo concreto
SkillProtocolo y toma de decisionesInterpretado por el modelo de lenguajeGuía paso a paso para auditorías de seguridad
ScriptAcción determinista directaEjecutado en la terminal del sistemaScript en Python para extraer etiquetas de versión
Tool (MCP)Interfaz de acceso al entornoInvocado mediante Tool CallingServidor MCP para consultar pull requests en GitHub
Nota

Una Skill define qué hacer y en qué orden. Un Script procesa tareas mecánicas sin consumir tokens innecesarios. Una Tool otorga los permisos necesarios para interactuar con plataformas externas.

8. Gestión programática mediante Skills API y versionado

Además de los archivos locales, OpenAI ofrece una Skills API para administrar habilidades de forma programática en aplicaciones en la nube y arquitecturas de agentes empresariales.

bash
# Creación de una Skill vía API HTTP curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Valida y genera migraciones de base de datos seguras", "instructions": "Verifica el esquema Prisma y confirma que no existan drop column destructivos..." }'

Ventajas del versionado de Skills:

  1. Inmutabilidad en entornos de producción: Cada actualización genera una nueva versión (v1, v2). Los flujos de CI/CD quedan vinculados a versiones fijas, evitando roturas inesperadas.
  2. Reversión instantánea (Rollback): Si un ajuste en las instrucciones produce regresiones, el equipo puede regresar a la versión previa inmediatamente.
  3. Pruebas A/B de prompts: Comparación de dos redacciones alternativas para evaluar tasas de éxito y consumo de tokens.

9. Seguridad, límites de autonomía y reglas de confirmación

Una Skill orienta de forma directa las acciones que el agente ejecuta en el equipo. Por este motivo, el texto debe distinguir con claridad las operaciones autónomas de las acciones destructivas.

mermaid
flowchart LR Action["Acción del Agente"] --> Decision{"Evaluación de Riesgo"} Decision -->|Segura: Solo Lectura| Auto["Ejecución autónoma sin pausas<br><i>(Lectura de archivos, linters)</i>"] Decision -->|Crítica: Escritura / Red| Confirm["Confirmación obligatoria del usuario<br><i>(Eliminar archivos, desplegar)</i>"]

Matriz de niveles de confianza

Atención

Evite la reiteración excesiva de restricciones: No repita frases como «no modifiques nada» en cada punto de las instrucciones. Definir las limitaciones de forma clara en un apartado específico previene que el agente se vuelva hiperpasivo y solicite permisos innecesarios para lecturas básicas.

10. Cuaderno de referencia y lista de verificación para producción

Consulte esta guía rápida al diseñar o auditar nuevas Skills en Codex.

Referencia rápida de comandos CLI

bash
# ─── Gestión de Skills en Codex ─────────────────────────────────── $skill-creator # Iniciar el asistente interactivo de creación $<nombre-skill> <descripción tarea> # Invocación determinista explícita /skills # Mostrar las Skills disponibles en la sesión # ─── Ubicación de archivos en el proyecto ───────────────────────── .codex/skills/<name>/SKILL.md # Skill a nivel de proyecto (en Git) ~/.codex/skills/<name>/SKILL.md # Skill personal global (en la máquina)

Lista de verificación previa al despliegue

  • Nombre en formato kebab-case: Menos de 64 caracteres, en minúsculas y separado por guiones ([a-z0-9-]).
  • Descripción con doble propósito: Especifica con claridad qué realiza la Skill y cuándo activarla.
  • Cuerpo sintético: SKILL.md no excede las 500 líneas y aborda exclusivamente la lógica del proyecto.
  • Flujo secuencial ordenado: Los pasos de ejecución están numerados (1., 2., 3.) para eliminar ambigüedades.
  • Límites de seguridad establecidos: Queda determinado qué archivos son de lectura libre y qué acciones exigen confirmación.
  • Validación en sesión limpia: Probada satisfactoriamente tanto con $name como mediante activación automática.
Esta guía es completamente gratuita. Si te ahorró una noche, puedes apoyar el crecimiento del proyecto.
Apoyar al autor