Plugins do Claude Code: o que são e quanto custam

O que é um plugin do Claude Code

Um plugin do Claude Code é um diretório com componentes que o Claude Code carrega e gere como uma única unidade. Esses componentes são skills, agents, hooks, servidores MCP, servidores LSP e monitores em segundo plano. A instalação de um plugin adiciona todas as suas partes de uma só vez, sob um único nome. A desativação remove-as da mesma forma.

Um plugin não dá ao agent nenhuma capacidade que ele já não tivesse. Cada parte de um plugin pode ser criada manualmente num diretório .claude/. O plugin é a camada de empacotamento: uma forma de versionar essas partes, entregá-las a quinze pessoas e atualizá-las posteriormente sem pedir a todos que copiem ficheiros. Essa é toda a ideia. A maior parte da confusão sobre plugins surge quando se espera que sejam um novo tipo de capacidade.

O manifesto opcional em .claude-plugin/plugin.json identifica o plugin. Esse nome torna-se um namespace. Uma skill num plugin chamado commit-commands é invocada como /commit-commands:commit. Assim, dois plugins podem disponibilizar uma skill chamada commit sem que uma oculte a outra. Os agents dos plugins seguem o mesmo escopo na lista de menções com @, como plugin-name:agent-name.

Plugin, skill, servidor MCP ou ficheiro de regras

Estas quatro expressões são usadas como se fossem alternativas. Não são, e vale a pena esclarecer a diferença uma vez.

• Um skill é uma unidade de instruções que o Claude carrega quando a tarefa o exige. Consulte o que é realmente um Agent Skill.
• Um servidor MCP é um processo separado que expõe ferramentas ao agente através de um protocolo. Muitas vezes, é um serviço de rede que você próprio executa.
• Um ficheiro de regras, como CLAUDE.md, é contexto do projeto lido no início da sessão e aplicado a tudo.
• Um plugin é um contentor que pode reunir skills, agentes, hooks e definições de servidores MCP, além de um número de versão e de um canal de distribuição.

Por isso, a pergunta respondida por um plugin não é "o que pode o agente fazer". É "como distribuo isto à minha equipa e faço a atualização no próximo mês". Se estiver a escolher entre os três primeiros, a comparação entre skills, servidores MCP e ficheiros de regras explica essa decisão em detalhe. Se o servidor MCP for o que lhe interessa, executar os seus próprios servidores MCP num VPS explica a parte de alojamento.

Onde ficam os plugins e o que existe dentro de um deles

Um plugin instalado a partir de um marketplace é copiado para um cache local em ~/.claude/plugins/cache, em vez de ser executado a partir do local onde foi clonado. Cada versão instalada recebe o seu próprio diretório. Quando atualiza ou desinstala um plugin, o diretório da versão antiga é marcado como órfão e eliminado cerca de duas semanas depois. Assim, uma sessão que já carregou a versão antiga continua a funcionar, em vez de falhar a meio da tarefa.

Como o caminho muda a cada atualização, um plugin nunca deve codificar o seu próprio local. Os hooks e as configurações MCP dentro de um plugin usam ${CLAUDE_PLUGIN_ROOT}, que é resolvido para o diretório de instalação atual. O estado que deve sobreviver a uma atualização fica em ${CLAUDE_PLUGIN_DATA}, que é resolvido para um diretório estável dentro de ~/.claude/plugins/data/.

Apenas o diretório do próprio plugin é copiado para o cache. Isto tem uma consequência que muitas pessoas só descobrem mais tarde. Um caminho que aponta para fora da raiz do plugin, como ../shared-utils, funciona enquanto desenvolve com um caminho local e deixa de funcionar depois da instalação, porque esses ficheiros nunca foram copiados.

A estrutura é a seguinte.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

Apenas plugin.json fica dentro de .claude-plugin/. Todo o resto fica na raiz do plugin. Colocar skills/ ou hooks/ dentro de .claude-plugin/ é o motivo mais comum para um plugin ser instalado corretamente e depois não fazer nada: o Claude Code procura esses diretórios na raiz, não encontra nenhum e carrega um plugin sem componentes.

