devetai/better-plugin-gen

Better Plugin Generator (better-plugin-gen)

Esta skill ajuda o usuário a criar um plugin: um diretório que empacota múltiplos componentes (como skill, agente, hook, servidor MCP) para instalação em um agente de código com um único comando. A skill suporta três hosts (ferramentas de agente que carregam plugins): Claude Code, Codex, Antigravity. Cada host tem seu próprio manifesto; a skill usa o diretório comum skills/ e gera manifestos para cada host selecionado.

Todos os caminhos template.md, references/, examples/, scripts/ abaixo são relativos ao diretório que contém este arquivo SKILL.md.

---

1. Princípios Centrais

1. Perguntar primeiro, gerar depois. Todas as escolhas são feitas perguntando ao usuário com uma ferramenta de perguntas estruturadas, se houver; caso contrário, liste as opções numeradas, destaque a recomendada e aguarde a resposta. Antes de cada pergunta, escreva brevemente: o que o plugin fará, o que a pergunta quer saber e por que ela surgiu. Não preencha pontos obscuros e gere arquivos automaticamente.
2. Não adivinhe especificações do host. A localização dos arquivos, o formato do manifesto e do MCP seguem references/hosts.md. Pontos marcados como "não verificado" devem ser reportados ao usuário.
3. Lógica principal na skill. A skill é o único componente que roda em todos os três hosts. Agentes, comandos, hooks, LSP só são adicionados quando o usuário precisa e o host suporta.
4. Estrutura mínima funcional. Cada componente gerado deve ser executável imediatamente, mas conciso. Se o projeto tiver as skills better-skill-gen ou better-agent-gen, sugira ao usuário usá-las para escrever skills ou agentes detalhados depois que o plugin estiver pronto.
5. Auto-validação. O plugin só é entregue quando scripts/validate.sh retorna código de saída 0.
6. Sem efeitos colaterais externos. A skill só grava arquivos dentro do diretório do plugin de destino (e o arquivo de marketplace na raiz do repositório, se o usuário escolher). Não executa git commit, git push, não instala o plugin, não altera a configuração do host do usuário; apenas imprime os comandos para ele executar.

---

2. Entrada

• Obrigatório: para que serve o plugin (uma frase já basta), ou o caminho de um plugin existente quando quiser adicionar componentes. Obtido da solicitação do usuário.
• Perguntar se não tiver: host de destino, localização do diretório, lista de componentes, se terá marketplace, nome do plugin, autor, licença.
• Informação faltante: perguntar conforme a seção 3, passo 2; sem resposta, aguardar.

---

3. Fluxo de Trabalho

Passo 1: Determinar o modo e ler o estado atual

• Criação nova: o usuário descreve o plugin, ainda não há diretório.
• Adicionar componente / adicionar host: o usuário fornece um caminho que contém .claude-plugin/plugin.json, .codex-plugin/plugin.json ou plugin.json. Leia todos os manifestos, liste os componentes existentes, execute o comando shell bash scripts/validate.sh <dir> para conhecer os erros atuais antes de corrigir.
• Criar marketplace: o usuário já tem o plugin, só precisa publicá-lo. Leia o plugin como acima e vá para o passo 6.
• Leia references/hosts.md. Se a 'Data de verificação' for mais antiga que 30 dias, ou se o plugin precisar de funcionalidade ainda não presente no arquivo: consulte as fontes na seção 6 desse arquivo na web, atualize o arquivo e a data de verificação, e informe ao usuário o que foi alterado.

Passo 2: Perguntar ao usuário

Resuma o que foi entendido (o que o plugin faz, quem usa, quando executa), depois faça a rodada 1 de perguntas, pulando qualquer pergunta que o usuário já tenha respondido claramente:

Pergunta	Tipo	Opções (recomendação primeiro)
Em qual host o plugin será executado?	Múltipla escolha	Claude Code; Codex; Antigravity. Recomende todos os três se o plugin consistir apenas de skill e MCP; apenas Claude Code se precisar de hook, LSP ou userConfig
Onde colocar o plugin?	Escolha um	Repositório próprio, plugin na raiz (./<nome>/); dentro de um repositório de marketplace (plugins/<nome>/); no projeto atual para teste
Quais componentes o plugin terá?	Múltipla escolha	Skill; Agente; Hook; Servidor MCP; Comando; LSP; userConfig
Criar marketplace para publicação?	Escolha um	Sim, para os hosts selecionados; Não, apenas teste local

Rodada 2 (se necessário): nome do plugin (sugira um nome em kebab-case derivado da descrição), autor e repositório GitHub, licença, detalhes de cada componente (o que a skill faz, quais ferramentas o agente pode usar, em qual evento o hook executa, qual servidor MCP e se precisa de token).

Regras ao perguntar:

• Usuário escolheu hook com host diferente do Claude Code: avise sobre o conflito em references/hosts.md seção 4, pergunte se deseja manter o hook.
• Plugin precisa de token ou senha: pergunte como fornecê-lo (Claude Code: userConfig com sensitive: true; outros hosts: variável de ambiente documentada no README). Nunca grave valores secretos em arquivos.
• Nome igual a um nome proibido do Claude Code (references/hosts.md seção 2.1): sugira outro nome.
• Diretório de destino já contém arquivos: liste os arquivos que serão sobrescritos e pergunte antes de gravar.

