Plugins e marketplaces do Claude Code: como usar, criar e publicar

No Claude Code, um conjunto de skills, subagentes, hooks e configuração MCP forma um plugin. Um catálogo com os nomes dos plugins e os locais de onde obtê-los é um marketplace. Juntos, eles permitem reutilizar procedimentos entre projetos ou compartilhar um conjunto de extensões com a equipe.

Este artigo acompanha você da instalação de um plugin existente à criação de uma skill de saudação e sua distribuição por um catálogo. Distinga três coisas: (1) o plugin e seu catálogo de distribuição ficam em níveis diferentes; (2) registrar um catálogo e instalar um plugin são operações separadas; (3) o sucesso de um comando de validação não garante comportamento correto ou segurança. As etapas seguem o guia oficial de criação.

1. O que são plugins do Claude Code?

Um plugin empacota extensões do Claude Code em um diretório que você pode compartilhar e reutilizar. Não precisa ter todos os componentes: pode conter apenas uma skill.

Para procedimentos que você usa sozinho, o diretório .claude/skills/ do projeto pode bastar. Plugins ajudam quando você quer distribuir o mesmo conjunto para vários lugares e gerenciar suas atualizações. Também existem extensões como suporte a LSP e monitoramento, com requisitos de ambiente e via de distribuição. É mais fácil começar com uma skill pequena e verificá-la.

2. Estrutura de um plugin

Esta é a estrutura padrão de um plugin individual. Se houver manifesto, ele fica em .claude-plugin/plugin.json; skills/, agents/ e hooks/ pertencem à raiz do próprio plugin. O catálogo de distribuição, marketplace.json, é separado. O exemplo adiante o coloca em .claude-plugin/marketplace.json do marketplace.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # metadados deste plugin
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

Veja um exemplo de plugin.json. Você pode omitir totalmente o manifesto se usar apenas a estrutura padrão de diretórios. Se o fornecer, name é obrigatório; descrição e versão são opcionais.

{
  "name": "my-first-plugin",
  "description": "Um plugin de saudação para aprender o básico",
  "version": "1.0.0",
  "author": { "name": "Seu nome" }
}

O name também define o namespace da skill: neste exemplo, invoque /my-first-plugin:hello. Na distribuição armazenada em cache via Git, a versão de plugin.json tem prioridade, seguida da versão do plugin no catálogo. Se nenhuma existir, usa-se o SHA do commit resolvido da origem. Manter uma versão explícita inalterada impede que mudanças apenas no código tornem o plugin elegível para atualização. O carregamento direto de um diretório local e as fontes do tipo command seguem outras regras. Consulte a documentação de gerenciamento de versões.

3. Como usar /plugin e marketplaces

Comece com /plugin. Ele abre um gerenciador com as abas Discover, Installed, Marketplaces e Errors. Estes são os comandos básicos:

# Adicionar um marketplace (catálogo de distribuição)
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add ./my-marketplace              # caminho local
/plugin marketplace add https://example.com/marketplace.json

# Escolher o escopo na interface, instalar e conferir o estado de ativação
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# Instalados por marketplaces (filtrar com --enabled / --disabled)
/plugin list
/plugin list --enabled

# Recarregar mudanças quando necessário e conferir o resultado
/reload-plugins

Adicionar um catálogo não instala plugins por si só. Instale-os individualmente após o registro. O comando interativo /plugin install permite escolher o escopo na tela de detalhes. O comando de shell claude plugin install usa user por padrão; informe --scope para alterá-lo.

Após instalar, confira se o resultado indica ativo, aguardando recarga ou erro de carregamento. A recarga pode ser adiada por seu efeito sobre o cache do prompt. Em sessões sem terminal, mudanças MCP de plugins podem só valer na próxima sessão. /plugin list cobre apenas instalações por marketplaces; não lista tudo que chega por sincronização ou diretórios de skills. Consulte as condições de instalação e recarga e, se o MCP não conectar, a solução de erros de conexão MCP.

4. O que é um marketplace?

Um marketplace é um catálogo com um .claude-plugin/marketplace.json que lista plugins e suas origens, fornecido por um repositório Git, caminho local ou arquivo hospedado. Há catálogos oficiais e comunitários.

Se faltar um catálogo, confira o registro; se faltar um plugin específico, confira nome e origem. Em um catálogo interno, também importa que os usuários possam acessar o repositório e o próprio plugin. Ao distribuir um arquivo JSON por URL, o conteúdo do plugin em caminhos relativos não é buscado nessa URL.

5. Crie e publique seu próprio plugin

Este exemplo cria uma skill de saudação. Comece com a estrutura abaixo. O diretório .claude-plugin externo serve ao catálogo; o interno, ao plugin individual. Execute os comandos a partir do diretório pai que contém my-marketplace.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-first-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── hello/
                └── SKILL.md

(1) Salve o JSON da seção anterior no arquivo interno my-marketplace/plugins/my-first-plugin/.claude-plugin/plugin.json. (2) Salve o conteúdo abaixo em my-marketplace/plugins/my-first-plugin/skills/hello/SKILL.md. O exemplo usa disable-model-invocation: true para que a skill só seja usada quando invocada explicitamente.

---
name: hello
description: Dar uma saudação breve usando um nome
disable-model-invocation: true
---
Cumprimente o usuário brevemente.
Se houver argumentos, inclua esse nome na saudação.
Argumentos: $ARGUMENTS

(3) Escreva o catálogo no arquivo externo my-marketplace/.claude-plugin/marketplace.json. Os caminhos relativos de source são resolvidos em relação à raiz do marketplace, não ao diretório que contém marketplace.json.