O manifesto é pequeno.

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

Como instalar um plugin do Claude Code

A instalação tem duas etapas, e a primeira não instala nada. Adicione um marketplace, que é um catálogo de plugins, e depois instale plugins individuais a partir dele. O marketplace oficial da Anthropic, claude-plugins-official, é registado automaticamente na primeira vez que inicia o Claude Code de forma interativa. Os outros marketplaces são adicionados manualmente.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

Tenha em atenção que o repositório é anthropics/claude-code, enquanto o marketplace se chama claude-code-plugins. O nome vem do ficheiro de catálogo dentro do repositório, não do caminho do repositório. Por isso, leia o nome do marketplace no separador Marketplaces de /plugin antes de introduzir um comando de instalação.

Depois da instalação, leia a linha de resumo. Plugin is now active. significa que os componentes foram carregados nesta sessão. Run /reload-plugins to activate. significa que não foram carregados e que é necessário executar esse comando. Se /reload-plugins avisar que a conversa seria lida novamente, execute-o como /reload-plugins --force. Em seguida, confirme que o plugin está realmente disponível: /plugin mostra-o no separador Installed, /help lista as respetivas skills no separador Custom commands, e tudo o que não foi carregado aparece no separador Errors, juntamente com o motivo.

A instalação pede um scope, que determina quem recebe o plugin. O scope de utilizador aplica-se a si, em todos os projetos. O scope de projeto grava o plugin no .claude/settings.json do repositório, em enabledPlugins, para que seja disponibilizado a todas as pessoas que clonarem o repositório. O scope local aplica-se a si apenas neste repositório.

Para um script, um Dockerfile ou qualquer sessão em que não esteja disponível um painel interativo, use a forma shell. A instalação é feita no scope de utilizador, exceto se indicar --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install é executado fora de uma sessão. Por isso, uma sessão já aberta não verá o novo plugin até executar /reload-plugins ou iniciar uma nova sessão.

A gestão dos plugins instalados segue o mesmo padrão em ambos os locais. /plugin list apresenta o que está instalado e aceita --enabled ou --disabled. /plugin disable name@marketplace desativa um plugin sem o remover, /plugin enable volta a ativá-lo e /plugin uninstall remove-o. As formas de comando com barra abrem o painel de plugins para aplicar a alteração. Por isso, em scripts, use os equivalentes shell claude plugin ....

Para disponibilizar um marketplace a toda a equipa, coloque-o no .claude/settings.json do projeto. Os membros serão convidados a instalá-lo depois de confiarem na pasta do repositório.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

Enquanto desenvolve o seu próprio plugin, ignore o marketplace. claude --plugin-dir ./my-plugin carrega um diretório para essa sessão, /reload-plugins deteta as suas alterações sem reiniciar e claude plugin validate ./my-plugin verifica o manifest, o frontmatter das skills e dos agents e hooks/hooks.json antes de o plugin ser utilizado por outras pessoas.

Quanto custa um plugin do Claude Code?

O mecanismo é gratuito. Em agosto de 2026, não existe qualquer custo para adicionar um marketplace, instalar um plugin ou manter um plugin ativado. Os marketplaces oficiais e comunitários são repositórios git públicos, e um plugin é um diretório de ficheiros de texto.

O que um plugin custa são tokens, e são os tokens que o consumo da sua subscrição ou a sua fatura da API mede efetivamente. Esse custo surge de três formas diferentes, que se comportam de maneira distinta.