Passo 3: Finalizar o design

Escreva um resumo no chat: nome, hosts, localização, árvore de diretórios a ser criada (marque o host de cada arquivo), quais componentes rodam em qual host, valores que o agente definirá automaticamente, pontos não verificados. Se a resposta levantar novos pontos obscuros, pergunte novamente; não gere arquivos ainda.

Passo 4: Gerar arquivos

1. Leia template.md (estrutura de cada arquivo) e references/components.md (formato de cada componente). Leia examples/sample.md para entender o nível de detalhe desejado.
2. Grave o manifesto para cada host selecionado. name, version, description idênticos em todos os manifestos.
3. Grave os componentes na raiz do plugin, não dentro de .claude-plugin/ ou .codex-plugin/:
   • Skill: skills/<nome>/SKILL.md, frontmatter apenas com name e description, para que qualquer host possa ler.
   • MCP: .mcp.json para Claude Code e Codex; mcp_config.json para Antigravity (servidor remoto usa serverUrl). Ambos os arquivos com a mesma lista de servidores.
   • Hook: hooks/hooks.json envolto na chave "hooks", sempre com matcher, chame o script usando "${CLAUDE_PLUGIN_ROOT}" (variável do Claude Code). Script em scripts/, com shebang.
   • Agente, comando, LSP, userConfig: conforme references/components.md.
4. Grave README.md a partir do template Arquivo 8, no mínimo 40 palavras, com tabela de componentes por host e comandos de instalação para cada host (references/publishing.md seção 5).
5. Modo adicionar componente: apenas adicione novos arquivos e corrija as chaves necessárias no manifesto; incremente version (patch) em todos os manifestos se o plugin já foi publicado.

Passo 5: Auto-validação

1. Execute o comando shell HOSTS="<hosts selecionados>" bash scripts/validate.sh <diretório-do-plugin-ou-repositório>. Exemplo: HOSTS="claude codex antigravity".
2. O script executa check_plugin.py (manifesto, nome, caminhos, MCP, hook, skill, agente, marketplace, placeholders, strings parecidas com segredos), depois claude plugin validate e agy plugin validate se os comandos estiverem disponíveis.
3. Se houver [FAIL] ou o CLI reportar erro: corrija os arquivos, execute novamente até obter código de saída 0.
4. Leia cada [WARN]: corrija se possível; se mantiver (ex.: aviso de hook multi-host já informado ao usuário), documente o motivo no relatório de entrega.
5. Se precisar de arquivos temporários, grave no diretório temporário especificado pelo usuário; se não houver, use o diretório temporário do sistema operacional; remova imediatamente após a verificação.

Passo 6: Marketplace (se selecionado)

• Claude Code: .claude-plugin/marketplace.json na raiz do repositório (template Arquivo 9).
• Codex: .agents/plugins/marketplace.json na raiz do repositório (template Arquivo 10).
• Antigravity: sem arquivo necessário; o README deve conter o comando agy plugin install com a URL do repositório GitHub, ex.: https://github.com/phucbui/pr-review-kit.
• Execute novamente o passo 5 com o diretório raiz do repositório para validar também o marketplace.

Passo 7: Entrega

Imprima o relatório conforme o template "Relatório de Entrega" no final de template.md: diretório, hosts, resultado da validação, tabela de arquivos, pontos não verificados, comandos para teste local, comandos de publicação para o usuário executar (references/publishing.md seções 3 a 6). Se existirem better-skill-gen ou better-agent-gen no projeto, sugira uma linha sobre como usá-los para escrever componentes detalhados.

---

4. Restrições

• Obrigatório:
  • Perguntar sobre host, localização, componentes, marketplace antes de criar arquivos; não decidir pontos obscuros automaticamente.
  • Gravar apenas no diretório do plugin de destino e no arquivo de marketplace na raiz do repositório; não criar arquivos de exemplo em outros lugares. Exemplos residem apenas em examples/ desta skill.
  • Não executar git commit, git push, claude plugin install, agy plugin install, codex plugin marketplace add; apenas imprimir os comandos.
  • Não gravar tokens, senhas ou chaves de API em nenhum arquivo.
  • Entregar apenas quando scripts/validate.sh retornar código 0.
• Recomendado:
  • Nomear plugin, skill e agente em kebab-case; versão inicial 0.1.0.
  • Manter o plugin focado em um único propósito; separar em plugins diferentes se o usuário juntar funcionalidades não relacionadas.
  • Deixar claro no README qual componente roda em qual host.
• Não recomendado:
  • Copiar SKILL.md com campos específicos do Claude Code para um plugin destinado a Codex ou Antigravity.
  • Usar caminhos absolutos ou .. em manifestos, hooks, MCP.
  • Colocar CLAUDE.md na raiz do plugin; se precisar de instruções de carregamento, coloque dentro da skill.