{
  "name": "my-plugins",
  "owner": { "name": "Seu nome" },
  "description": "Catálogo de prática para distribuir uma skill de saudação",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "Uma skill que dá uma saudação breve usando um nome"
    }
  ]
}

(4) Valide o catálogo e o plugin separadamente. O primeiro verifica o esquema do catálogo e o plugin.json de entradas locais, mas não lê cada arquivo de skill ou hook. O segundo também cobre arquivos dos diretórios padrão do plugin individual. Nenhuma dessas verificações garante execução correta ou segurança.

claude plugin validate ./my-marketplace
claude plugin validate ./my-marketplace/plugins/my-first-plugin

# Carregar o plugin individual nesta sessão para testá-lo
claude --plugin-dir ./my-marketplace/plugins/my-first-plugin

Na sessão interativa aberta, execute /my-first-plugin:hello Alex e confira se há uma saudação breve que inclua Alex. Uma verificação funcional significa examinar a saída e procurar efeitos colaterais indesejados, não apenas confirmar que o comando está visível. Se não carregar, confira os nomes nos dois JSONs, o caminho de origem e o local e o frontmatter de SKILL.md.

(5) Para testar também a via do catálogo, encerre a sessão de teste anterior e inicie o Claude Code sem --plugin-dir. Os comandos abaixo registram entradas na sua configuração: experimente em um projeto de prática e escolha o escopo de instalação.

/plugin marketplace add ./my-marketplace
/plugin install my-first-plugin@my-plugins
/my-first-plugin:hello Alex

(6) Para distribuir, publique o conteúdo de my-marketplace como raiz de um repositório Git que os usuários possam obter. Inclua no commit tanto o diretório plugins quanto o catálogo. Os usuários adicionam o owner/repo real e instalam o mesmo my-first-plugin@my-plugins. Essa estrutura com caminhos relativos funciona no registro por Git ou diretório local; não pode ser usada sem alterações com uma URL isolada de marketplace.json. Consulte como criar, distribuir e validar catálogos.

Você não precisa solicitar inclusão no catálogo oficial para distribuir pelo seu próprio repositório Git. Se também quiser aparecer no comunitário, autores individuais podem usar o formulário de envio do Console. O formulário de claude.ai exige organização Team/Enterprise e permissões administrativas. Enviar para community é diferente de aparecer no catálogo oficial com curadoria da Anthropic.

6. Escopos de instalação e segurança

Os escopos de instalação são user (todos os seus projetos), project (configurações compartilhadas do projeto) e local (só você neste projeto). Diferencie escolher o escopo interativamente do padrão user da CLI de shell. As configurações managed são controladas por administradores e restringem mudanças de configuração pelos usuários.

Equipes podem compartilhar origens e estado de ativação por extraKnownMarketplaces e enabledPlugins em .claude/settings.json. Porém, escrever configurações compartilhadas não equivale a concluir a instalação no computador de cada integrante. Cada membro precisa instalar plugins de fontes externas. Após confiar no projeto, confira registro do catálogo, permissões de acesso e resultado da instalação em cada ambiente.

Resumo

Um plugin é uma unidade de distribuição de extensões; um marketplace é seu catálogo. Usuários registram o catálogo → instalam plugins individuais → conferem ativação e comportamento. Autores preparam plugin e catálogo → validam ambos → invocam o recurso → distribuem por um repositório acessível. Conferir escopos, permissões de acesso e a versão usada nas atualizações facilita reproduzir a configuração em outros lugares.

O registro automático do catálogo oficial tem condições, e itens revisados não têm garantia incondicional de funcionamento. Comece com um recurso necessário, verifique o resultado e depois amplie. Outros mecanismos relacionados estão em Hooks do Claude Code, Claude Agent Skills, MCP e Artifacts do Claude Code.

Perguntas frequentes

P. Qual a diferença entre plugin e skill?
R. Uma skill é um procedimento a executar; um plugin é uma unidade de distribuição que a agrupa com hooks, configuração MCP e outros componentes. Invoque explicitamente uma skill do plugin com /plugin-name:skill-name. A seleção automática depende da descrição e das configurações.

P. Não encontro o marketplace oficial.
R. O oficial, claude-plugins-official, é registrado automaticamente na primeira inicialização interativa, mas uso não interativo anterior, restrições de rede ou políticas gerenciadas podem impedir isso. Em um ambiente onde seja permitido, tente /plugin marketplace add anthropics/claude-plugins-official. Registrar o catálogo não instala plugins individuais.

P. Qualquer pessoa pode distribuir um plugin que criou?
R. Uma possibilidade é colocar o plugin e o catálogo em um repositório Git próprio e acessível. Solicitar inclusão em community é outra operação; autores individuais podem usar o formulário do Console. O envio por claude.ai tem requisitos de organização e permissões. Confira também se source do catálogo aponta para o local real do plugin.

P. Por que meu plugin não atualiza após mudar o código?
R. Na distribuição armazenada em cache via Git, a versão de plugin.json tem prioridade máxima. Mudar apenas a versão do catálogo, mantendo aquela fixa, não atualiza o plugin. Se nenhum fornecer uma versão, usa-se o SHA do commit Git resolvido, mas as operações de atualização e a referência da origem também importam. Carregamento direto de diretório local, fontes archive e fontes command seguem outras regras.

P. Um plugin é seguro se validate passar?
R. Não. Validar estrutura e configuração é diferente de testar comportamento real e segurança. Validar apenas o catálogo não inspeciona o corpo das skills nem arquivos semelhantes. Valide o plugin individual e teste recursos e efeitos colaterais. A revisão para inclusão em community também não substitui a verificação do publicador e do código incluído.