grahama1970/skill-creator

Creador de Skills

Este skill proporciona orientación para crear skills efectivos.

Acerca de los Skills

Los skills son carpetas modulares y autónomas que extienden las capacidades de Codex al proporcionar conocimiento especializado, flujos de trabajo y herramientas. Piense en ellos como "guías de incorporación" para dominios o tareas específicas: transforman a Codex de un agente de propósito general a un agente especializado equipado con conocimiento procedimental que ningún modelo puede poseer por completo.

Qué Proporcionan los Skills

1. Flujos de trabajo especializados - Procedimientos de varios pasos para dominios específicos
2. Integraciones de herramientas - Instrucciones para trabajar con formatos de archivo o APIs específicos
3. Experiencia en el dominio - Conocimiento específico de la empresa, esquemas, lógica de negocio
4. Recursos empaquetados - Scripts, referencias y activos para tareas complejas y repetitivas

Principios Fundamentales

La Concisión es Clave

La ventana de contexto es un bien público. Los skills comparten la ventana de contexto con todo lo demás que Codex necesita: el prompt del sistema, el historial de la conversación, los metadatos de otros skills y la solicitud real del usuario.

Suposición predeterminada: Codex ya es muy inteligente. Solo agregue contexto que Codex aún no tenga. Desafíe cada pieza de información: "¿Codex realmente necesita esta explicación?" y "¿Este párrafo justifica su costo de tokens?"

Prefiera ejemplos concisos sobre explicaciones extensas.

Establezca el Nivel Adecuado de Libertad

Haga coincidir el nivel de especificidad con la fragilidad y variabilidad de la tarea:

• Alta libertad (instrucciones basadas en texto): Úselo cuando múltiples enfoques sean válidos, las decisiones dependan del contexto o los heurísticos guíen el enfoque.
• Libertad media (pseudocódigo o scripts con parámetros): Úselo cuando exista un patrón preferido, se acepte cierta variación, o la configuración afecte el comportamiento.
• Baja libertad (scripts específicos, pocos parámetros): Úselo cuando las operaciones sean frágiles y propensas a errores, la consistencia sea crítica o se deba seguir una secuencia específica.

Piense en Codex como explorando un camino: un puente estrecho con acantilados necesita barandillas específicas (baja libertad), mientras que un campo abierto permite muchas rutas (alta libertad).

Proteja la Integridad de la Validación

Puede usar subagentes durante la iteración para validar si un skill funciona en tareas realistas o si un problema sospechado es real. Esto es más útil cuando desea una verificación independiente del comportamiento, las salidas o los modos de falla del skill después de una revisión. Solo haga esto cuando sea posible iniciar nuevos subagentes.

Al usar subagentes para la validación, trátelo como una superficie de evaluación. El objetivo es aprender si el skill se generaliza, no si otro agente puede reconstruir la respuesta a partir de contexto filtrado.

Prefiera artefactos sin procesar, como prompts de ejemplo, salidas, diferencias (diffs), registros (logs) o trazas. Proporcione el contexto mínimo necesario para la tarea de validación. Evite pasar la respuesta prevista, el error sospechado, la corrección prevista o sus conclusiones anteriores, a menos que la validación lo requiera explícitamente.

Anatomía de un Skill

Cada skill consta de un archivo SKILL.md obligatorio y recursos empaquetados opcionales:

nombre-del-skill/
├── SKILL.md (obligatorio)
│   ├── Metadatos frontmatter YAML (obligatorio)
│   │   ├── name: (obligatorio)
│   │   └── description: (obligatorio)
│   └── Instrucciones en Markdown (obligatorio)
├── agents/ (recomendado)
│   └── openai.yaml - Metadatos de la interfaz de usuario para listas de skills y chips
└── Recursos empaquetados (opcional)
    ├── scripts/          - Código ejecutable (Python/Bash/etc.)
    ├── references/       - Documentación destinada a cargarse en el contexto según sea necesario
    └── assets/           - Archivos utilizados en la salida (plantillas, íconos, fuentes, etc.)

