Plugins do Claude Code, explicados

Um plugin do Claude Code é uma pasta que adiciona skills, agentes, hooks, servidores MCP e outras partes ao Claude Code, o agente de programação de linha de comando da Anthropic. Os plugins vêm de marketplaces, que são catálogos adicionados a partir de um repositório do GitHub, de uma URL git ou de uma pasta local. O guia da Anthropic para instalar plugins orienta os leitores a verificar o que um plugin adiciona antes de instalá-lo, porque um plugin pode executar hooks e servidores MCP.

Este guia acompanha o Claude Code 2.1.317, lançado em 2 de novembro de 2026. Ele mostra o que um plugin pode conter, os comandos que instalam e removem um plugin e o que o validador embutido verifica, tudo testado em um Mac.

Como funcionam os plugins do Claude Code

Todo plugin tem um manifesto, um pequeno arquivo JSON em .claude-plugin/plugin.json. Só o campo name é obrigatório, segundo a visão geral de plugins da Anthropic. Todo o resto é opcional, e cada parte fica em seu próprio lugar:

Parte	Onde fica	O que faz
Skills	skills/<name>/SKILL.md	Instruções para uma tarefa, executadas como /<plugin>:<name>
Agentes	agents/<name>.md	Agentes auxiliares para os quais o Claude pode passar trabalho
Hooks	hooks/hooks.json	Scripts que rodam em momentos definidos, como antes de uma ferramenta rodar
Mods	uma entrada modules em hooks/hooks.json	JavaScript que pode desenhar painéis e adicionar comandos
Servidores MCP	.mcp.json	Ferramentas externas, conectadas pelo Model Context Protocol
Servidores LSP	.lsp.json	Auxiliares de linguagem do tipo que os editores de código usam

O MCP, Model Context Protocol, é uma forma padrão de conectar ferramentas externas a um agente de IA. A documentação explica os mods de forma direta: um plugin com um módulo de hooks “é chamado de mod”.

Os plugins chegam até você por meio de marketplaces. O da própria Anthropic se chama claude-plugins-official, e o Claude Code o adiciona automaticamente na primeira vez que você inicia uma sessão interativa no terminal. O catálogo da comunidade, claude-community, não é adicionado automaticamente. O Claude Code só aceita os nomes dos catálogos oficial e da comunidade vindos de repositórios em github.com/anthropics/. Uma cópia hospedada em qualquer outro lugar deixa de carregar com o erro “Marketplace is registered from an untrusted source” (o marketplace foi registrado a partir de uma fonte não confiável).

Como instalar, ativar e remover um plugin

Cada ação tem duas formas: um comando /plugin dentro de uma sessão do Claude Code e um comando claude plugin em um terminal comum. A tabela abaixo combina a documentação da Anthropic com o texto de ajuda da versão 2.1.317.

Ação	Dentro de uma sessão	Em um terminal
Adicionar um marketplace	/plugin marketplace add <source>	claude plugin marketplace add <source>
Instalar	/plugin install <plugin>@<marketplace>	claude plugin install <plugin>@<marketplace>
Ativar ou desativar	Aba “Installed” e depois a tecla Espaço	claude plugin enable <plugin> ou disable
Atualizar	Aba “Installed” e depois “Update now”	claude plugin update <plugin>
Remover	Aba “Installed” e depois “Uninstall”	claude plugin uninstall <plugin>
Inspecionar	Aba “Installed”	claude plugin details <name>

Dentro de uma sessão, o /plugin install não instala na hora. Ele abre um painel de detalhes, para que você possa revisar o plugin e escolher um escopo antes. O comando do terminal instala imediatamente, no escopo de usuário, a menos que você adicione --scope.

O escopo decide quem recebe o plugin:

• Usuário (user) grava em ~/.claude/settings.json e ativa o plugin em todos os projetos da sua máquina.
• Projeto (project) grava em .claude/settings.json, um arquivo que você inclui no commit para que os colaboradores o compartilhem.
• Local grava em .claude/settings.local.json e vale só para você, em um único repositório.

Quando os escopos divergem, local vence projeto, e projeto vence usuário. As configurações que uma organização gerencia se sobrepõem aos três. Nenhum comando atualiza todos os plugins de uma vez, e o /reload-plugins aplica as mudanças a uma sessão em andamento. As atualizações chegam automaticamente para o marketplace oficial da Anthropic, mas vêm desativadas por padrão nos de terceiros.

Um teste prático dos comandos de plugin

Em um teste do Tech AI Wire no macOS 26.6.2 com o Claude Code 2.1.317, o claude plugin --help listou 15 subcomandos, de configure a validate. Três comandos mostram o que um plugin faz antes de mexer em um projeto:

claude plugin details cc-plugin-you-should-know@builtin
claude plugin validate ./hello-check
claude plugin validate ./broken-check

O primeiro comando inspecionou o “You should know”, o agente auxiliar opcional que chegou no Claude Code 2.1.287. Ele listou zero skills, agentes, hooks, servidores MCP e servidores LSP. O custo permanente previsto foi “~0 tok added to every session” (cerca de 0 token adicionado a cada sessão).

O segundo comando verificou um plugin de teste mínimo: um manifesto com nome, versão e descrição, mais uma skill. Ele passou com um aviso, pela falta de autor. Também listou dois problemas que impediriam o envio ao diretório de plugins da Anthropic: nenhum README.md com pelo menos 40 palavras e nenhum arquivo LICENSE ou campo license. A falta de um ícone foi só um aviso. O ícone precisa ser um PNG ou JPEG quadrado, com 512 a 2.048 pixels de lado e menos de 2 MB.

O terceiro comando usou o mesmo plugin com o campo name apagado. A validação falhou com o código de saída 1 e a mensagem “name: Invalid input: expected string, received undefined” (name: entrada inválida, esperava uma string e recebeu undefined). As verificações do diretório só mudam o resultado quando você adiciona --profile directory. A ferramenta também observa que o diretório “runs a safety scan and a policy review that this command does not” (faz uma varredura de segurança e uma revisão de políticas que este comando não faz).

O que mudou e quando

Os recursos de plugin chegaram em uma sequência constante de versões desde setembro. Estas datas são de quando cada versão chegou ao npm, o registro de pacotes de JavaScript:

Versão	Publicada em	O que mudou para os plugins
2.1.273	15 de setembro de 2026	Adição de marketplaces hospedados no claude.ai
2.1.275	17 de setembro de 2026	Adicionar um marketplace e instalar com um único comando na sessão
2.1.287	1º de outubro de 2026	Claude Mods e o agente auxiliar “You should know”
2.1.292	6 de outubro de 2026	A mesma instalação em uma etapa a partir do terminal
2.1.302	16 de outubro de 2026	Correção de marketplaces clonados de novo a cada atualização
2.1.317	2 de novembro de 2026	A skill plugin-authoring se oferece para ajudar a compartilhar um mod que funciona

Os marketplaces também são alvo. Em 29 de outubro, versões adulteradas de uma extensão do Claude Code ficaram no marketplace do Cursor por cerca de 11 horas e adicionaram uma chave SSH. Era uma extensão de editor, não um plugin do Claude Code, mas a lição sobre confiar em um catálogo é a mesma.

O que isso significa para os desenvolvedores

Trate um plugin como qualquer outro código que você baixa. A página de segurança de plugins da Anthropic diz que um plugin “pode executar código arbitrário na sua máquina com os seus privilégios de usuário”. Ela acrescenta que as regras de permissão e o sandbox “cobrem as chamadas de ferramentas que o Claude faz, não o código que um plugin executa por conta própria”. Leia a lista “Will install” (será instalado) no painel de detalhes. Depois, verifique hooks/hooks.json, .mcp.json e qualquer pasta bin/ antes de instalar.

Verifique também o custo. O claude plugin details mostra quantos tokens um plugin adiciona a cada sessão, então fica fácil identificar um plugin pesado antes de ativá-lo.

Para uma equipe, coloque extraKnownMarketplaces e enabledPlugins no .claude/settings.json do repositório e faça o commit. Essas entradas só valem em pastas em que o Claude Code confia. Os colegas de equipe ainda precisam rodar o comando de instalação uma vez para plugins de fontes externas.

As empresas podem ir além com configurações gerenciadas. Uma lista de permissões strictKnownMarketplaces limita quais catálogos carregam, e uma lista vazia bloqueia todas as fontes, inclusive a da própria Anthropic. Definir um plugin como false no enabledPlugins gerenciado o bloqueia em todos os escopos.

Um catálogo da empresa não precisa ficar no GitHub. A documentação do LiteLLM mostra o gateway de IA do LiteLLM servindo um: os administradores escolhem os plugins e os engenheiros adicionam o catálogo com um único comando claude plugin marketplace add. A mesma página alerta contra colocar a chave de acesso do catálogo no .claude/settings.json de um projeto, porque esse arquivo costuma ser enviado ao repositório em um commit.

Os autores de plugins devem rodar claude plugin validate --profile directory antes de enviar. No teste do Tech AI Wire, a falta de README e a falta de licença foram os dois problemas que o diretório recusa.