O Que Define a Qualidade de um Plugin de Produção
Um plugin que fica no dotfiles pessoal e um plugin publicado no marketplace público exigem níveis de qualidade completamente diferentes. O primeiro pode se contentar com "funciona no meu ambiente", mas o segundo precisa considerar uma variedade de sistemas operacionais, versões do Node.js, shells, coexistência com configurações existentes, experiência de onboarding e estratégia de upgrade.
Em abril de 2026, o marketplace oficial de plugins da Anthropic conta com mais de 1.800 plugins publicados, mas apenas cerca de 100 ultrapassam 1.000 instalações ativas por semana. O que gera essa diferença não é a sofisticação das funcionalidades, mas sim "fundamentos sólidos e pouco glamorosos": qualidade do manifesto, documentação, disciplina de versionamento e boas práticas de merge de configurações.
Estrutura de Repositório Padrão
A estrutura padrão de um repositório de plugin é a seguinte.
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # Manifesto (obrigatório) ├── commands/ # Slash commands │ ├── review.md │ └── deploy.md ├── skills/ # Skills │ └── security-audit/ │ └── SKILL.md ├── agents/ # Definições de subagentes │ └── researcher.md ├── hooks/ # Configuração de hooks │ └── hooks.json ├── mcp/ # Servidores MCP incluídos │ ├── server.ts │ └── package.json ├── scripts/ # Scripts de instalação e migração │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
Repositórios populares como gsd-build/get-shit-done e wshobson/agents convergem quase que completamente para essa estrutura. Em especial, a convenção de colocar `.claude-plugin/plugin.json` no topo é uma regra praticamente obrigatória, pois o comando `plugin add` da CLI da Anthropic busca esse caminho de forma fixa.
Como Escrever o Manifesto plugin.json
O `plugin.json` deve ter, no mínimo, os seguintes campos.
```json { "name": "gsd-build", "displayName": "Get Shit Done", "version": "2.4.1", "description": "Stop-hook driven task persistence for Claude Code", "author": { "name": "GSD Team", "url": "https://github.com/gsd-build" }, "license": "MIT", "homepage": "https://github.com/gsd-build/get-shit-done", "repository": "https://github.com/gsd-build/get-shit-done.git", "claudeCode": { "minVersion": "2.8.0" }, "commands": ["commands/"], "skills": ["skills/"], "agents": ["agents/"], "hooks": "hooks/hooks.json", "mcpServers": { "gsd-db": { "command": "node", "args": ["mcp/server.js"] } }, "configSchema": "config.schema.json", "telemetry": { "endpoint": "https://telemetry.gsd.dev/v1" } } ```
O campo `claudeCode.minVersion` deve ser atualizado sempre que houver uma mudança incompatível. O pior cenário de experiência do usuário é o plugin ser instalado em uma CLI antiga e apresentar falhas silenciosas. O `configSchema` fornece validação das configurações do usuário no formato JSON Schema e exibe mensagens de erro úteis em caso de configuração incorreta.
Versionamento Semântico na Prática
O versionamento de plugins segue o semver como base, mas decidir "o que conta como mudança incompatível" tem suas dificuldades específicas. Renomear um slash command, alterar o `matcher` de um hook existente ou adicionar um campo obrigatório ao `inputSchema` de uma ferramenta MCP são todas mudanças incompatíveis. Por outro lado, adicionar um novo comando, adicionar um argumento opcional a um comando existente ou adicionar uma nova ferramenta MCP justifica apenas um incremento de versão menor.
Recomenda-se fortemente o formato Keep a Changelog para o `CHANGELOG.md`. A UI do marketplace parseia automaticamente o `CHANGELOG.md` e o exibe na tela de atualização, então a padronização do formato tem um impacto prático direto. Na KGA IT, impomos esse formato em todos os projetos, incluindo os plugins internos.
Distribuição no Marketplace
Em abril de 2026, existem três principais canais de distribuição. O primeiro é o marketplace oficial da Anthropic (claude.ai/plugins), que possui revisão mas oferece a maior visibilidade. O segundo é a instalação direta a partir de um repositório GitHub (`claude plugin add github.com/user/repo`), que não exige revisão e tem publicação imediata, sendo popular entre autores de projetos open source. O terceiro é um marketplace privado, onde as empresas hospedam internamente um `claude-plugin-registry` para distribuição corporativa.
Na revisão do marketplace oficial, são verificados: a razoabilidade dos comandos shell executados, a declaração explícita dos destinos de rede, o tratamento de informações pessoais e, no caso de plugins pagos, a segurança do fluxo de pagamento. Em fevereiro de 2026, foi introduzido o sistema de "audit badge", e plugins que passaram na análise estática recebem um badge verde. Dados publicados mostram que ter esse badge mais do que dobra a taxa de adoção, portanto sua obtenção é fortemente recomendada.
Telemetria e Observabilidade
Para operar um plugin, é essencial entender "quem está usando e de que forma". Porém, os usuários do Claude Code têm alta consciência de privacidade, e telemetria opaca resulta em desinstalação imediata. A abordagem recomendada é baseada em três princípios: "opt-in, anônimo e envio apenas de valores agregados".
Na prática, na primeira inicialização, exibe-se um prompt perguntando "Você concorda com o envio de estatísticas de uso anônimas?" e, somente em caso afirmativo, envia-se diariamente o ID de instalação e a contagem de chamadas de cada comando. O conteúdo de prompts individuais ou caminhos de arquivos jamais devem ser enviados. O wshobson/agents agrega um ranking dos Subagents mais populares com esse método e o publica mensalmente no README. Isso também funciona como um sinal de que "este plugin é gerenciado de forma saudável".
Acompanhar APIs com Mudanças Incompatíveis
O Claude Code em si acelerou o ritmo de adição de funcionalidades no segundo semestre de 2025, e há casos raros em que plugins existentes param de funcionar até em versões menores. Em janeiro de 2026, quando o Claude Code 3.0 alterou o contrato de Hook — tornando obrigatório o repasse de JSON via stdin — cerca de 1.200 plugins foram obrigados a se atualizar em duas semanas.
A contramedida tem duas camadas. Primeiro, especificar rigorosamente o `claudeCode.minVersion` no `plugin.json` para que o plugin não inicie em CLIs sem suporte. Depois, automatizar a verificação de funcionamento em novas versões usando o `claude-code-nightly` em GitHub Actions. A Anthropic passou a publicar a `plugin-compat-matrix` em fevereiro, tornando visível o status de funcionamento dos plugins oficiais em cada versão da CLI. Terceiros também estão seguindo esse esquema.
Estratégia de Merge das Configurações do Usuário
O plugin escreve em `.claude/settings.json`, mas não deve corromper as configurações existentes do usuário. A implementação recomendada é o "patch baseado em JSON Pointer". No momento da instalação do plugin, o patch de diferença é salvo em `.claude/plugins/<name>/applied-patch.json` para que possa ser revertido com precisão no momento da desinstalação.
Deve-se ter atenção especial ao merge do array `permissions`. Para não conflitar com as regras allow/deny existentes do usuário, é uma prática que está se tornando padrão isolar as regras específicas do plugin com um prefixo de namespace (ex.: `"gsd:*"`). O get-shit-done adotou esse método de forma pioneira e se tornou uma implementação de referência para muitos plugins subsequentes.
Operação Após a Publicação
Publicar não é o fim. A velocidade de resposta inicial às Issues no GitHub, a emissão imediata de patches quando há violação do semver, os procedimentos para emissão de avisos de segurança, a notificação aos usuários sobre avisos de deprecação — a qualidade dessas operações define a taxa de adoção a longo prazo. Quanto mais popular o plugin, maior a carga operacional, e há casos em que se torna necessário aumentar a equipe de mantenedores ou formalizar a iniciativa.
Na KGA IT, ao entregar plugins internos para clientes, empacotamos tudo junto: runbook de operação, esquema de plantão e reuniões de revisão trimestral. Um plugin não é um entregável, mas um produto — e a responsabilidade operacional surge no momento da publicação em produção. Essa consciência é a linha que separa um plugin profissional de um plugin amador.