generador-mejor-skill

Generador de Skills Mejorado (better-skill-gen)

Este skill actúa como un Meta-Skill: recibe ideas, problemas o flujos de trabajo del usuario, concreta el diseño con él y luego genera la carpeta de Skill completa para cada proveedor seleccionado:

Proveedor	Carpeta (ámbito del proyecto)	Características
Codex y Antigravity	.agents/skills/<skill-name>/ (una versión compartida)	Solo name, description; Codex añade además agents/openai.yaml para la política de invocación del skill
Claude Code	.claude/skills/<skill-name>/	Tiene más campos frontmatter extendidos, consulta references/frontmatter-spec.md

Este archivo se usa de forma compartida para Codex y Antigravity. Todas las rutas scripts/..., references/... en este archivo son relativas a la carpeta que contiene este SKILL.md. "Ejecutar comando" significa usar la herramienta de ejecución de comandos shell del proveedor que se está usando (por ejemplo run_command en Antigravity).

---

1. Principios de Diseño Fundamentales

1. Arquitectura de Divulgación Progresiva de 3 Niveles:
   • Nivel 1: Metadatos (Siempre se cargan al iniciar): name, description en el Frontmatter YAML. Consume muy pocos tokens; mantén description por debajo de 1.536 caracteres.
   • Nivel 2: Instrucciones (Solo se cargan cuando se activa el Skill): Cuerpo del archivo SKILL.md, obligatoriamente menos de 500 líneas. Solo contiene el Flujo de Trabajo, los Principios Fundamentales y las Restricciones.
   • Nivel 3: Recursos (Solo se cargan cuando realmente se necesitan): templates/ (plantillas de resultados), examples/ (textos de muestra Gold Standard), references/ (especificaciones técnicas), scripts/ (código bash/python para tareas pesadas sin consumir contexto).
2. Clasificación del Propósito del Skill:
   • Reference Skills: Convenciones de código, conocimiento del sistema, patrones de diseño, para que el agente los aplique como conocimiento de fondo.
   • Task Skills: Procesos paso a paso para ejecutar acciones. Las tareas con efectos secundarios (despliegue, commit, borrado de datos) solo deben ejecutarse cuando el usuario las invoque directamente. La versión .agents/skills/ hace ambas cosas: crea agents/openai.yaml con policy.allow_implicit_invocation: false (para Codex) y escribe la frase "Usar solo cuando el usuario lo solicite directamente" en description (para Antigravity, que no tiene un campo equivalente). Los detalles están en references/providers.md sección 3.
3. Funcionalidades específicas de cada proveedor: Claude Code tiene subagente, variables de parámetros e inyección de comandos shell en SKILL.md (consulta references/frontmatter-spec.md). Solo se usan en la versión para Claude Code; la versión para otros proveedores las convierte según references/providers.md sección 3.
4. Verificar, No Confiar (Autoverificación):
   • Todo skill generado debe incluir scripts/validate.sh con códigos de salida estándar (0 = correcto, 1 = error).
   • Cumplir al 100% todas las reglas de linting según el estándar markdownlint.
5. Contaminación Cero del Espacio de Trabajo:
   • Todos los archivos de configuración, recursos y scripts solo residen dentro de la carpeta empaquetada del skill en la carpeta de cada proveedor.
   • Todos los documentos de muestra solo residen en examples/ del skill. No generar ni copiar archivos de muestra a otras carpetas de negocio del proyecto (como src/, raíz del proyecto).
   • Los archivos temporales durante las pruebas se escriben en la carpeta temporal del sistema operativo (o en la carpeta temporal que indiquen las instrucciones del usuario) y se limpian inmediatamente después.
