SpyBara
Go Premium

plugins/publish.md 2026-09-28 22:59 UTC to 2026-09-29 12:59 UTC

This page contains 29 additions and 26 deletions.

2026
Fri 25 23:58 Mon 28 22:59 Tue 29 14:57

Publicar e distribuir um plugin

Publique um plugin Claude Code através do seu próprio marketplace ou do diretório da Anthropic, com uma lista de verificação de pré-lançamento e como os usuários recebem atualizações.

Publicar um plugin Claude Code significa listá-lo em um marketplace, um catálogo JSON que lista plugins e onde buscar cada um, para que outras pessoas possam instalá-lo pelo nome e receber suas atualizações. Você pode executar seu próprio marketplace ou enviar seu plugin para o diretório da Anthropic. Para compartilhar um plugin sem publicá-lo, envie o diretório do plugin ou um .zip dele para que as pessoas carreguem por conta própria.

Esta página é para o autor de um plugin funcional que está pronto para compartilhá-lo.

Comece com Escolha como distribuir para comparar as opções de distribuição. Se você já conhece sua rota, vá para Prepare seu plugin para lançamento, depois siga a seção da sua rota para o que contar aos seus usuários e como eles recebem suas atualizações.

Escolha como distribuir

Escolha uma opção de distribuição com base em quem precisa instalar o plugin:

Rota Quem pode instalar O que você precisa Os usuários recebem suas atualizações automaticamente?
Sem marketplace As pessoas para as quais você envia a pasta do plugin ou um .zip dele A pasta do plugin Nenhuma. Eles carregam a cópia que você enviou
Seu próprio marketplace Qualquer pessoa que possa acessar o repositório, que pode ser um privado que sua equipe pode clonar Um repositório git ou outro host com um .claude-plugin/marketplace.json que lista seu plugin Desativado
Diretório da Anthropic Pessoas que o adicionam em claude.ai ou em Cowork. Ele também é carregado em suas sessões do Claude Code através de sincronização de conta Um repositório GitHub contendo o plugin e um plano claude.ai pago para enviar Sim, após a versão que você envia ser publicada

Auto-atualização é uma configuração por marketplace no lado do usuário que busca novas versões em segundo plano.

Prepare seu plugin para lançamento

O nome, a versão, validação e uma instalação a partir de um marketplace decidem se um lançamento funciona para as pessoas que o instalam. Verifique-os antes do primeiro lançamento e novamente antes de cada um posterior.

1

Escolha um nome permanente

Os usuários instalam, habilitam e configuram seu plugin por name@marketplace, então um plugin renomeado é um plugin diferente para cada instalação existente. Escolha um nome em kebab-case como deploy-helper, porque claude plugin validate avisa sobre outras formas, e trate-o como permanente. Defina displayName em plugin.json para o rótulo que os usuários veem.

2

Decida como você versionar

Se você definir version em plugin.json e depois fazer push de commits sem alterá-lo, claude plugin update imprime <name> is already at the latest version (1.0.0). e os usuários mantêm a cópia antiga. Incremente version em cada lançamento ou omita-o em um marketplace hospedado em git para que Claude Code use o SHA do commit. Veja Versões e atualizações.

3

Valide

Em seu shell, execute claude plugin validate --strict ./your-plugin. Uma execução limpa imprime ✔ Validation passed.

  • Em CI: mantenha --strict, que também falha a execução com código de saída 1 em avisos como um campo de manifesto desconhecido ou um version ausente. Remova --strict se você escolheu omitir version na etapa anterior.
  • Caminhos: a validação relata caminhos de componentes que não começam com ./. Dentro de comandos hook e configurações de servidor MCP, consulte arquivos como ${CLAUDE_PLUGIN_ROOT}/.... Veja regras de caminho.
4

Instale-o a partir de um marketplace local

Em seu shell, adicione um marketplace local que lista o plugin com claude plugin marketplace add ./path-to-marketplace, instale o plugin a partir dele e inicie uma sessão para confirmar que ele carrega.

5

Preencha os metadados que os usuários veem

Defina description, author, homepage e repository em plugin.json e adicione um README.md na raiz do plugin. homepage deve ser analisado como uma URL. A referência de manifesto lista todos os campos.

