O que são os plugins e o marketplace do Claude Code

À medida que você usa mais o Claude Code, vão se acumulando seus próprios slash commands, subagentes que você usa com frequência, servidores MCP e hooks. Um plugin é o mecanismo que os reúne em uma única unidade que você pode versionar, compartilhar e reutilizar entre equipes e projetos, e um marketplace é onde eles são distribuídos (os plugins chegaram em beta público em outubro de 2025; em 2026 foram adicionados um diretório oficial e a busca/listagem do /plugin).

Este artigo aborda o que é um plugin, sua estrutura, como usá-lo, marketplaces, como criar e publicar o seu próprio, além do escopo de distribuição e da segurança — com base na documentação oficial. Três pontos-chave antes de tudo. (1) Um plugin é um único diretório que agrupa "skills / commands / subagentes / hooks / servidores MCP", com o .claude-plugin/plugin.json como manifesto. (2) Use /plugin para adicionar um marketplace e install para adicionar um plugin. (3) Criar o seu próprio é fácil — basta colocar um plugin.json e um SKILL.md, testar com claude --plugin-dir e publicar via git.

1. O que é um plugin do Claude Code

A definição oficial: um plugin é "um diretório autocontido que agrupa funcionalidades personalizadas do Claude Code para que possam ser versionadas, compartilhadas e reutilizadas". Um único plugin pode incluir qualquer combinação de:

Em resumo, um plugin é "uma extensão do Claude Code empacotada em um formato compartilhável". Personalizações que antes você configurava separadamente passam a ser reunidas em um único repositório, para que toda a sua equipe reproduza a mesma configuração. Você também pode incluir servidores LSP, monitores em segundo plano e executáveis (bin/), mas os seis acima já bastam para começar.

2. Estrutura de um plugin

Há uma regra importante sobre o layout: apenas o plugin.json fica dentro de .claude-plugin/. Os diretórios commands/, agents/, skills/ e hooks/ ficam na raiz do plugin (não dentro de .claude-plugin/).

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # manifest — ONLY this file lives here
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

Um manifesto plugin.json mínimo:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

name é o identificador e também o namespace da skill (uma skill é invocada como /my-first-plugin:hello). version é opcional: se definido, os usuários só recebem atualizações quando você o incrementa. Se você omitir version ao distribuir via git, o commit SHA atua como a versão (cada commit é uma nova versão).

3. Como usar — /plugin e marketplaces

Instale via /plugin, que abre um gerenciador com abas (Discover / Installed / Marketplaces / Errors). Os comandos principais:

# Add a marketplace (the distribution catalog)
/plugin marketplace add anthropics/claude-code        # a GitHub owner/repo
/plugin marketplace add ./my-marketplace              # a local path
/plugin marketplace add https://example.com/marketplace.json

# Install / manage plugins (user scope by default)
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# List (filter with --enabled / --disabled). /plugin also has a search bar
/plugin list
/plugin list --enabled

# Apply changes without restart
/reload-plugins

"Adicionar um marketplace" = "registrar um catálogo", o que por si só não instala nenhum plugin — você adiciona o catálogo e depois faz install dos plugins individualmente. Para scripts, há equivalentes de CLI não interativos como claude plugin install …. Se o servidor MCP incluído em um plugin não conectar, veja como corrigir erros de conexão do MCP.

4. O que é um marketplace

Um marketplace é um catálogo com um .claude-plugin/marketplace.json que lista os plugins e de onde buscar cada um (um repositório git, um caminho local ou um arquivo hospedado). Existem os oficiais e um da comunidade.

Portanto, se você só quer usar plugins, o marketplace oficial está pronto imediatamente. Adicione o catálogo da comunidade ou o seu próprio catálogo interno conforme a necessidade.

5. Crie e publique o seu próprio

Criar um é surpreendentemente fácil. Comece colocando um manifesto e uma skill, depois testando localmente.

# 1) Scaffold
mkdir -p my-first-plugin/.claude-plugin my-first-plugin/skills/hello
# write .claude-plugin/plugin.json and skills/hello/SKILL.md

# 2) Test without installing (a .zip works too)
claude --plugin-dir ./my-first-plugin

