plugin-forge

Visión general de la skill plugin-forge

plugin-forge es una skill de creación y mantenimiento para autores de plugins de Claude Code que necesitan la estructura de carpetas correcta, los archivos de manifiesto adecuados y el registro en marketplace, sin tener que reinventar el flujo de trabajo. La necesidad real no es “escribir algo de JSON”, sino “publicar un plugin que tenga un scaffold correcto, versiones coherentes y se pueda instalar dentro de un flujo basado en marketplace”.

Para quién encaja mejor plugin-forge

Usa la skill plugin-forge si estás:

• creando un plugin nuevo de Claude Code desde cero
• añadiendo partes del plugin como commands/, agents/, skills/ o hooks/
• actualizando .claude-plugin/plugin.json y los metadatos del marketplace de forma conjunta
• probando plugins en local antes de publicarlos
• manteniendo un repositorio de plugins estilo marketplace con varios plugins

Resulta especialmente útil para desarrolladores que quieren una estructura repetible, no solo una salida puntual generada por prompt.

Qué diferencia a plugin-forge de un prompt genérico

Un prompt genérico puede bosquejar el esqueleto de un plugin, pero plugin-forge añade controles prácticos:

• una estructura de directorios de plugin definida
• ubicaciones explícitas para los manifiestos y expectativas sobre sus campos
• una referencia del esquema de marketplace
• un flujo de instalación y prueba en local
• scripts de automatización para scaffolding y subida de versión

Esa combinación importa porque el fallo más habitual en plugins no suele ser la calidad del código, sino una estructura inconsistente o metadatos desalineados.

Qué cubre realmente la skill plugin-forge

La evidencia del repositorio muestra que plugin-forge se centra en:

• scripts/create_plugin.py para crear el scaffold de un plugin nuevo
• scripts/bump_version.py para actualizar versiones de forma sincronizada
• references/plugin-structure.md para la estructura de carpetas y manifiestos
• references/marketplace-schema.md para las reglas de las entradas del marketplace
• references/workflows.md para el flujo de creación, prueba y publicación

Así que esto funciona más como una guía de implementación con tooling de apoyo que como un documento amplio de teoría.

Cuándo plugin-forge encaja muy bien para Code Generation

plugin-forge para Code Generation es especialmente útil cuando quieres que el modelo genere archivos que deban aterrizar con la forma correcta de plugin, por ejemplo:

• un esqueleto de plugin nuevo con metadatos válidos
• un comando o skill nuevo insertado en un plugin existente
• cambios en plugin.json junto con sus cambios correspondientes en la entrada del marketplace
• preparación de una release que incluya incrementos de versión semántica

Si lo que más necesitas es lógica de negocio pura dentro de un plugin que ya funciona, plugin-forge aporta menos que una skill de código específica para ese dominio.

Cómo usar la skill plugin-forge

Contexto de instalación de plugin-forge

El SKILL.md upstream no publica su propio comando de instalación, así que la instalación depende de cómo cargues skills en tu entorno. Si estás usando el bundle de skills del repositorio, un patrón habitual es:

npx skills add softaworks/agent-toolkit --skill plugin-forge

Después, usa plugin-forge cuando tu tarea tenga que ver con creación de plugins, manifiestos, registro en marketplace, pruebas en local o gestión de versiones.

Lee primero estos archivos de plugin-forge

Para adoptarlo rápido, empieza en este orden:

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

Este recorrido te da primero el “qué”, luego la estructura esperada de archivos, después el contrato del marketplace y finalmente las ayudas ejecutables.

Qué información necesita plugin-forge de tu parte

plugin-forge funciona mucho mejor cuando le das contexto concreto del repositorio y de publicación, no solo “hazme un plugin”. Como mínimo, especifica:

• nombre del plugin en kebab-case
• ruta raíz del marketplace
• propósito del plugin
• nombre y correo del autor
• palabras clave iniciales
• categoría
• si necesitas commands, agents, skills, hooks o configuración MCP
• si es un plugin nuevo o una actualización de uno existente

Sin esa información, el modelo aún puede bosquejar archivos, pero normalmente la salida requiere limpieza manual.

Convierte un objetivo difuso en un buen prompt para plugin-forge

Prompt débil:

Create a Claude Code plugin for my project.

Prompt más sólido:

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

El segundo prompt le da a plugin-forge suficiente información para producir archivos mucho más cercanos a algo utilizable.

Usa el script de scaffolding cuando priorices velocidad

Si ya conoces tus metadatos, usa el script auxiliar en lugar de construir manualmente el árbol inicial:

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

Es la vía más rápida cuando te importa más una configuración correcta que un scaffolding manual y muy personalizado.

Usa el script de versión para evitar desfases entre manifiestos

Una de las partes más prácticas de plugin-forge es el versionado sincronizado. La skill incluye scripts/bump_version.py para actualizar ambos:

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

Ejemplo:

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

Esto importa porque la falta de coincidencia de versión entre esos archivos es un error de mantenimiento muy común.

Sigue el flujo real de trabajo de plugin-forge

Una guía práctica de plugin-forge sería:

1. crear el scaffold del plugin
2. inspeccionar el plugin.json generado
3. verificar la entrada del marketplace en .claude-plugin/marketplace.json
4. añadir componentes como comandos o skills
5. probar en local mediante el flujo de instalación del marketplace
6. iterar
7. subir versión antes de la release

Ese flujo es más fiable que pedirle al modelo todo en un único prompt enorme.

Planifica pronto el flujo de pruebas locales

Las referencias incluyen una ruta concreta para pruebas locales:

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