Custo de contexto permanente. O conteúdo que um plugin acrescenta fica no seu contexto e é relido a cada turno da sessão. Antes de instalar, a vista de detalhes /plugin mostra uma estimativa Context cost em tokens e uma secção Will install que lista os comandos, skills, agents, hooks e servidores MCP e LSP que está prestes a adicionar. Leia ambas. Os plugins de marketplaces locais ou personalizados podem não fornecer esses dados; nesse caso, terá de fazer a estimativa manualmente. Um plugin que inclui um servidor MCP costuma ser o mais pesado, porque as definições das ferramentas são grandes, embora, nos modelos que suportam a pesquisa de ferramentas MCP, essas definições sejam adiadas até ser necessária uma ferramenta.

Custo de invocação. Executar a skill de um plugin acrescenta as respetivas instruções à conversa, pelo que só paga o conteúdo da skill quando a utiliza. Um agent funciona de forma diferente. Um subagent executa a sua própria conversa, com o seu próprio system prompt e a sua própria cache, começando sem cache hits. Por isso, um plugin cujo workflow inicia agents custa consideravelmente mais do que a estimativa de contexto sugere.

Custo de cache. Ativar ou desativar um plugin a meio de uma sessão pode obrigar o pedido seguinte a processar novamente toda a conversa. Skills, commands, agents, hooks, servidores LSP, monitors e themes nunca fazem isto: o conteúdo que acrescentam é anexado depois do histórico existente, pelo que o pedido seguinte paga pelo conteúdo novo e continua a ler tudo o que o precede a partir da cache. A exceção é um plugin que fornece um servidor MCP. Se as respetivas ferramentas forem adiadas pela pesquisa de ferramentas, a cache é preservada. Se forem carregadas no prefixo do prompt, o pedido seguinte relê toda a conversa como entrada sem cache. É exatamente por isso que /reload-plugins apresenta um aviso e recusa essa operação nesse caso, até passar --force.

Pode acompanhar este comportamento em vez de o calcular por estimativa. Todas as respostas da API apresentam cache_read_input_tokens e cache_creation_input_tokens, e uma statusline personalizada com o consumo de tokens em tempo real mostra ambos. Numa sessão saudável, a quantidade lida é muito superior à quantidade criada. Se a criação se mantiver elevada turno após turno, algo no seu prefixo está a mudar a cada turno. Para uma visão mais abrangente do que está a preencher a janela, consulte como gerir a janela de contexto do Claude Code e o que significam efetivamente essas contagens de tokens.

Uma tarefa de manutenção compensa por si só. O separador Installed agrupa, sob um cabeçalho Not used recently, os plugins que não utilizou há pelo menos duas semanas, com uma linha Last used na vista de detalhes. Esses plugins continuam a consumir tempo de arranque e contexto em todas as sessões. Desative-os ou desinstale-os.

Um plugin é executado com as suas permissões

A própria documentação da Anthropic é clara: plugins e marketplaces são componentes altamente confiáveis que podem executar código arbitrário na sua máquina com os privilégios do seu utilizador. Isto não é uma hipótese teórica. Os hooks de um plugin executam comandos shell em eventos da sessão, incluindo antes e depois das chamadas de ferramentas. O diretório bin/ é adicionado ao PATH da ferramenta Bash enquanto o plugin está ativo. Os servidores MCP são processos iniciados pelo próprio plugin. Nada disto fica isolado da sua conta de utilizador.

Num laptop, esse risco é limitado pelo que o seu utilizador do ambiente de trabalho consegue aceder. Num servidor, normalmente não é. A conta que executa o agente costuma ter chaves SSH, tokens de implementação, uma sessão da CLI da cloud e acesso ao socket do Docker. Por isso, "código arbitrário como o seu utilizador" significa acesso à máquina. Se o Claude Code for executado numa VPS, leia como executar o Claude Code com segurança numa VPS antes de instalar qualquer coisa. Leia também como manter as credenciais fora do alcance de um agente antes de instalar um plugin que comunica com um serviço externo.

