Creador de Skills
Crea skills que proporcionen a Codex orientación útil y no obvia sin restringir trabajo no relacionado.
Principios Fundamentales
Asume que Codex ya es capaz. Incluye solo información que cambie sus decisiones o mejore su trabajo. Elimina consejos genéricos, instrucciones repetidas, casos límite especulativos y ejemplos que no aclaren materialmente la tarea.
Preserva la intención y el alcance del usuario. Un skill debe respaldar la tarea solicitada, no reemplazar el producto elegido por el usuario, ampliar la asignación, modificar la configuración no relacionada ni implicar permiso para acciones externas adicionales. No conviertas un ejemplo particular, un fracaso pasado o una preferencia personal en un requisito universal.
La aprobación para completar una tarea no expande su alcance ni los permisos de ejecución. Para flujos de trabajo de reintento o mutación externa, define una condición de detención proporcional al riesgo.
Iguala la especificidad al riesgo. Dale al modelo espacio para elegir un enfoque apropiado cuando múltiples enfoques sean razonables. Usa pasos detallados, scripts deterministas o lenguaje absoluto solo cuando la corrección, seguridad, permisos o un flujo de trabajo genuinamente frágil lo requieran.
Para trabajo abierto, describe el resultado y los criterios de decisión relevantes. Para flujos de trabajo con una forma preferida, ofrece ejemplos útiles o scripts configurables. Reserva secuencias fijas y parámetros estrechos para operaciones donde la desviación causaría un problema concreto. Preserva invariantes operativas no obvias, distingue los requisitos reales de las recomendaciones opcionales o convenciones locales, y evita repetir políticas ya aplicadas en otro lugar.
Mantén el descubrimiento barato y preciso. Los nombres y descripciones de los skills están disponibles antes de que se cargue un skill. Describe la capacidad real y cuándo se aplica, agregando exclusiones solo cuando prevengan un enrutamiento incorrecto probable. Evita listas exhaustivas de capacidades y términos generales que atraigan solicitudes no relacionadas.
Mantén los skills autocontenidos; refiérete a otro skill o herramienta solo cuando el flujo de trabajo solicitado lo requiera genuinamente y esté disponible en el entorno de destino. Los flujos de trabajo especializados de revisión, endurecimiento o auditoría deben aplicarse cuando se soliciten o sean realmente necesarios, no meramente porque el trabajo ordinario toque el mismo tema.
Revela los detalles progresivamente. Mantén el propósito compartido, las restricciones esenciales y el enrutamiento útil en SKILL.md. Coloca guías sustanciales específicas del modo, esquemas, ejemplos o procedimientos en referencias de soporte y lee solo las referencias relevantes para la tarea actual. Un skill simple y autocontenido no necesita un enrutador ni archivos adicionales.
Anatomía de un Skill
Cada skill es una carpeta que contiene un archivo SKILL.md obligatorio y cualquier recurso opcional que su flujo de trabajo real necesite:
skill-name/
|-- SKILL.md Instrucciones obligatorias del skill
| |-- Frontmatter YAML Nombre y descripción obligatorios
| `-- Cuerpo Markdown Instrucciones cargadas cuando se usa el skill
|-- agents/ Metadatos opcionales de UI y política de invocación
| `-- openai.yaml
|-- scripts/ Ayudantes ejecutables opcionales
|-- references/ Documentación opcional cargada según sea necesario
`-- assets/ Archivos opcionales utilizados en la salida generada
Elige la estructura que se ajuste a la tarea real. Algunos skills son cortos y autocontenidos; otros enrutan entre modos de operación o delegan mecánicas complejas a scripts. Evita crear directorios, marcadores de posición, ejemplos o documentación auxiliar sin un uso claro.
SKILL.md
El frontmatter YAML identifica el skill y determina cuándo debe considerarse. Incluye el name y description obligatorios, y conserva los campos opcionales admitidos, como metadata existente, cuando sea apropiado.
El cuerpo Markdown se carga solo cuando se usa el skill. Coloca allí el propósito, el flujo de trabajo esencial, las restricciones reales y los enlaces útiles. Mantén procedimientos detallados y ejemplos en referencias de soporte cuando sean relevantes solo para modos particulares.
La información del skill se divulga en tres etapas:
- Nombre y descripción: Disponibles durante la selección del skill, así que mantenlos concisos y discriminatorios.
- Cuerpo de SKILL.md: Se carga cuando el skill se aplica, así que mantén sus instrucciones relevantes para esa tarea.
- Recursos de soporte: Se leen o ejecutan solo cuando la tarea actual realmente los necesita.
El punto de entrada debe ser tan corto como la tarea lo permita, manteniendo las restricciones importantes. Un límite superior grande no es un objetivo: mueve detalles condicionales a referencias cuando eso mejore la claridad o el uso del contexto, en lugar de esperar a que el archivo se vuelva difícil de manejar.
Scripts
Usa scripts/ para código ejecutable cuando la misma lógica se reescribiría repetidamente o la ejecución determinista mejora materialmente la confiabilidad.
- Ejemplo:
scripts/rotate_pdf.pypara una operación PDF que de otro modo requeriría recrear el mismo código. - Útil para: Transformaciones repetidas, operaciones confiables de API, procesamiento de datos y otra automatización concreta.
- Validación: Ejecuta scripts nuevos o modificados para verificar su comportamiento. Los scripts generalmente se pueden ejecutar sin cargar su implementación completa en el contexto, aunque un agente puede necesitar inspeccionarlos al parchearlos o adaptarlos.
Referencias
Usa references/ para documentación que solo se necesita en contextos particulares.
- Ejemplos:
references/schema.mdpara tablas de base de datos,references/policies.mdpara reglas de dominio,references/api_docs.mdpara una API, o guías de escritura separadas para diferentes entregables. - Útil para: Esquemas, documentación de API, políticas de empresa, procedimientos específicos de formato, flujos de trabajo detallados y ejemplos sustanciales.
- Enrutamiento: Enlaza cada referencia desde
SKILL.mdu otro recurso relevante y explica cuándo debe leerse. Mantén la información en un solo lugar en lugar de duplicarla en el punto de entrada y las referencias.
Mantén las referencias enfocadas en información mantenida y específica de la tarea que cambie las decisiones del agente. Evita manuales copiados, catálogos exhaustivos y tutoriales genéricos ya disponibles de fuentes autorizadas. Antes de eliminar recursos existentes, inspecciona sus llamadores y propósito.
Para referencias grandes, incluye términos de búsqueda útiles o una breve sección de contenido cuando eso facilite encontrar el material necesario.
Activos
Usa assets/ para archivos que pertenecen a la salida generada en lugar de a las instrucciones del modelo.
- Ejemplos:
assets/logo.png,assets/slides.pptx,assets/font.ttfoassets/frontend-template/. - Útil para: Plantillas, imágenes, fuentes, iconos, proyectos repetitivos y otros archivos copiados o adaptados en el resultado.
- Contexto: No cargues activos como instrucciones a menos que la tarea requiera inspeccionarlos.
Metadatos de UI y Política de Invocación
agents/openai.yaml puede proporcionar metadatos orientados a la UI como display_name, short_description y default_prompt, junto con la política de invocación. Al crear o actualizar esas configuraciones, lee references/openai_yaml.md y mantén los valores consistentes con el skill.
La selección automática de skills está permitida por defecto. Cambia ese valor predeterminado solo cuando el usuario solicite explícitamente un skill de solo invocación explícita:
policy:
allow_implicit_invocation: false
Esto mantiene el skill disponible cuando se invoca explícitamente como $skill-name sin agregarlo al contexto del modelo automáticamente. Conserva los campos de UI, política y dependencias no relacionados existentes al actualizar agents/openai.yaml.
El inicializador crea este archivo automáticamente. Para metadatos nuevos o solo de interfaz, genéralo con:
scripts/generate_openai_yaml.py <ruta/a/la-carpeta-del-skill> --interface clave=valor
El generador reemplaza el archivo completo. Si un archivo existente contiene policy o dependencies, actualiza solo los campos previstos en su lugar en lugar de regenerarlo.
Incluye campos de interfaz opcionales solo cuando el usuario los proporcione o los solicite.
Qué No Incluir
Incluye archivos que respalden directamente el trabajo del skill. Evita agregar un README.md, guía de instalación, registro de cambios, referencia rápida duplicada u otra documentación auxiliar a menos que una tarea específica o requisito de empaquetado lo requiera.
Divulgación Progresiva en la Práctica
Para un skill con múltiples modos sustanciales, mantén la guía compartida y los criterios de selección de modo en SKILL.md. Enlaza cada referencia de soporte donde su uso sea relevante. No cargues cada referencia por defecto, dupliques contenido de referencia en el punto de entrada ni agregues una capa de enrutamiento cuando no haya nada significativo que enrutar.
Por ejemplo, un skill de despliegue puede mantener la selección del proveedor en SKILL.md y separar los detalles del proveedor:
cloud-deploy/
|-- SKILL.md
`-- references/
|-- aws.md
|-- gcp.md
`-- azure.md
Cuando el usuario elija AWS, lee references/aws.md; no cargues también las guías de GCP y Azure. El mismo patrón puede separar dominios de negocio, tipos de entregables u otros modos de operación genuinamente distintos.
Un skill corto puede en su lugar enrutar a detalles solo cuando una operación avanzada los necesite:
## Documentos
Maneja las ediciones ordinarias directamente.
- Para cambios controlados, lee [references/redlining.md](references/redlining.md).
- Para aspectos internos del documento, lee [references/ooxml.md](references/ooxml.md).
Estos ejemplos ilustran opciones, no una estructura requerida. Elige la organización que haga que el skill sea más fácil de usar sin cargar material irrelevante.
Crear o Actualizar un Skill
Adapta el trabajo a la solicitud. Crear un skill nuevo complejo puede implicar comprender casos de uso realistas, elegir recursos de soporte, inicializar archivos, escribir instrucciones y validar el resultado. Una actualización limitada de un skill existente puede requerir solo una edición enfocada y validación.
Haz preguntas aclaratorias solo cuando la información faltante sea importante y no pueda inferirse razonablemente. Respeta la ubicación especificada por el usuario; de lo contrario, crea skills detectables en $CODEX_HOME/skills, o ~/.codex/skills cuando CODEX_HOME no esté establecido.
Mantén la selección automática de skills habilitada a menos que el usuario solicite explícitamente un skill de solo invocación explícita. Cuando el modo de invocación previsto no esté claro y sea importante para el flujo de trabajo solicitado, pregunta si el usuario desea detección automática normal o invocación explícita; de lo contrario, conserva el valor predeterminado. No infieras invocación explícita a partir de operaciones sensibles o aprobaciones requeridas: mantén el skill detectable y requiere autorización inmediatamente antes de la mutación real. Conserva la política de invocación de un skill existente a menos que el usuario pida cambiarla.
Para un skill nuevo o sustancialmente revisado, considera las solicitudes reales que debería manejar y qué recursos reutilizables mejorarían esas tareas:
- Una transformación PDF repetida puede justificar un ayudante
scripts/rotate_pdf.py. - Un flujo de trabajo de creación de aplicaciones puede beneficiarse de un iniciador
assets/frontend-template/. - Un skill de análisis de datos puede necesitar una guía
references/schema.mdpara evitar redescubrir relaciones de tablas.
Crea esos recursos solo cuando su beneficio concreto los justifique. Si el usuario ya ha explicado la tarea claramente, procede sin solicitar ejemplos adicionales.
Nomenclatura
- Usa letras minúsculas, dígitos y guiones.
- Mantén los nombres por debajo de 64 caracteres y prefiere nombres cortos orientados a la acción.
- Espacio de nombres por herramienta o dominio cuando eso mejore la detección.
- Nombra la carpeta del skill como el skill.
Inicializar un Nuevo Skill
Para un skill nuevo, usa el inicializador incluido cuando ayude a crear los archivos requeridos de manera consistente:
scripts/init_skill.py <nombre-del-skill> --path <directorio-de-salida> [--resources scripts,references,assets] [--examples]
Por ejemplo:
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references
Solicita solo los directorios de recursos que el skill necesite. Usa --examples solo cuando los marcadores de posición concretos ayuden, y reemplázalos o elimínalos antes de terminar. No inicialices un skill existente de nuevo.
El inicializador crea el directorio del skill, un iniciador conciso de SKILL.md y agents/openai.yaml. Crea directorios de recursos y archivos de ejemplo solo cuando se soliciten. Pasa valores de UI generados como --interface clave=valor cuando sea necesario.
Escribir las Instrucciones
La description del frontmatter debe explicar brevemente qué hace el skill y cuándo se aplica. Incluye un límite significativo cuando solicitudes similares no deban activar el skill.
Por ejemplo:
description: Crear o editar documentos de Word cuando el formato, los cambios controlados o los comentarios requieran un manejo específico del documento.
Coloca flujos de trabajo detallados, elecciones de herramientas, ejemplos y modos de operación en el cuerpo o referencias relevantes en lugar de enumerarlos todos en la descripción. Conserva el frontmatter opcional admitido, como metadata existente, cuando sea apropiado.
Escribe solo las instrucciones necesarias para que otra instancia de Codex realice bien la tarea. Indica el resultado deseado, el contexto no obvio, las restricciones reales y las referencias o herramientas relevantes. Preserva las elecciones explícitas del usuario y los límites de autorización existentes. Evita prescribir una estructura fija, proceso o número de pasos cuando la tarea no lo requiera.
Validar e Iterar
Valida el skill completado con:
scripts/quick_validate.py <ruta/a/la-carpeta-del-skill>
El validador verifica el frontmatter, la nomenclatura y los marcadores de posición de andamio sin terminar; no prueba que el skill tome buenas decisiones. También verifica que las descripciones sigan siendo discriminatorias, las instrucciones preserven la intención del usuario, las referencias sean detectables y cualquier script agregado funcione realmente.
Cuando las pruebas estén justificadas, verifica el comportamiento observable o los invariantes significativos. Evita pruebas que solo coincidan con la redacción generada, los encabezados o los patrones de expresiones regulares.
Mejora el skill basándote en el uso real o fallas demostradas. Prefiere una corrección limitada a acumular reglas universales para cada problema potencial. Antes de agregar un nuevo consejo, un requisito más estricto o un nuevo bloque de ejemplo, considera si las instrucciones actuales son insuficientes o si la falla proviene de una falta de comprensión de las capacidades existentes.
Resumen
Un skill es una carpeta con un SKILL.md y recursos de soporte opcionales. El nombre y la descripción determinan cuándo se considera. El cuerpo del markdown se carga cuando se usa. Las referencias, scripts y activos se cargan según sea necesario. Escribe lo mínimo que cambie el comportamiento de manera útil. Conserva lo que sea útil y elimina lo que no.