SKILL.md (obligatorio)

Cada SKILL.md consta de:

• Frontmatter (YAML): Contiene los campos name y description. Estos son los únicos campos que Codex lee para determinar cuándo se usa el skill, por lo que es muy importante ser claro y completo al describir qué es el skill y cuándo debe usarse.
• Cuerpo (Markdown): Instrucciones y orientación para usar el skill. Solo se carga DESPUÉS de que el skill se activa (si es que se activa).

Metadatos de agents (recomendado)

• Metadatos orientados a la interfaz de usuario para listas de skills y chips
• Lea references/openai_yaml.md antes de generar valores y siga sus descripciones y restricciones
• Cree: display_name, short_description y default_prompt orientados al usuario leyendo el skill
• Genere de forma determinista pasando los valores como --interface key=value a scripts/generate_openai_yaml.py o scripts/init_skill.py
• En actualizaciones: valide que agents/openai.yaml aún coincida con SKILL.md; regenere si está obsoleto
• Solo incluya otros campos de interfaz opcionales (íconos, color de marca) si se proporcionan explícitamente
• Consulte references/openai_yaml.md para definiciones de campos y ejemplos

Recursos Empaquetados (opcional)

Scripts (scripts/)

Código ejecutable (Python/Bash/etc.) para tareas que requieren confiabilidad determinista o se reescriben repetidamente.

• Cuándo incluir: Cuando el mismo código se reescribe repetidamente o se necesita confiabilidad determinista
• Ejemplo: scripts/rotate_pdf.py para tareas de rotación de PDF
• Beneficios: Eficiente en tokens, determinista, puede ejecutarse sin cargarse en el contexto
• Nota: Es posible que Codex aún necesite leer los scripts para parchearlos o realizar ajustes específicos del entorno

Referencias (references/)

Documentación y material de referencia destinado a cargarse según sea necesario en el contexto para informar el proceso y el pensamiento de Codex.

• Cuándo incluir: Para documentación que Codex debe consultar mientras trabaja
• Ejemplos: references/finance.md para esquemas financieros, references/mnda.md para la plantilla de NDA de la empresa, references/policies.md para políticas de la empresa, references/api_docs.md para especificaciones de API
• Casos de uso: Esquemas de bases de datos, documentación de API, conocimiento del dominio, políticas de la empresa, guías de flujo de trabajo detalladas
• Beneficios: Mantiene SKILL.md ligero, se carga solo cuando Codex determina que es necesario
• Mejores prácticas: Si los archivos son grandes (>10,000 palabras), incluya patrones de búsqueda grep en SKILL.md
• Evite la duplicación: La información debe residir en SKILL.md o en archivos de referencias, no en ambos. Prefiera archivos de referencias para información detallada a menos que sea verdaderamente central para el skill; esto mantiene SKILL.md ligero y hace que la información sea descubrible sin acaparar la ventana de contexto. Mantenga solo instrucciones procedimentales esenciales y guía de flujo de trabajo en SKILL.md; mueva material de referencia detallado, esquemas y ejemplos a archivos de referencias.

Activos (assets/)

Archivos que no están destinados a cargarse en el contexto, sino a usarse en la salida que Codex produce.

• Cuándo incluir: Cuando el skill necesita archivos que se usarán en la salida final
• Ejemplos: assets/logo.png para activos de marca, assets/slides.pptx para plantillas de PowerPoint, assets/frontend-template/ para código repetitivo HTML/React, assets/font.ttf para tipografía
• Casos de uso: Plantillas, imágenes, íconos, código repetitivo, fuentes, documentos de muestra que se copian o modifican
• Beneficios: Separa los recursos de salida de la documentación, permite que Codex use archivos sin cargarlos en el contexto

Qué No Incluir en un Skill

Un skill solo debe contener archivos esenciales que apoyen directamente su funcionalidad. NO cree documentación adicional o archivos auxiliares, incluyendo:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• etc.