Existem algumas proteções, e é útil saber quais. Um plugin com âmbito de projeto vem do repositório e não de si. Por isso, só é carregado depois de confiar no workspace. Os respetivos servidores MCP continuam a exigir aprovação individual por servidor. Os servidores LSP aguardam essa aprovação. Os monitores em segundo plano não são carregados. Os agentes fornecidos com plugins não podem declarar hooks, servidores MCP nem um modo de permissões. Os plugins de marketplaces são copiados para a cache, mas as ligações simbólicas que apontam para fora do marketplace são ignoradas. Assim, um plugin não pode incluir ficheiros arbitrários do host.

Nada disto substitui a leitura do que instala. Verifique a lista Will install. Prefira plugins cujo código-fonte possa abrir e ler. Mantenha os plugins da sua equipa num repositório de marketplace sob o seu controlo. Execute claude plugin validate em tudo o que escrever pessoalmente.

FAQ

Os plugins do Claude Code têm custos adicionais?

Não. Não existe qualquer custo pelo sistema de plugins, pela adição de um marketplace ou pela instalação de um plugin. O custo corresponde ao uso de tokens e é faturado no seu plano ou no seu consumo da API, tal como qualquer outro contexto. Um plugin adiciona contexto permanente em cada interação, adiciona mais contexto quando uma das suas skills ou agents é invocada e pode forçar uma interação dispendiosa sem cache se fornecer um servidor MCP cujas ferramentas sejam carregadas no prefixo do prompt. A vista detalhada /plugin mostra uma estimativa Context cost antes da instalação.

Qual é a diferença entre um plugin e uma skill?

Uma skill é uma unidade individual de instruções. Um plugin é um pacote que pode conter skills, agents, hooks, servidores MCP, servidores LSP e monitores, com um nome, uma versão e um marketplace a partir do qual pode ser instalado. Escreva uma skill autónoma em .claude/ quando ela se destinar a si e a este projeto. Uma skill de finalidade única, como Ponytail, que orienta o agente para a alteração funcional mais pequena, é o exemplo mais claro: um ficheiro com uma regra, até ao dia em que a sua equipa também precisar dela. Transforme-a num plugin quando outras pessoas precisarem dela e for necessário atualizá-la ao longo do tempo. As skills dos plugins têm um namespace, pelo que uma skill dentro de um plugin é invocada como /plugin-name:skill-name, e não como /skill-name.

O meu plugin foi instalado, mas as respetivas skills não aparecem. Qual é o problema?

Consulte primeiro o resumo da instalação. Se indicar Run /reload-plugins to activate., os componentes ainda não foram carregados. Se o reload avisar que vai reler a conversa, execute-o novamente como /reload-plugins --force. Se tiver sido carregado, mas não mostrar nada, abra /plugin e leia o separador Errors. O erro estrutural mais comum é colocar skills/, agents/ ou hooks/ dentro de .claude-plugin/, onde o Claude Code não os procura. Lembre-se de que as skills dos plugins têm um namespace. Procure /plugin-name:skill-name no separador Custom commands de /help. Como último recurso, execute rm -rf ~/.claude/plugins/cache, reinicie e reinstale.

Posso instalar plugins sem o painel interativo?

Sim. Use o comando de shell claude plugin install name@marketplace, que instala no âmbito do utilizador, exceto se passar --scope project ou --scope local. Funciona em scripts, imagens e ambientes não interativos onde o painel /plugin não está disponível. Como é executado fora de uma sessão, uma sessão já aberta precisa de /reload-plugins antes de o plugin produzir efeito.

É seguro instalar um plugin de um marketplace que encontrei no GitHub?

Trate-o como trataria a execução do script de instalação desse repositório com a sua conta, porque é praticamente isso que acontece. Um plugin pode executar comandos de shell através de hooks, adicionar executáveis ao PATH da ferramenta Bash e iniciar servidores MCP, tudo com os privilégios do seu utilizador. A Anthropic não controla nem verifica o conteúdo de plugins de terceiros. Instale a partir de fontes que possa ler, reveja a lista Will install antes de confirmar e seja mais rigoroso num servidor do que num portátil, porque a conta nesse servidor normalmente contém chaves e tokens que podem ser roubados.