6

Execute sua suite de avaliação

Se você tiver uma suite de avaliação, execute claude plugin eval em seu shell. Ele executa os casos de teste do plugin e pontua os resultados, o que detecta regressões quando você altera o plugin. Veja Teste plugins com evals.

Compartilhe um plugin sem um marketplace

Se o plugin estiver em um repositório git, as pessoas podem cloná-lo e carregar o checkout, ou iniciar Claude Code a partir de seu shell com --plugin-url apontando para um .zip que você anexa a um lançamento. Para obter sua próxima versão, eles puxam ou baixam novamente. Se não estiver em um repositório, envie-lhes o diretório ou um .zip dele. Eles o carregam de uma de duas maneiras:

  • Para uma sessão: eles iniciam Claude Code a partir de seu shell com claude --plugin-dir ./deploy-helper, onde o caminho é o clone, a pasta descompactada ou o próprio .zip. Veja Sinalizadores que carregam um plugin para uma sessão.
  • Para cada sessão: eles movem o diretório do plugin, com seu .claude-plugin/plugin.json, sob ~/.claude/skills/ para que Claude Code o carregue em cada sessão.

Adicionar um .claude-plugin/marketplace.json ao mesmo repositório é o que permite que as pessoas instalem pelo nome e atualizem com um comando; veja Publique através de seu próprio marketplace.

Envie um plugin com sua própria ferramenta

Se você mantém uma CLI ou SDK, publique o plugin em um marketplace e faça seu instalador ou mensagem pós-instalação executar ou imprimir os dois comandos que um usuário precisa: claude plugin marketplace add <source>, depois claude plugin install <name>@<marketplace>. Para descoberta em sessão quando alguém usa sua ferramenta, veja Recomende seu plugin a partir de sua CLI.

Publique através de seu próprio marketplace

Seu próprio marketplace é um arquivo .claude-plugin/marketplace.json que lista seu plugin, adicionado a um repositório git. Uma vez que o arquivo está no repositório, o plugin é publicado, sem formulário de envio. Você pode manter o arquivo no próprio repositório do plugin ou em um separado.

Adicione o arquivo de marketplace ao seu repositório

Para publicar a partir do próprio repositório do plugin, salve o arquivo de marketplace ao lado de plugin.json em .claude-plugin/, com uma entrada cuja source é "./", a raiz do repositório. Dê à entrada o mesmo name que plugin.json, de acordo com Mantenha o nome da entrada e o nome do manifesto iguais:

{
  "name": "your-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "deploy-helper", "source": "./" }
  ]
}

Em seu shell, execute claude plugin validate . no repositório para verificar o arquivo antes de fazer push.

Criar um marketplace cobre o layout com vários plugins em um repositório.

Controle quem pode instalar

Qualquer pessoa que possa clonar o repositório pode instalar a partir dele, então se o repositório for privado, o marketplace também será privado. Para hosts diferentes de um repositório git, veja Hospede um marketplace. Para alcançar todos em uma empresa, incluindo pessoas que não usam git, veja Implante para uma empresa inteira.

Diga aos usuários como instalar

Diga aos seus usuários para adicionar o marketplace e depois instalar o plugin a partir de seu shell, substituindo a fonte e os nomes pelos seus:

  • Adicione o marketplace uma vez: claude plugin marketplace add your-org/your-marketplace, onde o argumento é um atalho GitHub owner/repo, uma URL ou um caminho
  • Instale o plugin: claude plugin install deploy-helper@your-marketplace
  • Ou faça ambos de dentro de uma sessão: /plugin install deploy-helper --marketplace your-org/your-marketplace. Requer Claude Code v2.1.275 ou posterior. Veja Adicione um marketplace e instale em um comando

Envie atualizações aos usuários

Os usuários recebem um lançamento quando o solicitam ou quando a auto-atualização está ativada para seu marketplace:

  • Sob demanda: claude plugin update deploy-helper@your-marketplace no shell do usuário atualiza o marketplace e instala a nova cópia quando a versão do seu plugin foi alterada
  • Auto-atualização: desativada por padrão para seu marketplace. Veja Ative a auto-atualização. Uma vez ativada, ela faz o mesmo que claude plugin update com um atraso após o início da sessão