6. Preguntar al usuario mediante opciones estructuradas:
   • Todas las opciones que se presenten al usuario (alcance, proveedor, puntos poco claros de la idea, dirección de diseño) se preguntan en forma de selección. Si la sesión dispone de una herramienta para preguntar al usuario con selección de respuestas, se usa esa herramienta. Si no, se enumeran las opciones numeradas, luego se detiene y se espera la respuesta del usuario.
   • Orden de presentación: (1) qué hace el skill que se va a crear, (2) qué pregunta la pregunta y por qué surge, (3) las opciones, cada una con una frase que indique sus ventajas y desventajas, (4) la opción recomendada, colocada al principio de la lista y marcada con (recomendado).
   • Preguntar un máximo de 4 preguntas por turno, los puntos importantes primero. Siempre permitir al usuario responder algo diferente a las opciones presentadas.
   • No decidir por el usuario cuando aún no haya respondido.
7. Una versión para cada proveedor, correcta según ese proveedor:
   • Los recursos compartidos (template.md, examples/, references/, scripts/) se copian tal cual. Solo SKILL.md (y agents/openai.yaml de Codex) se escriben de forma específica: una versión para Claude Code, una versión compartida para Codex y Antigravity.
   • La versión Codex/Antigravity debe funcionar correctamente en ambos proveedores: solo usar los campos frontmatter del estándar abierto, no usar variables ni herramientas que solo entienda Claude Code, y no llamar "Claude" al agente que se está ejecutando. Claude solo se menciona cuando es el tema del skill.

---

2. Entradas Necesarias (Inputs)

• Obligatorio: Descripción de la idea o el objetivo de negocio del skill que se va a crear.
• Opcional: Restricciones específicas, herramientas a usar, tipo de tarea o referencia.
• Obligatorio preguntar (cada vez que se crea un skill nuevo): Alcance y proveedor (sección 2.1), junto con todos los puntos poco claros de la idea (sección 2.2). Solo se omiten las preguntas que el usuario ya haya respondido claramente en su solicitud.
• No decidir por sí mismo sobre puntos poco claros: Si la idea es vaga, se analiza y se proponen opciones (sección 2.2), no se rellena automáticamente y se generan archivos. Solo los puntos con una convención obvia (por ejemplo, el nombre en kebab-case deducido de la idea) se pueden establecer automáticamente, y deben mencionarse en el resumen de diseño.

2.1. Preguntar el Alcance (Scope) y el Proveedor

Antes de generar cualquier archivo, hacer 2 preguntas en el mismo turno según el principio 6:

1. Scope (se puede elegir más de uno): tres opciones según la tabla siguiente, project-shared es la recomendada.
2. Provider (se puede elegir más de uno): Codex, Claude Code, Antigravity. Si el skill se puede usar para todos los proveedores, se recomiendan los tres. Si el skill solo tiene sentido para un proveedor (por ejemplo, solo verifica archivos de configuración de Claude Code), se recomienda solo ese proveedor y se explica el motivo.

Scope	Significado	Raíz de destino	Variable al ejecutar script
project-shared	Solo para el proyecto actual, compartido por todo el equipo (se commitea en git)	Raíz del proyecto	SCOPE=project (por defecto)
project-personal	Solo para el proyecto actual, solo para este usuario (no se commitea)	Raíz del proyecto	SCOPE=project, luego se añaden las carpetas creadas a .git/info/exclude
user-global	Todos los proyectos de este usuario	$HOME	SCOPE=user

Reglas:

• Si el usuario elige varios alcances, se despliegan uno tras otro.
• Si la carpeta del proyecto no es un repositorio git, se omite la opción project-personal.
• Se registra el alcance y el proveedor seleccionados en el informe de entrega junto con la lista de rutas creadas.
• Si el skill tiene contenido específico del proyecto y el usuario elige user-global, se muestra una advertencia de una línea antes de crearlo.

2.2. Análisis de la Idea y Propuesta

Después de tener el alcance y el proveedor, analizar la idea antes de escribir cualquier archivo:

1. Resumen de lo que se ha entendido: qué problema resuelve el skill, quién lo usa, cuándo se activa, cuál es la salida.
2. Identificar los puntos de diseño, indicando claramente si ya los ha dicho el usuario o si el agente está especulando:
   • Tipo de skill: Tarea o Referencia; ¿tiene efectos secundarios?
   • Forma de activación: automática según description, solo cuando el usuario lo invoca directamente, o ambas; frase de activación y casos en los que no se usa.
   • Entradas, parámetros y cómo manejar los faltantes.
   • Salidas: formato, dónde se guardan, si se necesita template.md y criterios de verificación en scripts/validate.sh.
   • Modo de ejecución: solo instrucciones o se necesita script; herramientas a usar.
   • Parte que se separa a references/, para mantener SKILL.md por debajo de 500 líneas.
3. Proponer la dirección óptima: para cada punto que admita varias formas de hacerlo, presentar 2 o 3 direcciones con sus ventajas y desventajas, y seleccionar una dirección recomendada. Por ejemplo: "verificar con el script scripts/check.sh (rápido, preciso, pero necesita bash)" frente a "el agente lee y evalúa por sí mismo (flexible, pero consume tokens y es propenso a errores)".
4. Preguntar al usuario: agrupar todos los puntos poco claros y todos los puntos con múltiples direcciones en preguntas según el principio 6.
5. Cerrar el diseño: después de recibir las respuestas, escribir un resumen de diseño (nombre del skill, tipo, forma de activación, lista de archivos a crear, proveedor, alcance, valores que el agente ha establecido automáticamente). Si las respuestas generan nuevos puntos poco claros, se sigue preguntando; no se generan archivos todavía.

2.3. Investigación del Proveedor

Antes de escribir la versión para un proveedor, leer references/providers.md:

• Si la Fecha de verificación tiene más de 30 días, el skill necesita una funcionalidad que aún no está en el archivo, o la información del archivo contradice la realidad: consultar la documentación oficial en la sección 6 de ese archivo, corregir el archivo, actualizar la fecha de verificación y luego copiar el archivo a los otros proveedores usando scripts/sync-skill.sh better-skill-gen.
• Antigravity en el ámbito del proyecto usa la carpeta compartida .agents/skills/ con Codex (sección 5). No crear .agent/skills/.
• No adivinar las especificaciones del proveedor. Cualquier punto que no se pueda consultar se comunica claramente al usuario y se pregunta.

---

3. Flujo de Trabajo (Workflow)

flowchart TD
    A["Idea de negocio del Usuario"] --> A2["0. Preguntar Scope y Proveedor"]
    A2 --> B["1. Analizar la idea, proponer, preguntar puntos poco claros"]
    B --> B2["2. Investigar el proveedor"]
    B2 --> C["3. Consultar template.md y references/"]
    C --> D["4. Generar la versión base"]
    D --> E["5. Sincronizar recursos y escribir SKILL.md específico para cada proveedor"]
    E --> F["6. Autoverificación con scripts/validate.sh"]
    F -->|Correcto| G["Completado y Entrega"]
    F -->|Error| D

0. Preguntar Scope y Proveedor: Realizar la sección 2.1 y esperar la respuesta antes de continuar.
1. Analizar la idea: Realizar la sección 2.2 hasta que el diseño quede cerrado. Nombrar el skill en kebab-case ($\le 64$ caracteres, prohibido usar anthropic-skills, synced, claude, anthropic).
2. Investigar el proveedor: Realizar la sección 2.3 para todos los proveedores seleccionados.
3. Consultar la documentación estándar: Leer template.md (estructura marco), references/providers.md (diferencias entre proveedores), references/frontmatter-spec.md (campos de Claude Code) y examples/sample.md (estilo de escritura y lógica de scripts).
4. Generar la versión base: Escribir todos los componentes en la carpeta del primer proveedor seleccionado:
   • SKILL.md: Frontmatter seguro (scalar block >-), menos de 500 líneas.
   • template.md (o templates/): Plantilla de salida con variables de muestra ${VARIABLE}.
   • examples/sample.md: Texto de muestra real sin placeholders.
   • references/ (si hay documentación de especificaciones o conocimiento complejo que deba separarse).
   • scripts/validate.sh: Script de verificación de la integridad del resultado.
   • Los recursos compartidos se escriben de forma neutral respecto al proveedor: los scripts se llaman mediante rutas relativas desde la carpeta del skill.
