plugin-forge

Visão geral da skill plugin-forge

plugin-forge é uma skill de criação e manutenção para autores de plugins do Claude Code que precisam da estrutura de pastas correta, dos arquivos de manifesto e do registro no marketplace sem reinventar o fluxo de trabalho. O trabalho real aqui não é “escrever um JSON”, e sim “entregar um plugin com scaffold correto, versionamento consistente e instalável em um fluxo baseado em marketplace”.

Para quem a plugin-forge é mais indicada

Use a skill plugin-forge se você estiver:

• criando um novo plugin do Claude Code do zero
• adicionando partes do plugin como commands/, agents/, skills/ ou hooks/
• atualizando .claude-plugin/plugin.json e os metadados do marketplace em conjunto
• testando plugins localmente antes de publicar
• mantendo um repositório de plugins no estilo marketplace com vários plugins

Ela é especialmente útil para desenvolvedores que querem uma estrutura repetível, e não apenas uma resposta pontual de prompt.

O que diferencia a plugin-forge de um prompt genérico

Um prompt genérico pode até montar o esqueleto de um plugin, mas a plugin-forge adiciona proteções práticas:

• um layout definido de diretórios do plugin
• localizações explícitas dos manifestos e expectativa dos campos
• uma referência de schema de marketplace
• um fluxo para instalação e teste local
• scripts de automação para scaffold e incremento de versão

Essa combinação importa porque a falha mais comum em plugins não costuma ser a qualidade do código; é a estrutura inconsistente ou metadados desalinhados.

O que a skill plugin-forge realmente cobre

Pelo que o repositório mostra, a plugin-forge está centrada em:

• scripts/create_plugin.py para criar o scaffold de um novo plugin
• scripts/bump_version.py para atualizações sincronizadas de versão
• references/plugin-structure.md para layout de pastas e manifestos
• references/marketplace-schema.md para regras de entrada no marketplace
• references/workflows.md para o fluxo de criação, teste e publicação

Ou seja, trata-se mais de um guia de implementação com ferramentas auxiliares do que de um documento amplo e teórico.

Quando a plugin-forge é uma ótima escolha para Code Generation

plugin-forge para Code Generation é mais útil quando você quer que o modelo gere arquivos que já precisem sair no formato correto de plugin, por exemplo:

• um novo esqueleto de plugin com metadados válidos
• um novo command ou skill inserido em um plugin existente
• atualizações em plugin.json com as mudanças correspondentes na entrada do marketplace
• preparação de release com incremento de versão semântica

Se a sua necessidade principal for apenas lógica de negócio dentro de um plugin que já funciona, a plugin-forge ajuda menos do que uma skill de programação específica do domínio.

Como usar a skill plugin-forge

Contexto de instalação da plugin-forge

O SKILL.md original não publica um comando próprio de instalação, então a instalação depende de como você carrega skills no seu ambiente. Se estiver usando o bundle de skills do repositório, um padrão comum é:

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

Depois disso, use a plugin-forge quando a tarefa envolver criação de plugin, manifestos, registro em marketplace, testes locais ou gerenciamento de versão.

Leia estes arquivos primeiro

Para adotar a plugin-forge rapidamente, comece nesta ordem:

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

Esse caminho te dá primeiro o “o quê”, depois o layout esperado de arquivos, depois o contrato do marketplace e, por fim, os helpers executáveis.

Quais entradas a plugin-forge precisa de você

A plugin-forge funciona melhor quando você fornece contexto concreto do repositório e da publicação, e não apenas “faça um plugin para mim”. No mínimo, informe:

• nome do plugin em kebab-case
• caminho raiz do marketplace
• objetivo do plugin
• nome e e-mail do autor
• palavras-chave iniciais
• categoria
• se você precisa de commands, agents, skills, hooks ou configuração MCP
• se isso é um plugin novo ou uma atualização de um já existente

Sem essas informações, o modelo ainda consegue rascunhar os arquivos, mas a saída normalmente exige limpeza manual.

Transforme um objetivo vago em um prompt forte para a plugin-forge

Prompt fraco:

Create a Claude Code plugin for my project.

Prompt melhor:

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.

O segundo prompt dá à plugin-forge informação suficiente para produzir arquivos muito mais próximos do uso real.

Use o script de scaffold quando quiser ganhar velocidade

Se você já conhece seus metadados, use o script auxiliar em vez de montar manualmente a árvore 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"

Esse é o caminho mais rápido quando você se importa mais com uma configuração correta do que com um scaffold manual personalizado.

Use o script de versão para evitar divergência entre manifestos

Uma das partes mais práticas do uso da plugin-forge é o versionamento sincronizado. A skill inclui scripts/bump_version.py para atualizar ao mesmo tempo:

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

Exemplo:

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

Isso importa porque incompatibilidade de versão entre esses arquivos é um erro comum de manutenção.

Siga o fluxo real da plugin-forge

Um guia prático de uso da plugin-forge é:

1. criar o scaffold do plugin
2. inspecionar o plugin.json gerado
3. verificar a entrada do marketplace em .claude-plugin/marketplace.json
4. adicionar componentes como commands ou skills
5. testar localmente pelo fluxo de instalação via marketplace
6. iterar
7. incrementar a versão antes do release

Esse fluxo é mais confiável do que pedir tudo ao modelo em um único prompt enorme.

Planeje cedo o fluxo de testes locais

As referências incluem um caminho concreto para teste local:

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