El skill solo debe contener la información necesaria para que un agente de IA realice el trabajo en cuestión. No debe contener contexto auxiliar sobre el proceso de creación, procedimientos de configuración y prueba, documentación orientada al usuario, etc. Crear archivos de documentación adicionales solo agrega desorden y confusión.

Principio de Diseño de Divulgación Progresiva

Los skills utilizan un sistema de carga de tres niveles para gestionar el contexto de manera eficiente:

1. Metadatos (name + description) - Siempre en contexto (~100 palabras)
2. Cuerpo de SKILL.md - Cuando el skill se activa (<5,000 palabras)
3. Recursos empaquetados - Según lo necesite Codex (Ilimitado porque los scripts se pueden ejecutar sin leerlos en la ventana de contexto)

Patrones de Divulgación Progresiva

Mantenga el cuerpo de SKILL.md en lo esencial y por debajo de 500 líneas para minimizar la hinchazón del contexto. Divida el contenido en archivos separados cuando se acerque a este límite. Al dividir el contenido en otros archivos, es muy importante referenciarlos desde SKILL.md y describir claramente cuándo leerlos, para asegurarse de que el lector del skill sepa que existen y cuándo usarlos.

Principio clave: Cuando un skill admita múltiples variaciones, marcos u opciones, mantenga solo el flujo de trabajo central y la guía de selección en SKILL.md. Mueva los detalles específicos de la variante (patrones, ejemplos, configuración) a archivos de referencia separados.

Patrón 1: Guía de alto nivel con referencias

# Procesamiento de PDF

## Inicio rápido

Extraiga texto con pdfplumber:
[código de ejemplo]

## Funciones avanzadas

- **Relleno de formularios**: Consulte [FORMS.md](FORMS.md) para una guía completa
- **Referencia de API**: Consulte [REFERENCE.md](REFERENCE.md) para todos los métodos
- **Ejemplos**: Consulte [EXAMPLES.md](EXAMPLES.md) para patrones comunes

Codex carga FORMS.md, REFERENCE.md o EXAMPLES.md solo cuando es necesario.

Patrón 2: Organización específica por dominio

Para skills con múltiples dominios, organice el contenido por dominio para evitar cargar contexto irrelevante:

bigquery-skill/
├── SKILL.md (descripción general y navegación)
└── reference/
    ├── finance.md (métricas de ingresos, facturación)
    ├── sales.md (oportunidades, pipeline)
    ├── product.md (uso de API, funciones)
    └── marketing.md (campañas, atribución)

Cuando un usuario pregunta sobre métricas de ventas, Codex solo lee sales.md.

De manera similar, para skills que admiten múltiples marcos o variantes, organice por variante:

cloud-deploy/
├── SKILL.md (flujo de trabajo + selección de proveedor)
└── references/
    ├── aws.md (patrones de despliegue en AWS)
    ├── gcp.md (patrones de despliegue en GCP)
    └── azure.md (patrones de despliegue en Azure)

Cuando el usuario elige AWS, Codex solo lee aws.md.

Patrón 3: Detalles condicionales

Muestre contenido básico, enlace al contenido avanzado:

# Procesamiento de DOCX

## Creación de documentos

Use docx-js para documentos nuevos. Consulte [DOCX-JS.md](DOCX-JS.md).

## Edición de documentos

Para ediciones simples, modifique el XML directamente.

**Para cambios controlados**: Consulte [REDLINING.md](REDLINING.md)
**Para detalles de OOXML**: Consulte [OOXML.md](OOXML.md)

Codex lee REDLINING.md o OOXML.md solo cuando el usuario necesita esas funciones.

Directrices importantes:

• Evite referencias profundamente anidadas - Mantenga las referencias a un solo nivel de profundidad desde SKILL.md. Todos los archivos de referencia deben enlazar directamente desde SKILL.md.
• Estructura archivos de referencia largos - Para archivos de más de 100 líneas, incluya una tabla de contenido al principio para que Codex pueda ver el alcance completo al obtener una vista previa.

