Plugins e marketplaces: como avaliar antes de instalar

A documentação não faz rodeio. Plugins e marketplaces são descritos como "componentes altamente confiados, capazes de executar código arbitrário na sua máquina com seus privilégios de usuário". E na tela de instalação, o aviso complementa: a Anthropic não controla quais servidores MCP, arquivos ou software vêm dentro de um plugin, e não consegue verificar se ele faz o que promete.

Isso muda a pergunta. Não é se dá para confiar no marketplace, é o que conferir antes de apertar enter. E o Claude Code já traz as ferramentas para conferir. Quase ninguém usa.

Antes de avaliar, é preciso saber o que se está avaliando. Um plugin é um diretório com componentes opcionais, e a lista é maior do que a maioria imagina.

As quatro linhas com "sim" são as que merecem atenção, e duas delas quase nunca aparecem em texto sobre plugins.

monitors/ define comandos que o Claude Code inicia sozinho quando o plugin está ativo. Cada linha que o comando escreve na saída padrão vira notificação para o agente durante a sessão. É um canal legítimo e útil, e é um processo rodando de fundo que você não pediu.

settings.json aceita hoje só duas chaves, e uma delas é grande: agent ativa um dos agentes do próprio plugin como thread principal, aplicando o prompt de sistema dele, as restrições de ferramenta dele e o modelo dele. Um plugin com essa chave muda o comportamento padrão do Claude Code na sua máquina.

bin/ soma executáveis ao PATH da ferramenta Bash enquanto o plugin estiver ativo. Um binário ali com nome de comando comum passa a ser encontrado antes do original.

Nada disso é falha de projeto. É o que torna plugin útil, e é exatamente por isso que a documentação usa a expressão "altamente confiados". A mecânica dos hooks está em hooks no Claude Code, e a de servidores MCP em MCP na prática.

Tratar todo marketplace como equivalente é o erro mais comum. Existem três camadas, com garantias bem diferentes.

Duas leituras importam aqui.

A primeira: o marketplace oficial é registrado sozinho na primeira vez que você abre o Claude Code de forma interativa. Você já tem um marketplace adicionado sem ter pedido, e é o único com curadoria humana.

A segunda: o comunitário fixa cada plugin num commit específico do catálogo, e a CI move esse ponteiro conforme o autor publica. Isso dá rastreabilidade, e significa que o conteúdo aprovado na triagem não é necessariamente o que você vai baixar semanas depois.

Para tudo fora dessas duas listas, incluindo repositório de time e marketplace local, não há revisão nenhuma. O que existe é o que você conferir.

O Claude Code já mostra o suficiente para uma avaliação séria. A tela de detalhes, no /plugin, aba Discover, traz três campos que a maioria pula:

• Custo de contexto, uma estimativa de quantos tokens o plugin soma à sua janela a cada turno
• Última atualização, para ver se o projeto está vivo
• Será instalado, a lista dos comandos, agentes, skills, hooks e servidores MCP e LSP que ele adiciona

Nem todo plugin fornece esses dados. Em marketplace local ou personalizado, o custo de contexto e a data podem não aparecer, e a lista vira "os componentes serão descobertos na instalação". Essa mensagem é informação, não ruído: ela diz que você vai instalar sem saber o que vem.

Fora da interface, três comandos fazem o trabalho pesado:

# inventário completo de um plugin instalado
claude plugin details <plugin>@<marketplace>

# a mesma validação que o pipeline de revisão roda
claude plugin validate ./caminho-do-plugin --strict

# carregar sem instalar, só para esta sessão
claude --plugin-dir ./caminho-do-plugin

O último é o mais subestimado. --plugin-dir carrega o plugin para a sessão atual sem instalar nada, e aceita também um arquivo .zip. Clonar o repositório, ler o hooks.json e o .mcp.json com os próprios olhos, e testar assim custa cinco minutos.

A ordem que eu sigo:

1. Ler a seção Será instalado. Tem hook, MCP ou monitor? A avaliação fica mais rigorosa.
2. Abrir o repositório e ler hooks/hooks.json, .mcp.json e monitors/monitors.json. São arquivos curtos.
3. Conferir se existe bin/ e o que tem dentro.
4. Conferir se existe settings.json com a chave agent.
5. Olhar a data da última atualização e o custo de contexto.
6. Testar com --plugin-dir antes de instalar de verdade.

Depois de instalar, a aba Errors do /plugin mostra o que falhou ao carregar.

Se a dúvida é qual instalar antes de saber como avaliar, o catálogo de skills e comandos traz o que já passou por esse crivo aqui.

Como garantir que você recebe o que revisou

Revisar um plugin e depois receber outro conteúdo é uma possibilidade real, porque ref aponta para um branch ou tag que se move. As fontes de plugin resolvem isso, e vale saber para quando você mantém o marketplace do time.

São sete tipos de fonte: caminho relativo, github, url, git-subdir, npm, archive e command. Os três primeiros git aceitam sha, que fixa um commit exato:

{
  "name": "formatador",
  "source": {
    "source": "github",
    "repo": "meu-org/formatador",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Com ref e sha juntos, o sha é o que vale. A instalação continua funcionando mesmo que o branch apontado por ref tenha sido apagado, desde que o commit siga alcançável no repositório.

A fonte archive, que baixa um zip por HTTPS e dispensa git e npm na máquina, aceita sha256 com a mesma finalidade.

É a diferença entre "instale a última versão do que esse autor publicar" e "instale exatamente o que eu li".

Plugin tem custo recorrente, e ele não aparece em lugar nenhum da conversa.

O custo de contexto listado na tela de detalhes é por turno, não por sessão. Descrição de skill, definição de agente e nome de ferramenta MCP entram no prompt e são reenviados a cada mensagem. Como 90% do custo de uma sessão é releitura de contexto, um punhado de plugins esquecidos e nunca usados sai mais caro do que parece.

Há também um custo de troca. Habilitar ou desabilitar plugin no meio da sessão cobra na requisição seguinte: os componentes novos se anunciam em conteúdo acrescentado à conversa. E se o plugin traz servidores MCP cujas ferramentas não estão adiadas pela busca de ferramentas, a mudança invalida o cache e a próxima requisição relê a conversa inteira. Por isso o /reload-plugins avisa e pede --force quando a recarga tem esse efeito.

O Claude Code ajuda a encontrar o peso morto. Na aba Installed, plugins que você instalou e não usa há pelo menos duas semanas, ao longo de dez sessões ou mais, aparecem sob o cabeçalho Not used recently. É a lista para revisar de tempos em tempos.

Na instalação você escolhe entre três escopos, mais um que só administrador define:

Escolher Project é publicar uma decisão de segurança para o time inteiro. Vale o mesmo cuidado de um package.json.

Três comportamentos que surpreendem em operação.

Remover um marketplace desinstala os plugins dele. A documentação avisa, e o aviso passa despercebido.

Atualização automática tem padrões diferentes. Ligada nos marketplaces oficiais da Anthropic, desligada em terceiros e locais. Se você adicionou um marketplace de time, ele não atualiza sozinho a menos que alguém ligue ou que o administrador marque autoUpdate na entrada de extraKnownMarketplaces.

Plugin de fonte command roda um comando na sua máquina. É um tipo de fonte em que o marketplace, em vez de apontar para um repositório, aponta para um comando local que imprime o caminho do plugin. Ele roda na instalação e uma vez por sessão, em segundo plano, numa cadência própria que não depende da configuração de atualização automática do marketplace.

O desenho em volta disso é cuidadoso, e vale conhecer. O comando precisa ser ASCII imprimível, no máximo 500 caracteres, sem sequências de quatro espaços ou mais, com a justificativa declarada na documentação: para que a pessoa consiga revisar o comando inteiro que está aceitando. O Claude Code mostra a string exata antes da instalação e só executa o comando que você aceitou. Se o autor mudar o comando, as re-execuções param até você revisar e aceitar de novo.

Quando a decisão deixa de ser individual, quatro configurações gerenciadas resolvem quase tudo:

Um detalhe de precedência que evita falsa sensação de controle: strictKnownMarketplaces casa com o marketplace de origem, não com as entradas dentro dele. Uma pessoa ainda instala um plugin de fonte command a partir de um marketplace permitido. Para fechar isso, é preciso o disableCommandPluginSources junto.

O modelo de permissões que governa o resto da execução está em permissões e auto mode, e o checklist mais amplo de operação em Claude Code em produção.

A Anthropic revisa os plugins que estão nos marketplaces?

Depende do marketplace. O oficial é curado pela Anthropic, com inclusão a critério dela. O comunitário aceita plugins que passaram por validação automatizada e triagem de segurança, e fixa cada um num commit específico. Para qualquer outro marketplace não há revisão, e a documentação declara que a Anthropic não controla nem verifica o que vem dentro de um plugin de terceiro.

Dá para testar um plugin sem instalar?

Sim, e é o passo mais útil da avaliação. claude --plugin-dir ./caminho carrega o plugin só para aquela sessão, sem instalar, e aceita também um .zip. Existe ainda o claude plugin validate, que roda a mesma verificação do pipeline de revisão.

Plugin instalado e nunca usado atrapalha?

Atrapalha o bolso e o contexto. O custo listado na tela de detalhes é por turno: descrições de skill e definições de ferramenta são reenviadas a cada mensagem. A aba Installed agrupa sob Not used recently o que você não usa há duas semanas ao longo de dez sessões, e essa é a lista para limpar.

Qual a diferença entre desabilitar e desinstalar?

Desabilitar mantém o plugin no disco e tira os componentes dele da sessão, o que já elimina o custo de contexto. Desinstalar remove de vez. E vale lembrar que remover o marketplace de origem desinstala todos os plugins que vieram dele.

• Anthropic — Claude Code Docs: Discover and install prebuilt plugins. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Create plugins. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Create and distribute a plugin marketplace. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: How Claude Code uses prompt caching. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Configure permissions. Acesso em 20/08/2026.

Verificado em 20 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) o settings.json de plugin aceitar chaves além de agent e subagentStatusLine, (b) o marketplace comunitário mudar o critério de triagem ou deixar de fixar commit, ou (c) a lista de sete tipos de fonte de plugin mudar.