Instale plugins cobre os comandos do lado do usuário, e quando a auto-atualização é executada cobre o tempo.

Envie para o diretório da Anthropic

O diretório da Anthropic é o catálogo que as pessoas navegam no claude.ai e no Cowork para adicionar plugins e conectores. Uma listagem lá alcança pessoas no claude.ai, no Cowork e no Claude Code. Você envia pelo portal do desenvolvedor em claude.ai/directory/manage; Prepare for review no claude.com descreve o que acontece com cada versão antes de ser publicada.

O envio requer um plano pago do claude.ai. No Pro e Max você envia da sua própria conta. No Team e Enterprise, um Owner pode enviar, e no Enterprise um Owner também pode conceder a permissão Directory para outros membros através de uma função personalizada em Organization settings > Roles. Veja Confirm you can submit to the directory.

As etapas de envio, as verificações que cada versão deve passar e o que acontece após você publicar estão documentadas no claude.com, porque são as mesmas independentemente de qual superfície seus usuários estão:

Antes de abrir o portal, valide localmente e verifique quais dos seus componentes carregam fora do Claude Code:

  • Execute claude plugin validate ./your-plugin --strict em seu shell: substitua ./your-plugin pelo caminho para seu diretório de plugin. O comando detecta erros de manifesto localmente; plugin validate lista quais arquivos cada execução lê. O portal aplica regras de diretório adicionais que o CLI não verifica, portanto uma execução local limpa não garante uma validação de portal limpa.
  • Verifique o que carrega onde: alguns componentes de plugin são apenas do Claude Code e não carregam no claude.ai ou no Cowork. A component support table lista cada componente por aplicativo, para que você saiba o que os usuários fora do Claude Code receberão.

O marketplace oficial da Anthropic, claude-plugins-official, não aceita envios através do portal de diretório. Se você trabalha com um contato de parceiro da Anthropic, pergunte-lhes sobre uma listagem no marketplace oficial.

Como um plugin listado alcança usuários do Claude Code

Uma pessoa que instala seu plugin do diretório no claude.ai o tem em sua conta, e o Claude Code o carrega como <name>@synced. Plugins synced from claude.ai cobre o que eles veem e como desativam.

Enviar atualizações, renomeações e remoções

Lançar uma nova versão

Se você publicar através do seu próprio marketplace e seu plugin.json define version, incremente-a e faça push. Os usuários que executam claude plugin update ou têm auto-update ativado recebem a nova versão, conforme descrito em Enviar atualizações para usuários. Para uma listagem de diretório, consulte Atualizar um plugin publicado.

Marcar um lançamento

Marque o lançamento no git quando outros plugins declaram um intervalo de versão no seu, porque esses intervalos são resolvidos contra tags. Caso contrário, você não precisa de uma tag.

Para marcar, execute claude plugin tag no seu shell a partir do diretório do plugin. Isso cria uma tag {name}--v{version}. Adicione --push para enviar a tag para origin. A referência plugin tag lista seus sinalizadores.

Renomear ou remover um plugin

Nunca altere o name de um plugin publicado. Após uma renomeação, os usuários que já o instalaram perdem o plugin, porque sua instalação é registrada sob o nome antigo. Uma entrada renames no seu arquivo de marketplace os migra em vez disso. Altere displayName quando quiser um rótulo diferente.

Se uma renomeação for inevitável, use o mapa renames do arquivo de marketplace para que as instalações existentes sejam migradas em vez de falharem com Plugin "<name>" not found in marketplace. Para remover um plugin do marketplace, ou para os detalhes completos de renames, consulte Renomear ou remover um plugin na página de hospedagem. A referência de marketplace tem o campo.

Declare dependências

Se seu plugin precisa que outro plugin do mesmo marketplace seja habilitado, liste-o no array dependencies de plugin.json. Cada entrada é um nome simples ou um objeto com um intervalo de semver version. Quando um usuário instala seu plugin, Claude Code instala e habilita a dependência também.

Dependências de plugin cobre a sintaxe de intervalo, dependências entre marketplaces e como os usuários removem dependências que não precisam mais.

Próximas etapas