Better Plugin Generator

Generador Mejorado de Plugins (better-plugin-gen)

Esta habilidad ayuda al usuario a crear un plugin: un directorio que empaqueta múltiples componentes (como skill, agent, hook, servidor MCP) para instalarlos en un agente de codificación con un solo comando. La habilidad soporta tres hosts (herramientas de agente que cargan plugins): Claude Code, Codex, Antigravity. Cada host tiene su propio manifest; la habilidad usa el directorio común skills/ y genera manifests para cada host seleccionado.

Todas las rutas template.md, references/, examples/, scripts/ a continuación se calculan desde el directorio que contiene este archivo SKILL.md.

---

1. Principios fundamentales

1. Preguntar antes, generar después. Todas las opciones se preguntan al usuario usando herramientas de consulta estructurada si la sesión lo permite; si no, se enumeran las opciones numeradas, se indica claramente la recomendada y se espera la respuesta. Antes de cada pregunta, se escribe brevemente: qué hace el plugin a crear, qué pregunta se hace y por qué surge. No se completan puntos poco claros para luego generar archivos.
2. No adivinar especificaciones del host. La ubicación de archivos, el formato del manifest y MCP siguen references/hosts.md. Los puntos marcados como "no verificado" deben ser reportados al usuario.
3. La lógica principal reside en la habilidad. La habilidad es el único componente que se ejecuta en los tres hosts. Agent, command, hook, LSP solo se añaden cuando el usuario lo necesita y el host lo soporta.
4. Esqueleto mínimo funcional. Cada componente generado debe poder ejecutarse de inmediato pero ser conciso. Si el proyecto tiene las habilidades better-skill-gen o better-agent-gen, se sugiere al usuario usarlas para escribir en detalle la skill o el agente una vez que el plugin esté funcionando.
5. Autovalidación. El plugin solo se entrega cuando scripts/validate.sh devuelve código de salida 0.
6. Sin efectos secundarios externos. La habilidad solo escribe archivos dentro del directorio del plugin de destino (y el archivo marketplace en la raíz del repo si el usuario lo elige). No ejecuta git commit, git push, no instala el plugin, no modifica la configuración del host del usuario; solo imprime los comandos para que el usuario los ejecute.

---

2. Entrada

• Obligatorio: para qué sirve el plugin (incluso una frase basta), o la ruta de un plugin existente cuando se desea añadir un componente. Se obtiene de la solicitud del usuario.
• Preguntar si no se tiene: host de destino, ubicación del directorio, lista de componentes, si tiene marketplace, nombre del plugin, autor, licencia.
• Información faltante: preguntar según el paso 2 de la sección 3; si no hay respuesta, esperar.

---

3. Proceso

Paso 1: Determinar el modo y leer el estado actual

• Creación nueva: el usuario describe el plugin, aún no hay directorio.
• Añadir componente / añadir host: el usuario proporciona una ruta que contiene .claude-plugin/plugin.json, .codex-plugin/plugin.json o plugin.json. Leer todos los manifests, enumerar los componentes existentes, ejecutar el comando shell bash scripts/validate.sh <dir> para conocer los errores existentes antes de corregir.
• Crear marketplace: el usuario ya tiene un plugin, solo necesita publicarlo. Leer el plugin como en el caso anterior y luego ir al paso 6.
• Leer references/hosts.md. Si la Fecha de verificación tiene más de 30 días, o el plugin necesita una funcionalidad que no está en el archivo: consultar la fuente en la sección 6 de ese archivo en la web, actualizar el archivo y la fecha de verificación, luego informar al usuario de los cambios realizados.

Paso 2: Preguntar al usuario

Resumir lo entendido (qué hace el plugin, quién lo usa, cuándo se ejecuta), luego hacer la ronda 1 de preguntas, omitiendo aquellas que el usuario ya haya respondido claramente:

Pregunta	Tipo	Opciones (recomendada primero)
¿En qué host se ejecuta el plugin?	Selección múltiple	Claude Code; Codex; Antigravity. Se recomiendan los tres si el plugin solo contiene skill y MCP; solo Claude Code si necesita hook, LSP o userConfig
¿Dónde se coloca el plugin?	Selección única	Repositorio propio, plugin en la raíz (./<nombre>/); dentro de un repo marketplace (plugins/<nombre>/); en el proyecto actual para probar
¿Qué componentes incluye el plugin?	Selección múltiple	Skill; Agent; Hook; Servidor MCP; Command; LSP; userConfig
¿Se crea un marketplace para publicar?	Selección única	Sí, para los hosts seleccionados; No, solo probar localmente

Ronda 2 (si es necesario): nombre del plugin (sugerir nombre en kebab-case derivado de la descripción), autor y repositorio GitHub, licencia, detalles de cada componente (qué hace la skill, qué herramientas usa el agent, en qué evento se ejecuta el hook, qué servidor MCP y si necesita token).

Reglas al preguntar:

• Si el usuario selecciona hook junto con un host diferente a Claude Code: advertir del conflicto en la sección 4 de references/hosts.md, preguntar si desea conservar el hook.
• Si el plugin necesita token o contraseña: preguntar cómo proporcionarlo (Claude Code: userConfig con sensitive: true; otros hosts: variables de entorno documentadas en README). Nunca escribir valores secretos en archivos.
• Si el nombre coincide con un nombre prohibido de Claude Code (sección 2.1 de references/hosts.md): sugerir otro nombre.
• Si el directorio de destino ya contiene archivos: listar los archivos que se sobrescribirán y preguntar antes de escribir.