Eso significa que debes diseñar los prompts para que plugin-forge genere rutas y metadatos instalables, no solo archivos descriptivos. Si la ruta de origen o el nombre del plugin no son coherentes, las pruebas fallan de inmediato.

Archivos clave que plugin-forge suele modificar

En uso real, lo normal es que plugin-forge cree o edite:

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

Este alcance ayuda a planificar la revisión, porque plugin-forge suele generar cambios en varios archivos.

Consejos prácticos para mejorar la calidad de salida de plugin-forge

Pídele a plugin-forge que:

• preserve exactamente los nombres y rutas existentes del plugin
• mantenga todos los identificadores en kebab-case
• muestre juntos tanto el manifiesto del plugin como la entrada del marketplace
• explique cualquier campo obligatorio que no haya podido inferir
• separe “generated files” de “manual follow-up”
• valide que las versiones y los nombres coincidan entre manifiestos

Estas peticiones reducen la probabilidad de obtener una salida atractiva, pero no instalable.

FAQ de la skill plugin-forge

¿Merece la pena usar plugin-forge si ya sé hacer buenos prompts?

Sí, si tu principal riesgo es la corrección estructural. La skill plugin-forge resulta más útil que un prompt normal cuando necesitas manifiestos consistentes, entradas de marketplace correctas y una estructura de directorios coherente. Si solo necesitas ayuda para escribir un archivo de comando dentro de un plugin ya existente, la ventaja es menor.

¿plugin-forge es amigable para principiantes?

En general, sí. plugin-forge les da a los principiantes un camino concreto para crear y probar plugins. El matiz es que igualmente necesitan entender dónde está la raíz del marketplace, cuáles son las convenciones de nombres y qué componentes quieren realmente. Ayuda más con la estructura que con el diseño del producto.

¿Cuándo no conviene usar plugin-forge?

Omite plugin-forge si:

• no estás creando un plugin de Claude Code
• no usas distribución estilo marketplace
• solo quieres generación genérica de código Python o JavaScript
• tu repositorio tiene una estructura de plugin personalizada que difiere intencionalmente de la documentada

En esos casos, plugin-forge puede empujarte hacia una forma equivocada.

¿plugin-forge se encarga de la publicación automáticamente?

No por completo. La skill cubre bien la preparación: scaffolding, manifiestos, registro en marketplace, guía de pruebas locales y actualizaciones de versión. Pero no es una plataforma integral de release. Aun así, necesitas revisar archivos, probar en local y ejecutar tu propio proceso de publicación o distribución.

¿Cuál es el principal bloqueo para adoptarlo?

Normalmente, la falta de contexto del repositorio. plugin-forge da por hecho que sabes dónde está la raíz del marketplace y cómo debe categorizarse tu plugin. Si no puedes responder a esas preguntas, la salida seguirá teniendo calidad de borrador en lugar de estar lista para producción.

¿Cómo se compara plugin-forge con editar los manifiestos a mano?

Las ediciones manuales sirven para cambios puntuales, pero plugin-forge es mejor cuando buscas repetibilidad o necesitas evitar desfases entre plugin.json y marketplace.json. Los scripts incluidos son la ventaja práctica más clara.

Cómo mejorar la skill plugin-forge

Dale a plugin-forge entradas con contexto real del repositorio

La mejor mejora es proporcionar rutas exactas y archivos actuales. En vez de pedir “una subida de versión”, di:

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

Eso empuja la skill hacia cambios verificables en lugar de consejos genéricos.

Pide salida archivo por archivo, no solo un resumen

plugin-forge rinde mejor cuando le pides entregables concretos:

• plugin.json completo
• entrada exacta del marketplace
• árbol de directorios propuesto
• README inicial
• comandos posteriores para probar en local

Esto es especialmente importante para plugin-forge en Code Generation, donde el valor está en archivos listos para aplicar.

Evita los fallos más habituales

Vigila estos problemas en la salida de plugin-forge:

• el nombre del plugin difiere entre archivos
• la ruta source del marketplace no coincide con la estructura real de carpetas
• la versión se actualiza en un manifiesto pero no en el otro
• se referencian componentes opcionales en los metadatos, pero no se crean
• la estructura generada omite .claude-plugin/plugin.json

Una revisión rápida contra references/plugin-structure.md y references/marketplace-schema.md detecta la mayoría.

Usa un flujo en dos pasadas para mejores resultados con plugin-forge

Una guía sólida de plugin-forge en la práctica sería:

1. primera pasada: generar estructura y manifiestos
2. segunda pasada: generar componentes del plugin y mejorar el README

Intentar hacer scaffolding, lógica de negocio, documentación, setup de pruebas y notas de publicación en un solo prompt suele bajar la calidad. plugin-forge funciona mejor cuando la estructura va primero.

Itera sobre la primera salida con correcciones concretas

No digas solo “arregla esto”. Da instrucciones precisas de corrección, por ejemplo:

• “Regenerate marketplace.json entry so source points to ./plugins/schema-audit.”
• “Add skills/ to the tree and keep manifest fields unchanged.”
• “Update only version fields; do not rewrite descriptions or keywords.”
• “Align the plugin name to kebab-case everywhere.”

Ese tipo de iteración acotada hace que plugin-forge sea mucho más fiable.

Combina plugin-forge con la documentación de referencia, no en lugar de ella

La mejor forma de mejorar la salida de plugin-forge es pedir explícitamente que cite o siga las referencias del repositorio. En los prompts, menciona:

• references/plugin-structure.md para las expectativas de directorios
• references/marketplace-schema.md para los campos del marketplace
• references/workflows.md para el flujo de instalación y pruebas

Así mantienes la skill anclada a las convenciones reales del repo, en lugar de dejar que recaiga en supuestos genéricos sobre plugins.