Como avaliar um sistema para Claude Code antes de instalar no seu projeto

Instalar um sistema no Claude Code não é baixar um arquivo, é dar uma cópia da chave do seu repositório e do seu shell pra um código que você provavelmente não leu

Fala aí, beleza? A quantidade de plugin, skill e marketplace comunitário que apareceu nos últimos tempos criou uma decisão nova no dia a dia do vibe coder: instalar ou não instalar

E quase ninguém trata isso como decisão, é só rodar o comando e seguir a vida… 😅

Então bora montar um checklist de leitura prévia, genérico, que serve pra qualquer projeto: o que o sistema promete, o que ele encosta no seu repo e quais perguntas fazer ANTES de dar o comando de instalação

O que um sistema para Claude Code realmente encosta no seu projeto

Antes do como, o porquê: você precisa saber qual é a superfície de contato

Segundo a referência oficial de plugins, um plugin de Claude Code é um diretório autocontido de componentes que estende a ferramenta

E esses componentes podem incluir skills, agents, hooks, servidores MCP, servidores LSP e monitors

Ou seja: não é "um arquivinho de configuração", é um pacote que pode plugar várias coisas de uma vez

O que cada peça implica:

Skills. No Claude Code elas são baseadas em sistema de arquivos e ficam em ~/.claude/skills/ (pessoal) ou .claude/skills/ (projeto), cada skill na própria pasta com um SKILL.md obrigatório

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Detalhe importante do funcionamento: o frontmatter de cada skill disponível é carregado na inicialização, e o corpo do SKILL.md só é carregado quando a skill é selecionada

Hooks. Aqui mora o barulho

Hooks são comandos shell, endpoints HTTP ou prompts de LLM definidos pelo usuário, que executam automaticamente em pontos específicos do ciclo de vida da ferramenta

E rodam no NÍVEL DE PERMISSÃO DO USUÁRIO, ou seja, com a sua permissão, na sua máquina, sem você clicar em nada na hora

A pasta bin/. Um executável colocado em bin/ na raiz do plugin faz o Claude Code adicionar esse diretório ao PATH da ferramenta Bash enquanto o plugin estiver habilitado

Tradução: aquele binário vira comando direto, chamável

Servidores MCP. Servidores MCP declarados por um plugin em escopo de projeto passam pela mesma aprovação por servidor que um .mcp.json de projeto

Esse é o único ponto da lista onde existe um pedágio explícito de aprovação, e mesmo assim é você que decide

E tem a posição oficial, que é bem honesta: a documentação orienta que o usuário confie no plugin antes de instalar, porque a Anthropic não controla quais servidores MCP, arquivos ou softwares vêm dentro de plugins e não consegue verificar que eles funcionam como prometido

A confiança é responsabilidade de quem instala, beleza? Mesma lógica que vale na hora de avaliar um recurso do awesome-claude-code antes de levar pro projeto do time

De onde veio o sistema muda o quanto você precisa ler

Nem toda origem pede o mesmo nível de leitura

O Claude Code adiciona automaticamente o marketplace oficial da Anthropic (claude-plugins-official) na primeira vez que é iniciado em modo interativo

Já o comunitário, anthropics/claude-plugins-community, você adiciona na mão

E marketplaces podem ser adicionados a partir de shorthand do GitHub, qualquer host Git, caminhos locais ou URLs remotas, o que é MUITO conveniente e também é exatamente o motivo de dar atenção na origem

Cada plugin do diretório traz um link pra você revisar o conteúdo antes de instalar

Esse link é o começo do checklist, não um detalhe de interface 😀

Checklist passo a passo: como ler um sistema antes do comando de instalação

Agora a parte prática

A ideia não é virar auditor de segurança em tempo integral, é gastar uns minutos de leitura antes de um comando que é rápido demais de rodar

1. Identifique a origem e abra o link de inspeção. Antes de qualquer coisa, responda: veio do oficial, do comunitário ou de um repo solto que alguém postou? O diretório oferece um link pra revisar o conteúdo por plugin, use ele. O erro comum deste passo é confundir "está no marketplace comunitário" com "foi revisado por uma pessoa": a validação lá é automatizada

2. Abra o repositório e mapeie a estrutura. Olhe a raiz do plugin e veja o que existe de fato. O manifesto fica em .claude-plugin/plugin.json e é OPCIONAL: sem ele, o Claude Code descobre os componentes nos locais padrão e deriva o nome do plugin pelo nome do diretório. O erro comum aqui é procurar só o manifesto e concluir que "não tem nada", quando na verdade os componentes estão nos locais padrão

3. Procure os hooks e leia o que eles executam. Linha a linha mesmo, sem pressa. A documentação de hooks traz boas práticas de segurança que servem também como régua de leitura: validar e sanitizar entradas vindas do stdin, colocar variáveis de shell entre aspas pra evitar injeção, usar caminhos absolutos para scripts e evitar processar arquivos sensíveis como .env ou credenciais. Se o hook do sistema que você vai instalar faz o oposto disso, já é resposta. O erro comum é ler o README e não o hook: o README promete, o hook executa

4. Procure bin/ e servidores MCP declarados. Se existe bin/ na raiz, aquele diretório entra no PATH do Bash enquanto o plugin estiver habilitado. Se existe MCP em escopo de projeto, vai aparecer aprovação por servidor. O erro comum é aprovar o servidor no automático porque "apareceu um diálogo e eu queria testar logo"