5. Despliegue por proveedor:
   • Copiar los recursos compartidos: ejecutar PROVIDERS="<proveedores seleccionados>" bash scripts/sync-skill.sh <skill-name>. El script copia todos los archivos excepto SKILL.md y agents/, y muestra [TODO] para el proveedor al que le falta SKILL.md.
   • Para las carpetas restantes, escribir un SKILL.md específico según la tabla de conversión de references/providers.md sección 3. Reescribir el texto del cuerpo, no solo eliminar campos del frontmatter. Si Codex y Antigravity se seleccionan juntos, solo hay una carpeta .agents/skills/, el script la fusiona automáticamente.
   • Skill con efectos secundarios: la versión .agents/skills/ crea además agents/openai.yaml con policy.allow_implicit_invocation: false y escribe la frase "Usar solo cuando el usuario lo solicite directamente" en description.
   • Scope user-global: añadir SCOPE=user al ejecutar el script.
   • Scope project-personal: añadir las carpetas del skill recién creadas a .git/info/exclude (no modificar .gitignore, no committear).
6. Autoverificación (Self-Verification):
   • Ejecutar PROVIDERS="<proveedores seleccionados>" bash scripts/validate.sh <skill-name> (añadir SCOPE=user si es user-global).
   • El script verifica: frontmatter YAML válido, markdownlint, SKILL.md $\le 500$ líneas, archivos obligatorios presentes en todos los proveedores seleccionados, y que el SKILL.md de Codex/Antigravity no tenga campos o tokens que solo entienda Claude Code.
   • Leer cada línea [WARN]: si menciona a Claude porque Claude es el tema, se mantiene; si no, se corrige.
   • Si hay errores, se corrigen automáticamente hasta obtener [PASS].

---

4. Restricciones y Estándares (Guardrails)

• REGLAS OBLIGATORIAS (CRÍTICAS):
  • Todas las opciones se preguntan según el principio 6 y se espera la respuesta antes de continuar.
  • Siempre preguntar el alcance y el proveedor antes de crear un skill nuevo (sección 2.1).
  • No decidir por sí mismo sobre puntos poco claros: analizar, proponer y preguntar (sección 2.2) antes de generar archivos.
  • Investigar el proveedor antes de escribir la versión para ese proveedor (sección 2.3); no adivinar las especificaciones.
  • No copiar literalmente SKILL.md entre proveedores: cada proveedor tiene una versión correcta según su propio estándar; validate.sh debe dar [PASS] para todos los proveedores seleccionados.
  • Contaminación Cero del Espacio de Trabajo: los documentos de muestra solo residen en examples/; no crear archivos fuera de la carpeta empaquetada del skill.
  • Mantener SKILL.md por debajo de 500 líneas: mover el contenido detallado a references/ o templates/.
  • Estandarización del Frontmatter: si description contiene dos puntos :, se debe usar scalar >- o comillas dobles "...".
  • Cumplir con Markdownlint (MD001 - MD047) para todos los archivos Markdown creados.
• QUÉ HACER (Recomendaciones):
  • Declarar el mecanismo "ejecutar solo cuando el usuario lo solicite" para todo skill con efectos secundarios, según la forma correcta de cada proveedor (Codex: agents/openai.yaml; Antigravity: frase en description).
  • Usar variables de plantilla ${NOMBRE_VARIABLE} que sean muy descriptivas en la plantilla.
  • Limpiar inmediatamente los archivos temporales generados durante las pruebas automáticas.
• QUÉ NO HACER (Prohibiciones):
  • No meter toda la documentación de referencia larga directamente en SKILL.md.
  • No dejar URLs sueltas en un archivo markdown sin los delimitadores <> o un enlace markdown.
  • No usar un nombre de skill de más de 64 caracteres o que contenga mayúsculas/caracteres especiales.
  • No llamar "Claude" al agente en la versión para un proveedor que no sea Claude Code.