← Voltar ao curso
Nível 3 — Automação e escala · Módulo 3.3 — Plugins: distribuindo o setup do time

3.3.3 · Leia antes de instalar

5 min de vídeo TODOS

Objetivo: ao final, o consultor avalia um plugin de terceiro antes de ativar, e sabe identificar o que muda no comportamento padrão do Claude Code só por instalar.

O que você precisa levar desta aula

  1. Instalar um plugin é rodar código de terceiro na sua máquina, com as suas permissões. Você instala pelas skills e leva os hooks junto — e eles disparam em toda chamada que casar com o matcher deles.
  2. A chave agent no settings.json de um plugin promove um subagente dele para a thread principal, com o system prompt, a restrição de ferramentas e o modelo dele. Ativar o plugin muda o comportamento padrão do Claude Code.
  3. Revisão do marketplace da comunidade é automatizada. Ela filtra o obviamente malicioso, não o que é inadequado ao seu contexto contratual. Revisado não é confiável.

O que vem junto sem estar na descrição

Componente O que faz depois de instalado Por que é risco
hooks/hooks.json Dispara em todo evento que casar com o matcher Você instalou por causa das skills; o hook roda em toda chamada de Bash
settings.json com agent Promove um subagente do plugin para a thread principal Muda o comportamento padrão do Claude Code, em toda sessão
.mcp.json Configura servidor MCP Servidor MCP roda com os seus privilégios (aula 3.1.5) e pode falar com endereço externo
bin/ Executáveis entram no PATH do Bash enquanto o plugin está ativo Um executável com nome de ferramenta conhecida pode ser chamado no lugar dela
monitors/ Roda comando em segundo plano, entregando saída ao Claude Vigilância contínua que você não pediu explicitamente

A chave agent, em detalhe

Do settings.json de um plugin, apenas duas chaves são honradas: agent e subagentStatusLine. Chave desconhecida é silenciosamente ignorada.

{
  "agent": "sap-expert"
}

Essas duas linhas fazem o seguinte: o subagente sap-expert, definido em agents/ do plugin, passa a ser a thread principal. O system prompt dele vale, a restrição de ferramentas dele vale, o modelo dele vale.

Por que isso é a coisa mais importante do módulo: todo o resto do curso partiu do princípio de que você configura o Claude — CLAUDE.md no módulo 2.3, skills no 2.4, permissões no 2.5. A chave agent é o único mecanismo em que instalar uma coisa troca quem o Claude é por padrão. Um plugin com essa chave não estende o seu setup; ele substitui o comportamento base dele.

Não é malicioso por natureza — é o mecanismo legítimo de um plugin que quer entregar um agente especializado. É o desconhecimento que é perigoso.

"Mas passou pela revisão do marketplace"

O marketplace da comunidade tem revisão automatizada e triagem de segurança. Plugin aprovado é fixado num SHA de commit específico, e a CI atualiza o pin conforme o autor publica commits novos.

O que isso pega: malware óbvio, plugin quebrado, manifesto inválido.

O que isso não pega: um plugin honesto cujo hook envia o diff para um endpoint de telemetria do autor. Num projeto pessoal, ninguém se importa. Num repositório do Meridiano, é dado de cliente saindo do ambiente controlado — possivelmente violando a cláusula que a Decisão 1 trata.

A revisão avalia o plugin. Ela não conhece o seu contrato.

Checklist antes de instalar plugin de terceiro

Para inspecionar antes de instalar de verdade, use claude --plugin-dir apontando para uma cópia local do plugin, numa máquina sem pasta de cliente.

Regra Wayon Plugin de terceiro em máquina com acesso a pasta de cliente exige aprovação prévia do responsável técnico, com o checklist acima preenchido por escrito. Dois itens são veto automático até haver justificativa documentada: plugin com settings.json contendo a chave agent (porque troca o comportamento padrão do Claude Code de quem instalou) e plugin com bin/ (porque altera o PATH do Bash). Marketplace da comunidade não substitui essa aprovação — a revisão dele não conhece o contrato do cliente.

📖 Segurança de plugins · Configuração padrão de plugin

Quiz — 5 questões

1.Um plugin do marketplace da comunidade traz um settings.json com { "agent": "sap-expert" }. O que acontece ao ativá-lo?
  • a)Um subagente novo fica disponível para você invocar quando quiser

    Isso descreve um subagente comum em agents/; a chave agent faz algo mais forte.

  • b)Aquele subagente passa a ser a thread principal, aplicando o system prompt, a restrição de ferramentas e o modelo dele — o comportamento padrão do Claude Code muda

    Correto. É o único mecanismo em que instalar algo troca quem o Claude é por padrão.

  • c)A status line passa a exibir o nome do subagente ativo

    Isso é a outra chave honrada, subagentStatusLine — que é cosmética, ao contrário de agent.