Paso 3: Cerrar el diseño

Escribir un resumen en el chat: nombre, host, ubicación, árbol de directorios a crear (marcar el host de cada archivo), qué componentes se ejecutan en qué host, valores que el agente establece automáticamente, puntos no verificados. Si la respuesta genera nuevos puntos poco claros, preguntar de nuevo; no generar archivos.

Paso 4: Generar archivos

1. Leer template.md (esqueleto de cada archivo) y references/components.md (formato de cada componente). Leer examples/sample.md para conocer el nivel de detalle esperado.
2. Escribir el manifest para cada host seleccionado. name, version, description deben ser idénticos en todos los manifests.
3. Escribir los componentes en la raíz del plugin, no dentro de .claude-plugin/ ni .codex-plugin/:
   • Skill: skills/<nombre>/SKILL.md, con frontmatter solo name, description, legible por todos los hosts.
   • MCP: .mcp.json para Claude Code, Codex; mcp_config.json para Antigravity (servidor remoto usando serverUrl). Ambos archivos con la misma lista de servidores.
   • Hook: hooks/hooks.json envuelto en la clave "hooks", siempre con matcher, llamando al script mediante "${CLAUDE_PLUGIN_ROOT}" (variable de Claude Code). El script se coloca en scripts/, con shebang.
   • Agent, command, LSP, userConfig: según references/components.md.
4. Escribir README.md basado en el esqueleto del Archivo 8, mínimo 40 palabras, con una tabla de componentes por host y comandos de instalación para cada host (references/publishing.md sección 5).
5. Modo añadir componente: solo agregar archivos nuevos y modificar las claves necesarias en el manifest; incrementar version (parche) en todos los manifests si el plugin ya se publicó.

Paso 5: Autovalidación

1. Ejecutar el comando shell HOSTS="<hosts seleccionados>" bash scripts/validate.sh <directorio-del-plugin-o-repo>. Por ejemplo HOSTS="claude codex antigravity".
2. El script ejecuta check_plugin.py (manifest, nombre, rutas, MCP, hook, skill, agent, marketplace, placeholders, cadenas similares a secretos), luego claude plugin validate y agy plugin validate si el sistema tiene esos comandos.
3. Si hay [FAIL] o el CLI reporta errores: corregir los archivos, ejecutar de nuevo hasta que el código de salida sea 0.
4. Leer cada [WARN]: corregir si es posible; si se mantiene (por ejemplo, una advertencia de hook multi-host ya informada al usuario), documentar el motivo en el informe de entrega.
5. Si se necesitan archivos temporales, escribirlos en el directorio temporal especificado por las instrucciones del usuario; si no, usar el directorio temporal del sistema operativo; eliminar inmediatamente después de la validación.

Paso 6: Marketplace (si se seleccionó)

• Claude Code: .claude-plugin/marketplace.json en la raíz del repo (esqueleto del Archivo 9).
• Codex: .agents/plugins/marketplace.json en la raíz del repo (esqueleto del Archivo 10).
• Antigravity: no necesita archivo; README documenta el comando agy plugin install con la URL del repositorio GitHub, por ejemplo https://github.com/phucbui/pr-review-kit.
• Volver a ejecutar el paso 5 con el directorio raíz del repo para validar también el marketplace.

Paso 7: Entrega

Imprimir el informe siguiendo el esqueleto "Informe de entrega" al final de template.md: directorio, hosts, resultado de la validación, tabla de archivos, puntos no verificados, comandos de prueba local, comandos de publicación para que el usuario los ejecute (references/publishing.md secciones 3 a 6). Si en el proyecto existen better-skill-gen o better-agent-gen, sugerir en una línea cómo usarlos para escribir componentes en detalle.

---

4. Restricciones

• Obligatorio:
  • Preguntar por host, ubicación, componentes y marketplace antes de crear archivos; no decidir por el usuario puntos poco claros.
  • Escribir solo dentro del directorio del plugin de destino y el archivo marketplace en la raíz del repo; no crear archivos de ejemplo en otros lugares. Los ejemplos solo residen en examples/ de esta habilidad.
  • No ejecutar git commit, git push, claude plugin install, agy plugin install, codex plugin marketplace add; solo imprimir los comandos.
  • No escribir tokens, contraseñas ni claves API en ningún archivo.
  • Entregar solo cuando scripts/validate.sh devuelva código 0.
• Recomendado:
  • Usar nombres en kebab-case para plugin, skill, agent; versión inicial 0.1.0.
  • Mantener el plugin enfocado en un solo propósito; dividir en plugins si el usuario agrupa funcionalidades no relacionadas.
  • Indicar claramente en el README qué componente se ejecuta en qué host.
• No recomendado:
  • No copiar el SKILL.md original con campos específicos de Claude Code en un plugin destinado a Codex o Antigravity.
  • No usar rutas absolutas ni .. en manifests, hooks, MCP.
  • No colocar CLAUDE.md en la raíz del plugin; si se necesita cargar instrucciones, incluirlas en la skill.