5. Rode o validador de estrutura. O comando claude plugin validate verifica a estrutura de um plugin ou diretório de skills:

claude plugin validate ./caminho-do-plugin
claude plugin validate ./caminho-do-plugin --strict

Ele imprime ✔ Validation passed (ou "passed with warnings"), e a flag --strict trata warnings como erros

Tome cuidado com a interpretação: isso valida ESTRUTURA, não intenção. Um plugin malicioso bem formatado passa numa boa

6. Revise suas permissões antes de instalar. Rode /permissions e olhe o estado atual: o diálogo mostra cada regra junto do arquivo settings.json de onde ela veio. O settings.json aceita três tipos de regra (allow, ask e deny) e a avaliação segue a ordem deny, depois ask, depois allow. Dá pra bloquear leitura de arquivos de ambiente com regra deny em ~/.claude/settings.json, seguindo o exemplo oficial:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

O erro comum deste passo é montar um allow generoso "só pra hoje" e esquecer que allow perde pra deny, mas ganha do seu esquecimento

7. Instale de forma reversível. Use o gerenciador dentro da sessão com /plugin, ou instale direto:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <nome>@<marketplace>

E já entre sabendo a rota de saída: /plugin disable e /plugin uninstall existem, além de /plugin search, /plugin enable e /plugin marketplace update. Pela CLI, o comando é claude plugin (com alias claude plugins). O erro comum é instalar sem saber desinstalar e ficar com meia dúzia de coisas ligadas sem lembrar de onde vieram

Quanto ler em cada caso: skill simples, plugin com hooks e plugin com MCP

Ler tudo com o mesmo peso é o caminho mais rápido pra não ler nada

Então calibra a profundidade pelo risco:

Skill isolada: leitura leve. É uma pasta com SKILL.md obrigatório, e o corpo do arquivo só é carregado quando a skill é selecionada, sendo que o frontmatter das skills disponíveis é carregado na inicialização

Aqui a leitura é mais sobre entender o que ela instrui do que sobre o que ela executa sozinha, e vale conferir os caminhos, ~/.claude/skills/ versus .claude/skills/, principalmente quando uma skill não funciona depois de copiada de outro projeto

Plugin com hooks: leitura linha a linha. Hooks disparam automaticamente em pontos do ciclo de vida e rodam com a sua permissão

Não tem "vou olhar depois": depois já rodou

Plugin com MCP em escopo de projeto e binário em bin/: atenção máxima. Você tem aprovação por servidor de um lado e um diretório entrando no PATH do Bash do outro, enquanto o plugin estiver habilitado

É o cenário que mais merece os seus minutos de leitura, e o que mais merece um "instala amanhã" se você estiver com pressa hoje

Sinais de alerta durante a instalação e como voltar atrás

Sintoma: permissões que passam a valer sozinhas em sessões futuras.

Causa: regras aprovadas com "Yes, and don’t ask again" são salvas em .claude/settings.local.json na raiz do repositório git e passam a valer nas próximas sessões daquele repo, incluindo subdiretórios e worktrees

Solução: rode /permissions e leia a origem de cada regra, já que o diálogo mostra de qual settings.json ela veio

Sintoma: o sistema instalou, mas a configuração do projeto parece não fazer efeito.

Causa: entradas no .claude/settings.json de um projeto só passam a valer depois que você aceita o diálogo de confiança daquela pasta, e esse diálogo só aparece em sessões interativas

Sintoma: o prompt de confiança reaparece toda vez que você inicia.

Causa: a sessão foi aberta direto no diretório home, onde a aceitação vale só para a sessão atual e não é gravada em disco

Solução, que é a recomendação oficial: inicie a partir de um subdiretório de projeto, onde a confiança é salva por diretório

Como prevenir:

Manter a versão em dia não é papo de boas maneiras, tem base histórica

A CVE-2025-59536 foi uma falha de injeção de código no Claude Code que permitia execução de código ANTES do usuário aprovar o prompt de confiança de inicialização, classificada como alta severidade, com CVSS v3 8.7

Ela foi corrigida na versão 1.0.111, e quem tem auto-update padrão habilitado recebeu a correção automaticamente

No mesmo tema, a Check Point Research documentou execução remota de código e exfiltração de token de API através de arquivos de configuração de projeto do Claude Code em repositórios maliciosos, e reportou que todas as falhas divulgadas foram corrigidas pela Anthropic antes da publicação

A conclusão prática é curta: versão atualizada, e desconfiança saudável com repositório clonado de terceiro

E a rota de saída sempre à mão: /plugin disable, /plugin uninstall e /plugin marketplace update

Conclusão

Esse checklist não existe pra você não instalar nada, seria o conselho mais inútil possível num ecossistema que está bombando de coisa boa

Ele existe pra transformar a instalação em decisão consciente e REVERSÍVEL: você sabe de onde veio, sabe o que encosta no seu repo, sabe como desligar

Próximo passo bem concreto: no próximo sistema que você for instalar, rode /permissions pra ver o terreno e claude plugin validate pra checar a estrutura, antes do install

E comece pelo marketplace oficial ou pelo comunitário antes de sair adicionando repositório solto por aí

Dá uns minutos a mais, e evita aquele tipo de dor de cabeça que só aparece depois…

até o próximo post! 😀