Em 24 de fevereiro de 2026, a Anthropic anunciou marketplaces privados de plugins para Claude Code, dando aos administradores uma forma de construir, hospedar e controlar plugins sem tocar nos registros públicos da Anthropic. O que você obtém deste post: os passos exatos para agrupar uma skill e conectar a um plugin distribuível, hospedá-lo em um repositório GitHub privado, fixar versões e diagnosticar as quebras mais comuns quando uma segunda máquina se recusa a instalar de forma limpa.
Quando uma equipe precisa de um plugin
O marketplace público é bom para experimentação individual. Uma vez que você tem mais de uma pessoa confiando no mesmo slash command ou no mesmo script de hook, a distribuição ad-hoc desaba rapidamente. Alguém copia um arquivo manualmente, usa um caminho ligeiramente diferente, e Claude Code silenciosamente ignora o hook porque o nome não corresponde ao que o registro espera.
Esse é o gatilho real para um marketplace privado: consistência entre máquinas, não quantidade de pessoas. Se você tem dois desenvolvedores e ambos precisam do mesmo hook de deployment, um marketplace privado vale a hora de configuração. Se você tem vinte, não é opcional.
O outro gatilho é confidencialidade. A documentação de criação de plugins da Anthropic é explícita: para manter um plugin interno à sua equipe, você hospeda o marketplace em um repositório privado. Submeter a claude-community publica seu plugin para qualquer um ver e instalar. Um repositório privado evita isso completamente. Se seu plugin contém padrões de API internos, slash commands proprietários, ou qualquer coisa que você prefira não indexar, o caminho privado é o correto.
Vale notar: se sua equipe já está executando servidores MCP em produção, verifique como a distribuição privada de plugins se encaixa nessa stack antes de se comprometer com uma estrutura, já que as duas abordagens têm casos de uso sobrepostos mas distintos.
Agrupe uma skill e hook existentes
Um plugin é uma pasta. Essa é a resposta honesta. Conforme a documentação oficial de plugins, a estrutura viável mínima se parece com isto:
my-plugin/
plugin.json
README.md
skills/
my-skill.md
hooks/
hooks.json
guard.sh
O plugin.json é o manifesto. Ele nomeia o plugin, declara uma versão e aponta para os subdiretórios de skills e hooks. Um exemplo ilustrativo resumido:
{
"name": "deployment-tools",
"version": "1.2.0",
"description": "Deployment workflow helpers for the platform team",
"skills": ["skills/"],
"hooks": "hooks/hooks.json"
}
Skills são arquivos markdown que definem o que Claude sabe como fazer, e slash commands vivem dentro deles. Hooks são declarações JSON que conectam scripts shell a pontos de gatilho (antes de uma chamada de ferramenta, depois de uma sessão, e assim por diante). Você pode agrupar qualquer combinação dos dois em uma única pasta de plugin. A documentação de skills observa que comandos personalizados agora fazem parte do modelo de skills, então não tente mantê-los como um sistema paralelo separado.
Uma coisa que pega as pessoas: scripts de hook devem ser executáveis. Execute chmod +x hooks/guard.sh antes de fazer commit. Claude Code verifica o bit de permissão e pulará silenciosamente um hook se ele não estiver definido.
Crie e distribua um marketplace privado
Um marketplace é um repositório GitHub com uma estrutura de pasta específica. Cada plugin vive em seu próprio subdiretório. Na raiz do repo você precisa de um registry.json que catalogue o que está disponível. A documentação de marketplace de plugins descreve essa estrutura em detalhes, e a demo comunitária em mrlm-xyz/demo-claude-marketplace mostra dois exemplos de plugins funcionando com agentes, comandos e skills se você quiser uma referência concreta antes de construir do zero.
Depois que o repositório existir, informe Claude Code sobre ele em .claude/settings.json na raiz do repositório:
{
"extraKnownMarketplaces": {
"company-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
},
"enabledPlugins": {
"deployment-tools@company-tools": true,
"code-formatter@company-tools": true
}
}
Faça commit desse arquivo. Agora todo membro da equipe que confia na pasta do projeto terá o marketplace adicionado automaticamente, sem prompt separado e sem etapa manual de CLI. O bloco enabledPlugins significa que esses dois plugins estão ativos por padrão. Quem não quiser pode desabilitar localmente; os padrões apenas removem atrito para todos os outros.
Se você está em um plano Team ou Enterprise e distribuindo através das configurações da Organização, o repositório do marketplace deve ser privado ou interno. O Claude GitHub App o lê, então você precisará conceder acesso explicitamente. Um repositório público falha silenciosamente nesse caminho, que é um dos modos de erro mais confusos.
Para equipes que gerenciam trabalho com Claude Code voltado para clientes em grande escala, os serviços de agência Claude Code da Seahawk cuidam da configuração do marketplace e da governança contínua de plugins se você preferir não possuir essa infraestrutura.
Controle versões e revise atualizações
É aqui que a maioria dos marketplaces privados falha. As pessoas fixam uma versão em plugin.json, enviam uma mudança breaking na mesma tag e se perguntam por que o rollback não funcionou. Git tags são a unidade certa de verdade de versão aqui, não apenas a string de versão no manifest.
O workflow que realmente funciona:
- Incremente o campo
versionemplugin.json(siga semver:1.2.0para1.3.0para adições compatíveis com versões anteriores,2.0.0para mudanças breaking). - Faça commit e push.
- Crie uma git tag:
git tag v1.3.0 && git push origin v1.3.0. - Atualize
registry.jsonpara apontar a entrada do plugin para a nova tag.
Para instalar uma versão específica em uma máquina:
/plugin install deployment-tools@company-tools --version 1.3.0
Para fazer rollback para a tag anterior:
/plugin install deployment-tools@company-tools --version 1.2.0
A flag --version resolve contra git tags no repositório de origem. Se você não tiver feito tag, Claude Code volta para o HEAD do branch padrão, o que significa que "rollback" não tem sentido. Faça tag de cada release. Leva dez segundos e evita dores reais.
Para revisão de atualização, trate o repositório do marketplace como qualquer outro codebase de produção: exija um pull request, no mínimo uma aprovação e uma entrada de changelog em README.md antes de fazer merge para main. A própria documentação da Anthropic observa que plugins são componentes altamente confiáveis que podem executar código arbitrário, então uma política de uma-pessoa-pode-fazer-merge em um repositório de plugin é uma má ideia independentemente do tamanho da equipe.
Teste instalação em uma segunda máquina
Antes de dizer à equipe mais ampla para puxar o novo plugin, instale-o em um perfil completamente novo. Não em uma janela de terminal diferente. Um perfil novo sem segredos incorporados, sem estado de plugin existente e sem entradas de marketplace pré-configuradas além do que está no settings.json do repositório.
Checklist numerada para um teste limpo em segunda máquina:
- Clone o repositório do projeto.
- Abra Claude Code e confie na pasta quando solicitado.
- Confirme que o marketplace aparece com
/plugin marketplace list. - Instale o plugin explicitamente:
/plugin install deployment-tools@company-tools. - Execute o comando slash que o plugin expõe e verifique se ele retorna o resultado esperado.
- Verifique se o hook dispara acionando a chamada de ferramenta relevante e inspecionando o resultado.
- Confirme que nenhuma credencial ou caminho local da sua máquina de desenvolvimento apareça na resposta.
Essa última verificação é importante. Scripts de hook que referenciam caminhos absolutos (/Users/yourname/scripts/...) quebram em qualquer outra máquina. Use caminhos relativos ao diretório do plugin ou variáveis de ambiente que as equipes possam configurar consistentemente.
Solucione problemas de nomes, caminhos e dependências
A maioria das falhas de instalação é uma de três coisas.
Incompatibilidade de nomes. O nome do plugin em plugin.json deve corresponder exatamente ao nome do diretório no repositório do marketplace e ao nome usado em registry.json. Sensível a maiúsculas e minúsculas. Se plugin.json diz deployment-tools e a entrada de registro diz Deployment-Tools, o comando de instalação retorna um erro de não encontrado que parece não estar relacionado à capitalização.
Problemas de caminho em hooks. Como mencionado acima, caminhos absolutos são a maior fonte de bugs "funciona na minha máquina". Audite cada script de hook em busca de caminhos codificados antes de marcar um lançamento. Um grep -r "/Users" hooks/ rápido detecta o mais comum.
Lacunas de dependência. Se seu script de hook chamar um binário externo (jq, gh, docker, uma CLI interna customizada), documente essa dependência em README.md com a versão mínima. Claude Code não resolve dependências de binários externos para você. Um hook que sai silenciosamente porque jq não está instalado é difícil de diagnosticar, especialmente para um membro da equipe que não conhece o hook.
Algumas outras coisas que valem a pena verificar se a instalação travasse:
- O GitHub App precisa de acesso de leitura ao repositório do marketplace privado. Verifique as configurações da Organização se a busca travar.
- Se
extraKnownMarketplacesestiver emsettings.jsonmas o marketplace não aparecer após confiar na pasta, confirme que o arquivo foi commitado e que o prompt de confiança foi aceito, não descartado. - Nomes de plugins em
enabledPluginsdevem usar o formatoname@marketplaceexatamente.deployment-toolssozinho não será resolvido sem o qualificador de marketplace.
A série dev.to do Nagell aborda versionamento automático e CI de lançamento em mais profundidade se você quiser conectar GitHub Actions ao fluxo de marcação. Vale a pena ler antes de você construir o passo de CI manualmente.
Para contexto mais amplo sobre como Claude Code se encaixa em um fluxo de trabalho de desenvolvimento real além de apenas plugins, esta visão geral dos superpoderes do Claude Code é uma leitura complementar útil.
FAQ
Posso hospedar o marketplace em algum lugar diferente do GitHub?
O campo source em settings.json suporta github e local como tipos de fonte de acordo com a documentação atual do plugin marketplace. Um caminho local funciona para uma única máquina ou um compartilhamento de rede montado, mas não atualiza automaticamente da forma como uma fonte baseada em git. Para distribuição em equipe com rastreamento de versão, um repositório GitHub privado é a escolha prática no momento.
Os membros da equipe precisam de seu próprio acesso ao GitHub para o repositório do marketplace privado?
Não diretamente. Se você estiver distribuindo através das configurações da Organização em um plano Team ou Enterprise, o GitHub App do Claude lê o repositório em seu nome. Se você estiver usando extraKnownMarketplaces em settings.json sem o caminho de sincronização org, cada usuário precisa de acesso de leitura ao repositório através de suas próprias credenciais do GitHub ou uma chave de deploy.
Qual é a diferença entre `enabledPlugins` e instalar um plugin?
enabledPlugins em settings.json ativa plugins automaticamente quando a pasta do projeto é confiável. É um padrão, não uma instalação forçada. Um usuário ainda pode desativar um plugin localmente. A instalação manual via /plugin install adiciona o plugin independentemente do que settings.json diz. Os dois mecanismos funcionam juntos: padrões para conveniência, instalação manual para qualquer coisa fora do contexto do projeto.
Posso ter vários marketplaces privados em uma organização?
Sim. O objeto extraKnownMarketplaces aceita várias chaves. Cada chave é um alias de marketplace local, e cada uma aponta para um repositório de fonte separado. Você poderia ter company-tools, data-team-plugins e security-tools todos registrados no mesmo settings.json. Apenas certifique-se de que os aliases são únicos e não colidem com claude-plugins-official ou claude-community.
Como isso interage com o marketplace oficial do Anthropic?
Coexistem. Claude Code registra claude-plugins-official automaticamente no primeiro lançamento interativo. Seu marketplace privado é adicionado junto. Plugins do seu marketplace privado são referenciados como plugin-name@your-alias; plugins oficiais como plugin-name@claude-plugins-official. Sem conflito, contanto que seus nomes de plugin não duplichem os oficiais e causem ambiguidade na resolução.
O caveat mais importante de tudo isso: git tags são o único mecanismo confiável de rollback. Uma string de versão em plugin.json sem uma tag correspondente é apenas decoração, não uma opção de recuperação.