Proceso de Creación de Skills

La creación de un skill implica estos pasos:

1. Entender el skill con ejemplos concretos
2. Planificar contenidos reutilizables del skill (scripts, referencias, activos)
3. Inicializar el skill (ejecutar init_skill.py)
4. Editar el skill (implementar recursos y escribir SKILL.md)
5. Validar el skill (ejecutar quick_validate.py)
6. Iterar según el uso real y realizar pruebas hacia adelante de skills complejos.

Siga estos pasos en orden, saltándose solo si hay una razón clara de que no son aplicables.

Nomenclatura de Skills

• Use solo letras minúsculas, dígitos y guiones; normalice los títulos proporcionados por el usuario a mayúsculas y minúsculas con guiones (por ejemplo, "Plan Mode" -> plan-mode).
• Al generar nombres, genere un nombre de menos de 64 caracteres (letras, dígitos, guiones).
• Prefiera frases cortas que comiencen con un verbo y describan la acción.
• Use el espacio de nombres por herramienta cuando mejore la claridad o la activación (por ejemplo, gh-address-comments, linear-address-issue).
• Nombre la carpeta del skill exactamente igual que el nombre del skill.

Paso 1: Entender el Skill con Ejemplos Concretos

Omita este paso solo cuando los patrones de uso del skill ya estén claramente comprendidos. Sigue siendo valioso incluso cuando se trabaja con un skill existente.

Para crear un skill efectivo, comprenda claramente ejemplos concretos de cómo se utilizará el skill. Esta comprensión puede provenir de ejemplos directos del usuario o de ejemplos generados que se validan con la retroalimentación del usuario.

Por ejemplo, al construir un skill de editor de imágenes, las preguntas relevantes incluyen:

• "¿Qué funcionalidad debería soportar el skill de editor de imágenes? ¿Edición, rotación, algo más?"
• "¿Puede dar algunos ejemplos de cómo se usaría este skill?"
• "Puedo imaginar que los usuarios pidan cosas como 'Elimina los ojos rojos de esta imagen' o 'Rota esta imagen'. ¿Hay otras formas en que imagine que se use este skill?"
• "¿Qué diría un usuario que debería activar este skill?"
• "¿Dónde debería crear este skill? Si no tiene preferencia, lo colocaré en $CODEX_HOME/skills (o ~/.codex/skills cuando CODEX_HOME no esté establecido) para que Codex pueda descubrirlo automáticamente."

Para no abrumar a los usuarios, evite hacer demasiadas preguntas en un solo mensaje. Comience con las preguntas más importantes y haga un seguimiento según sea necesario para una mayor efectividad.

Concluya este paso cuando tenga una idea clara de la funcionalidad que el skill debe soportar.

Paso 2: Planificar los Contenidos Reutilizables del Skill

Para convertir ejemplos concretos en un skill efectivo, analice cada ejemplo mediante:

1. Considerar cómo ejecutar el ejemplo desde cero
2. Identificar qué scripts, referencias y activos serían útiles al ejecutar estos flujos de trabajo repetidamente

Ejemplo: Al construir un skill pdf-editor para manejar consultas como "Ayúdame a rotar este PDF", el análisis muestra:

1. Rotar un PDF requiere reescribir el mismo código cada vez
2. Un script scripts/rotate_pdf.py sería útil para almacenar en el skill

Ejemplo: Al diseñar un skill frontend-webapp-builder para consultas como "Créame una aplicación de tareas" o "Créame un tablero para realizar un seguimiento de mis pasos", el análisis muestra:

1. Escribir una aplicación web frontend requiere el mismo código repetitivo HTML/React cada vez
2. Una plantilla assets/hello-world/ que contenga los archivos de proyecto repetitivos HTML/React sería útil para almacenar en el skill

Ejemplo: Al construir un skill big-query para manejar consultas como "H..."

[El resto del contenido del SKILL.md original se ha truncado; se ha traducido hasta donde estaba disponible en la entrada.]