Isso significa que você deve estruturar seus prompts para que a plugin-forge gere caminhos e metadados instaláveis, e não apenas arquivos descritivos. Se o caminho de origem ou o nome do plugin estiver inconsistente, o teste quebra imediatamente.

Arquivos-chave que a plugin-forge costuma modificar

No uso real, espere que a plugin-forge crie ou 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

Esse escopo ajuda no planejamento da revisão, porque a plugin-forge costuma gerar mudanças em vários arquivos.

Dicas práticas para melhorar a qualidade da saída da plugin-forge

Peça à plugin-forge para:

• preservar exatamente os nomes e caminhos existentes dos plugins
• manter todos os identificadores em kebab-case
• mostrar juntos o manifesto do plugin e a entrada do marketplace
• explicar quaisquer campos obrigatórios que ela não conseguiu inferir
• separar “generated files” de “manual follow-up”
• validar se versões e nomes batem entre os manifestos

Esses pedidos reduzem a chance de uma saída bonita, mas não instalável.

FAQ da skill plugin-forge

Vale a pena usar a plugin-forge se eu já sei escrever bons prompts?

Sim, se o seu principal risco for correção estrutural. A skill plugin-forge é mais útil do que um prompt comum quando você precisa de manifestos consistentes, entradas de marketplace corretas e layout de diretórios estável. Se você só precisa de ajuda para escrever um único arquivo de command dentro de um plugin existente, a vantagem é menor.

A plugin-forge é amigável para iniciantes?

Na maior parte, sim. A plugin-forge dá aos iniciantes um caminho concreto para criar e testar plugins. O ponto é que, mesmo assim, iniciantes ainda precisam entender onde fica a raiz do marketplace, quais convenções de nomenclatura usar e quais componentes realmente querem. Ela ajuda mais com estrutura do que com design de produto.

Quando eu não devo usar a plugin-forge?

Evite a plugin-forge se:

• você não está criando um plugin do Claude Code
• você não usa distribuição no estilo marketplace
• você quer apenas geração genérica de código Python ou JavaScript
• seu repositório tem um layout de plugin customizado que difere de propósito da estrutura documentada

Nesses casos, a plugin-forge pode te empurrar para o formato errado.

A plugin-forge cuida da publicação automaticamente?

Não por completo. A skill cobre bem a etapa de preparação: scaffold, manifestos, registro no marketplace, orientação para teste local e atualização de versão. Mas ela não é uma plataforma de release ponta a ponta. Você ainda precisa revisar os arquivos, testar localmente e executar seu próprio processo de publicação ou distribuição.

Qual é o maior bloqueador de adoção?

Geralmente, falta de contexto do repositório. A plugin-forge assume que você sabe onde fica a raiz do marketplace e como seu plugin deve ser categorizado. Se você não consegue responder a isso, a saída ainda será útil como rascunho, mas não pronta para produção.

Como a plugin-forge se compara à edição manual de manifestos?

Editar manualmente funciona para mudanças pontuais, mas a plugin-forge é melhor quando você quer repetibilidade ou precisa evitar divergência entre plugin.json e marketplace.json. Os scripts incluídos são a vantagem prática mais clara.

Como melhorar a skill plugin-forge

Dê à plugin-forge entradas conscientes do repositório

A melhor melhoria é fornecer caminhos exatos e os arquivos atuais. Em vez de pedir “um version bump”, diga:

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.

Isso empurra a skill para mudanças verificáveis em vez de conselhos genéricos.

Peça saída arquivo por arquivo, não apenas um resumo

A plugin-forge funciona melhor quando você pede entregáveis concretos:

• plugin.json completo
• entrada exata do marketplace
• árvore de diretórios proposta
• início de README
• comandos de follow-up para testar localmente

Isso é especialmente importante para plugin-forge em Code Generation, em que o valor está nos arquivos prontos para aplicar.

Evite os modos de falha mais comuns

Fique atento a estes problemas na saída da plugin-forge:

• o nome do plugin difere entre arquivos
• o caminho source do marketplace não bate com o layout real das pastas
• a versão foi atualizada em um manifesto, mas não no outro
• componentes opcionais são mencionados nos metadados, mas não foram criados
• a estrutura gerada omite .claude-plugin/plugin.json

Uma revisão rápida com base em references/plugin-structure.md e references/marketplace-schema.md detecta a maioria deles.

Use um fluxo em duas etapas para resultados melhores

Na prática, um bom guia de uso da plugin-forge é:

1. primeira etapa: gerar estrutura e manifestos
2. segunda etapa: gerar componentes do plugin e melhorar o README

Tentar fazer scaffold, lógica de negócio, documentação, configuração de testes e notas de publicação em um único prompt geralmente piora a qualidade. A plugin-forge é mais forte quando a estrutura vem primeiro.

Itere após a primeira saída com correções direcionadas

Não diga apenas “corrija isso”. Dê instruções exatas de ajuste, por exemplo:

• “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.”

Esse tipo de iteração com restrições torna a plugin-forge muito mais confiável.

Combine a plugin-forge com a documentação de referência, não no lugar dela

A melhor forma de melhorar a saída da plugin-forge é pedir explicitamente que ela cite ou siga as referências do repositório. Nos prompts, mencione:

• references/plugin-structure.md para expectativas de diretórios
• references/marketplace-schema.md para campos do marketplace
• references/workflows.md para fluxo de instalação e testes

Assim, a skill fica ancorada nas convenções reais do repositório, em vez de recorrer a suposições genéricas sobre plugins.