Ver resposta e por quê
❌a) Isso descreve um subagente comum em agents/; a chave agent faz algo mais forte.
✅b) Correto. É o único mecanismo em que instalar algo troca quem o Claude é por padrão.
❌c) Isso é a outra chave honrada, subagentStatusLine — que é cosmética, ao contrário de agent.
2.Você instalou um plugin por causa de três skills úteis. Ele também traz um hook PreToolUse com matcher em Bash. Quando esse hook roda?
  • a)Só quando você invoca uma das skills do plugin

    Hook não é escopado à skill que você chamou; ele casa com o evento e o matcher declarados.

  • b)Só se você habilitar os hooks do plugin separadamente, depois de instalar

    Não há passo separado de habilitação: os hooks vêm ativos com o plugin.

  • c)Em toda chamada de Bash da sessão, independentemente de você estar usando as skills dele

    Correto. Você instala pelas skills e leva os hooks junto.

Ver resposta e por quê
❌a) Hook não é escopado à skill que você chamou; ele casa com o evento e o matcher declarados.
❌b) Não há passo separado de habilitação: os hooks vêm ativos com o plugin.
✅c) Correto. Você instala pelas skills e leva os hooks junto.
3.O plugin está publicado no marketplace da comunidade da Anthropic, portanto passou por revisão. Isso é suficiente para instalá-lo numa máquina com a pasta do Meridiano?
  • a)Sim — a revisão da Anthropic cobre segurança, que é justamente a preocupação

    A revisão é automatizada e filtra o obviamente malicioso; ela não avalia adequação ao seu contexto contratual.

  • b)Sim, desde que o plugin tenha mais de mil instalações

    Volume de instalação mede popularidade, não adequação a um contrato de cliente específico.

  • c)Não — a revisão não conhece o seu contrato; um hook que envia diff para telemetria passa na revisão e é vazamento de dado de cliente no Meridiano

    Correto. Revisado não é confiável no seu contexto.

Ver resposta e por quê
❌a) A revisão é automatizada e filtra o obviamente malicioso; ela não avalia adequação ao seu contexto contratual.
❌b) Volume de instalação mede popularidade, não adequação a um contrato de cliente específico.
✅c) Correto. Revisado não é confiável no seu contexto.
4.Ao inspecionar um plugin, você encontra uma pasta bin/ com um executável. Por que isso merece atenção?
  • a)Porque bin/ indica que o plugin foi empacotado errado

    bin/ é um diretório legítimo e documentado da estrutura de plugin.

  • b)Porque executáveis em bin/ entram no PATH do Bash enquanto o plugin está ativo

    Correto — e um executável com nome de ferramenta conhecida poderia ser chamado no lugar dela.

  • c)Porque bin/ só funciona em Linux e quebraria a instalação no Windows

    A questão não é portabilidade; é o efeito sobre o PATH da ferramenta Bash.

Ver resposta e por quê
❌a) bin/ é um diretório legítimo e documentado da estrutura de plugin.
✅b) Correto — e um executável com nome de ferramenta conhecida poderia ser chamado no lugar dela.
❌c) A questão não é portabilidade; é o efeito sobre o PATH da ferramenta Bash.
5.Você quer inspecionar um plugin de terceiro com segurança antes de decidir. Qual é o caminho mais adequado? ---
  • a)Carregar com claude --plugin-dir a partir de uma cópia local, numa máquina sem pasta de cliente

    Correto. Carrega sem instalar e mantém o risco longe de material de cliente.

  • b)Instalar normalmente e desinstalar depois, se algo parecer errado

    Os hooks e a chave agent já valem enquanto está instalado; o dano possível acontece antes de você notar.

  • c)Instalar apenas no escopo de projeto, que é isolado do resto da máquina

    Escopo de instalação define quem herda o plugin, não impede o código dele de rodar com as suas permissões.

Ver resposta e por quê
✅a) Correto. Carrega sem instalar e mantém o risco longe de material de cliente.
❌b) Os hooks e a chave agent já valem enquanto está instalado; o dano possível acontece antes de você notar.
❌c) Escopo de instalação define quem herda o plugin, não impede o código dele de rodar com as suas permissões.