# 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. ## 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 ``` > [!NOTE] > 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ón | Prompt ad-hoc convencional | Codex Skill | | :--- | :--- | :--- | | **Frecuencia de uso** | Tarea exploratoria puntual | Escenario recurrente (diario o antes de cada release) | | **Complejidad del flujo** | 1–2 pasos básicos | Pipeline de múltiples etapas con validaciones intermedias | | **Recursos complementarios** | No necesarios | Requiere scripts auxiliares, manuales de estilo o checklists | | **Requisitos de salida** | Texto libre no estructurado | Estructura formal fija (tabla markdown, esquema JSON) | | **Límites de seguridad** | Configuración de la sesión | Permisos 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. > [!TIP] > **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. ``` > [!IMPORTANT] > **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
'Razonamiento y Protocolo'
Define la lógica, el contexto y la secuencia"] Script["SCRIPT
'Cálculo Determinista'
Ejecuta operaciones rápidas y exactas en disco"] Tool["TOOL (MCP)
'Sentidos y Actuadores'
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 | Componente | Rol en el sistema | Modelo de ejecución | Ejemplo concreto | | :--- | :--- | :--- | :--- | | **Skill** | **Protocolo y toma de decisiones** | Interpretado por el modelo de lenguaje | Guía paso a paso para auditorías de seguridad | | **Script** | **Acción determinista directa** | Ejecutado en la terminal del sistema | Script en Python para extraer etiquetas de versión | | **Tool (MCP)** | **Interfaz de acceso al entorno** | Invocado mediante Tool Calling | Servidor MCP para consultar pull requests en GitHub | > [!NOTE] > 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
(Lectura de archivos, linters)"] Decision -->|Crítica: Escritura / Red| Confirm["Confirmación obligatoria del usuario
(Eliminar archivos, desplegar)"] ``` ### Matriz de niveles de confianza :::tabs @tab Permitido de forma autónoma - Inspección de archivos de código, configuraciones y documentación. - Análisis de registros de compilación y trazas de error en consola. - Ejecución de pruebas unitarias en modo de solo lectura. - Generación de tablas de auditoría y resúmenes de incidencias. @tab Requiere confirmación humana - Edición de archivos de configuración global (`package.json`, `.env`). - Eliminación, reemplazo o sobreescritura de archivos existentes. - Peticiones de red o transmisión de datos a APIs remotas. - Creación de commits o pushes hacia ramas remotas de Git. ::: > [!WARNING] > **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 $ # Invocación determinista explícita /skills # Mostrar las Skills disponibles en la sesión # ─── Ubicación de archivos en el proyecto ───────────────────────── .codex/skills//SKILL.md # Skill a nivel de proyecto (en Git) ~/.codex/skills//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.