Para publicar, basta colocar um .claude-plugin/marketplace.json na raiz de um repositório git. Os usuários o adicionam com /plugin marketplace add owner/repo.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quick code-review skill"
    }
  ]
}

O versionamento é resolvido nesta ordem: version no plugin.json → (senão) version na entrada do marketplace → (senão) o commit SHA. Se você fixar version, incremente-a a cada release (se esquecer, os usuários não atualizam). Valide antes de publicar com claude plugin validate .. Para ser listado no catálogo oficial da comunidade, inscreva-se pelo formulário de submissão (aplicam-se Team/Enterprise e outras condições).

6. Escopo de distribuição e segurança

As instalações têm um escopo: user (padrão, todos os projetos) / project (todos os colaboradores do repositório, registrado em .claude/settings.json) / local (só você, este repositório) / managed (distribuído pelo admin, não modificável pelo usuário). Para distribuição em equipe, coloque extraKnownMarketplaces e enabledPlugins no .claude/settings.json do projeto, e os membros recebem o prompt de instalação quando confiam na pasta.

Resumo

Um plugin do Claude Code agrupa skills, slash commands, subagentes, hooks e servidores MCP em um único diretório que você pode versionar, compartilhar e reutilizar (o manifesto é o .claude-plugin/plugin.json; commands/ etc. ficam na raiz). Eles são distribuídos via marketplaces, e o oficial (claude.com/plugins) está disponível de imediato. Instale com /plugin marketplace add → /plugin install → (conforme a necessidade) /plugin list, busca, /reload-plugins.

Criar o seu próprio é um caminho curto: coloque um plugin.json e um SKILL.md, teste com claude --plugin-dir e publique colocando um marketplace.json em um repositório git. Os escopos são user / project / local / managed, com distribuição em equipe via .claude/settings.json. Mas plugins podem executar código arbitrário, então instale apenas de publicadores confiáveis e restrinja as fontes com strictKnownMarketplaces em organizações. Os plugins também podem incluir hooks que são executados automaticamente em pontos do ciclo de vida; veja o guia detalhado para entender como funcionam. Relacionados: Claude Agent Skills, MCP, Claude Code Artifacts.

FAQ

Q. Qual é a diferença entre um plugin e uma skill?
A. Uma skill é um dos componentes dentro de um plugin. Um plugin é uma unidade de distribuição (diretório) que agrupa skills mais slash commands, subagentes, hooks e servidores MCP. O plugin é a "caixa" para enviar suas skills e comandos mais usados a uma equipe; uma skill é uma das "folhas de instruções" dentro dessa caixa.

Q. Como eu instalo um plugin?
A. Primeiro adicione um marketplace (catálogo) com /plugin marketplace add owner/repo e depois instale individualmente com /plugin install plugin-name@marketplace-name. O marketplace oficial (claude-plugins-official) está disponível automaticamente desde a primeira inicialização, e você pode navegar em claude.com/plugins ou pelo Discover do /plugin. Alterne com /plugin enable|disable; liste com /plugin list.

Q. Posso criar e distribuir o meu próprio plugin?
A. Sim. Coloque um .claude-plugin/plugin.json (manifesto) e um skills/…/SKILL.md e teste sem instalar via claude --plugin-dir ./your-plugin. Para publicar, basta colocar um .claude-plugin/marketplace.json na raiz de um repositório git; os usuários o adicionam com /plugin marketplace add owner/repo. Lembre-se: apenas o plugin.json fica dentro de .claude-plugin/ — skills/ etc. ficam na raiz.

Q. Como funciona o versionamento?
A. Ele é resolvido como: version no plugin.json → (senão) version na entrada do marketplace → (senão) o git commit SHA. Se você definir version, as atualizações só chegam aos usuários quando você a incrementa, então incremente-a a cada release (caso contrário, os usuários ficam na versão antiga). Omita version e cada commit é uma nova versão. Valide antes de publicar com claude plugin validate ..

Q. Plugins de terceiros são seguros?
A. Não incondicionalmente. A documentação oficial observa que um plugin "pode executar código arbitrário com os seus privilégios", e a Anthropic não verifica plugins de terceiros nem o MCP que eles incluem. Instale apenas de publicadores confiáveis e revise o código se tiver dúvidas. As organizações podem restringir as fontes permitidas com strictKnownMarketplaces ([] para um bloqueio total).