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 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 partes de uma só vez, sob um único nome, e a sua 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 é algo que pode escrever 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 dá nome ao plugin, e esse nome torna-se um namespace. Uma skill num plugin chamado commit-commands é invocada como /commit-commands:commit, por isso dois plugins podem disponibilizar cada um 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 estabelecer esta distinção uma vez.

• Uma skill é uma unidade de instruções que o Claude carrega quando a tarefa o exige. Consulte o que é realmente uma Agent Skill.
• Um servidor MCP é um processo separado que expõe ferramentas ao agente através de um protocolo, muitas vezes como um serviço de rede que o próprio utilizador 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 incluir 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 a que um plugin responde não é "o que pode o agente fazer". É "como distribuo isto pela 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 componente MCP for o que lhe interessa, executar os seus próprios servidores MCP num VPS aborda a parte do alojamento.

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

Um plugin instalado a partir de um marketplace é copiado para uma 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 o 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 a sua própria localização. Os hooks e as configurações MCP dentro de um plugin usam ${CLAUDE_PLUGIN_ROOT}, que resolve para o diretório de instalação atual. O estado que deve persistir durante uma atualização fica em ${CLAUDE_PLUGIN_DATA}, que resolve para um diretório estável dentro de ~/.claude/plugins/data/.

Apenas o diretório do próprio plugin é copiado para a 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/. Tudo o resto fica na raiz do plugin. Colocar skills/ ou hooks/ dentro de .claude-plugin/ é o motivo mais comum para um plugin ser instalado sem erros e depois não fazer absolutamente nada: 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. Deve adicionar um marketplace, que é um catálogo de plugins, e depois instalar plugins individuais a partir dele. O marketplace oficial da Anthropic, claude-plugins-official, fica 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 escrever 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 deve executar esse comando. Se /reload-plugins avisar que a operação voltaria a ler a conversa, execute-o novamente como /reload-plugins --force. Depois, 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 tenha sido 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 escreve o plugin no .claude/settings.json do repositório, em enabledPlugins, por isso todos os utilizadores que clonarem o repositório receberão a proposta de instalação. 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. Por predefinição, instala no scope de utilizador, exceto se passar --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 nos dois locais. /plugin list mostra 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 do plugin para aplicar a alteração. Por isso, em scripts, deve usar as equivalentes shell claude plugin ....

Para disponibilizar um marketplace a toda uma equipa, coloque-o no .claude/settings.json do projeto. Os membros receberão uma proposta para o instalar 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 completamente o marketplace. claude --plugin-dir ./my-plugin carrega um diretório apenas para essa sessão, /reload-plugins deteta as suas alterações sem reiniciar e claude plugin validate ./my-plugin valida o manifest, o frontmatter das skills e dos agents e hooks/hooks.json antes de o plugin ser disponibilizado a outras pessoas.

Quanto custa um plugin do Claude Code?

O mecanismo é gratuito. Em agosto de 2026, não há qualquer cobrança 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 uso da subscrição ou a fatura da API mede efetivamente. Qual destas duas formas de cobrança um plugin afeta depende da forma como paga a ferramenta, e o custo do Claude Code em cada plano apresenta os níveis de subscrição juntamente com os preços da API por token. Esse custo surge de três formas diferentes, que têm comportamentos distintos.

Custo de contexto persistente. O conteúdo que um plugin adiciona fica no seu contexto e é relido em 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 com os comandos, skills, agentes, 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. No entanto, nos modelos que suportam a pesquisa de ferramentas MCP, essas definições só são carregadas quando uma ferramenta é necessária.

Custo de invocação. Executar a skill de um plugin acrescenta as instruções dessa skill à conversa. Por isso, só paga pelo corpo da skill quando a utiliza. No entanto, o corpo é a parte barata, e as ações que a skill instrui o agente a executar podem não ser: o método Depth Tree da skill unlazy gasta quase todos os seus tokens nas passagens adicionais que impõe antes de permitir que o agente marque uma tarefa como concluída, e não no ficheiro que instalou. Um agente é diferente. Um subagente 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 fluxo de trabalho cria agentes custa consideravelmente mais do que a estimativa de contexto indica.

Custo da cache. Ativar ou desativar um plugin a meio de uma sessão pode obrigar o pedido seguinte a processar novamente toda a conversa. Skills, comandos, agentes, hooks, servidores LSP, monitores e temas nunca fazem isso: o conteúdo que adicionam é anexado depois do histórico existente. Assim, o pedido seguinte paga pelo conteúdo novo e continua a ler da cache tudo o que vem antes. 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 a operação nesse caso, até passar --force.

Pode monitorizar este comportamento em vez de o estimar. Cada resposta da API informa cache_read_input_tokens e cache_creation_input_tokens, e uma statusline personalizada que mostra o uso de tokens em tempo real apresenta ambos os valores. Uma sessão saudável lê muito mais do que cria. Se a criação se mantiver elevada em todos os turnos, algo no seu prefixo está a mudar a cada turno. Para obter uma visão mais ampla do que está a preencher a janela, consulte como gerir a janela de contexto do Claude Code e o que essas contagens de tokens significam efetivamente.

Uma tarefa de manutenção compensa por si própria. O separador Installed agrupa, sob um cabeçalho Not used recently, os plugins que não utiliza há pelo menos duas semanas. A vista de detalhes inclui uma linha Last used. 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 sobre isto: 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 meramente teórica. Os hooks de um plugin executam comandos da 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á ativado. Os servidores MCP são processos iniciados pelo plugin. Nada disto fica isolado da sua conta de utilizador por uma sandbox.

Num portátil, 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 de cloud e acesso ao socket do Docker. Por isso, "código arbitrário como o seu utilizador" significa, na prática, a máquina. Se o Claude Code for executado num VPS, leia como executar o Claude Code com segurança num VPS antes de instalar qualquer coisa, e como manter as credenciais fora do alcance de um agente antes de instalar um plugin que comunique com um serviço externo. Outros harnesses enfrentam o mesmo problema na mesma máquina alugada. Por isso, os plugins do DeepSeek Harness que vale a pena instalar consistem sobretudo em limites de gastos, regras de permissões de ferramentas e análise de injeções, em vez de novas capacidades.

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 por servidor, os servidores LSP aguardam essa confiança e os monitores em segundo plano não são carregados. Os agentes fornecidos pelos 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 disso 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 que controle e execute claude plugin validate em tudo o que escrever por iniciativa própria.

FAQ

Os plugins do Claude Code têm custo adicional?

Não. Não há cobrança pelo sistema de plugins, pela adição de um marketplace nem pela instalação de um plugin. O custo corresponde ao uso de tokens, cobrado no seu plano ou no seu consumo da API, 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 sem cache mais dispendiosa se fornecer um servidor MCP cujas ferramentas sejam carregadas no prefixo do prompt. A vista detalhada /plugin mostra uma estimativa de Context cost antes da instalação.

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

Uma skill é uma unidade única 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 menor alteração que funciona, é 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 ela tiver de ser atualizada ao longo do tempo. As skills dos plugins usam namespaces, por isso 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 skills não aparecem. O que está errado?

Consulte primeiro o resumo da instalação. Se ele 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 o plugin tiver sido carregado, mas não mostrar nada, abra /plugin e consulte 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 usam namespaces. 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, a menos que passe --scope project ou --scope local. Ele 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 ele faz. 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.