Plugins do Claude Code: o que são e quanto custam
Entenda onde ficam os plugins do Claude Code, como instalar e o custo real: o mecanismo não cobra nada, mas o conteúdo usado consome tokens no contexto.
O que é um plugin do Claude Code
Um plugin do Claude Code é um diretório de componentes que o Claude Code carrega e gere como uma unidade. Os principais componentes são skills, agents, hooks, servidores MCP, servidores LSP e monitores em segundo plano. Um plugin também pode incluir comandos, estilos de saída, temas, workflows e um diretório bin/ de executáveis. A instalação de um plugin adiciona todas as suas partes de uma só vez, com um único nome. A sua desativação remove-as da mesma forma.
Um plugin, em geral, não dá ao agent nenhuma capacidade que ele já não tivesse. Skills, agents, hooks e servidores MCP podem ser escritos manualmente num diretório .claude/. As exceções são os servidores de linguagem para inteligência de código e os mods, que o Claude Code só carrega a partir de um plugin. Nos restantes casos, o plugin é a camada de empacotamento. Permite versionar esses componentes, distribuí-los por quinze pessoas e atualizá-los mais tarde sem pedir a cada pessoa que copie 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 incluir uma skill chamada commit sem que uma oculte a outra. Os agents dos plugins seguem o mesmo mecanismo de 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.
- 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 é executado por si.
- Um ficheiro de regras como
CLAUDE.mdfornece o contexto do projeto. É lido no início da sessão e aplica-se a tudo. - Um plugin é um diretório de skills, agents, hooks, servidores MCP ou outros componentes que o Claude Code instala e carrega como uma unidade. O seu manifesto opcional identifica-o e pode adicionar uma versão, uma descrição e outros metadados. A distribuição não faz parte do plugin: um marketplace é um catálogo separado que lista os plugins e indica onde obter cada um.
Por isso, a pergunta a que um plugin responde não é "o que pode o agente fazer". É "como disponibilizo isto à minha equipa e atualizo-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 a parte do MCP for a sua preocupação, executar os seus próprios servidores MCP num VPS explica a parte do alojamento.
Onde os plugins ficam e o que existe dentro deles
A maioria dos plugins do marketplace é copiada para uma cache local em ~/.claude/plugins/cache, com um diretório separado para cada versão instalada. Os plugins com caminhos relativos num marketplace adicionado a partir de um caminho local são carregados no próprio local, e os plugins de origem de comandos em modo de link são carregados através de links para o respetivo diretório de origem. Quando atualiza ou desinstala um plugin copiado, o diretório da versão antiga é marcado como órfão e eliminado cerca de duas semanas depois. Assim, uma sessão que já tenha carregado a versão antiga continua a funcionar, em vez de falhar a meio da tarefa. A limpeza só é executada enquanto existir pelo menos uma instalação de plugin registada. Depois de desinstalar o último plugin, os diretórios órfãos permanecem até instalar outro.
Como o caminho de um plugin copiado muda em cada atualização, um plugin nunca deve definir a própria localização de forma fixa. 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 tem de sobreviver a uma atualização deve ser colocado em ${CLAUDE_PLUGIN_DATA}, que é resolvido para um diretório estável sob ~/.claude/plugins/data/.
Num plugin copiado, apenas o diretório do próprio plugin é copiado para a cache, exceto os destinos de links simbólicos existentes noutro local do mesmo marketplace, que são copiados para o local correspondente. Um script que leia um caminho fora da raiz do plugin, como ../shared-utils, funciona enquanto desenvolve com um caminho local e deixa de funcionar quando o plugin é copiado para a cache, porque esses ficheiros nunca foram copiados. Um caminho de componente declarado dessa forma em plugin.json falha mais cedo: o Claude Code rejeita qualquer caminho de componente que saia da raiz do plugin, também durante o desenvolvimento, com um erro path escapes plugin directory.
A estrutura é semelhante a esta.
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 sem erros e depois não fazer absolutamente 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. Você adiciona um marketplace, que é um catálogo de plugins, e depois instala 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, exceto quando uma política gerida ou CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL o bloqueia. Os restantes marketplaces são adicionados manualmente.
/plugin marketplace add anthropics/claude-plugins-official
/plugin install commit-commands@claude-plugins-officialO nome do marketplace vem do ficheiro de catálogo dentro do repositório, não do caminho do repositório. Por isso, consulte o nome do marketplace no separador Marketplaces de /plugin antes de escrever um comando de instalação. O marketplace antigo claude-code-plugins em anthropics/claude-code está obsoleto; use claude-plugins-official para novas instalações. Os plugins existentes desse marketplace antigo são atualizados a partir do repositório oficial. Não precisa de reinstalar commit-commands apenas para mudar de marketplace.
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 apply. significa que não foram ativados durante a instalação; o painel fecha e o Claude Code executa o reload por si. Se o reload avisar que teria de ler novamente a conversa, o plugin fica pendente. Nesse caso, execute novamente como /reload-plugins --force. Confirme depois que o plugin está realmente disponível: /plugin mostra-o no separador Installed, escrever / lista as respetivas skills como /plugin-name:skill-name, 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 escreve o plugin no .claude/settings.json do repositório, em enabledPlugins, e ativa-o para todas as pessoas que clonarem o repositório. Isto não faz o download por elas. Cada colaborador continua a ter de o instalar uma vez na sua própria máquina, por exemplo com claude plugin install name@marketplace --scope project, exceto quando a entrada do marketplace é um caminho relativo ou quando um diretório seed já o contém. 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. Numa máquina onde ainda ninguém iniciou uma sessão interativa, o marketplace oficial não está registado. Nesse caso, adicione-o primeiro.
claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install commit-commands@claude-plugins-official --scope project
claude plugin listclaude 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 sessão nova.
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 slash command abrem o painel de plugins para aplicar a alteração. Por isso, use os equivalentes shell claude plugin ... em scripts.
Para disponibilizar um marketplace a toda a equipa, coloque-o no .claude/settings.json do projeto ou execute claude plugin marketplace add your-org/claude-plugins --scope project uma vez e faça commit do ficheiro que este comando criar. O Claude Code regista o marketplace para cada membro depois de essa pessoa confiar na pasta do repositório.
{
"extraKnownMarketplaces": {
"my-team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}Enquanto desenvolve o seu próprio plugin, não use um 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 utilizado por outras pessoas. Também não é necessário um marketplace para partilhar um plugin. Pode enviar a pasta ou um .zip dela para ser carregado com --plugin-dir. No entanto, o destinatário não receberá atualizações até lhe enviar uma cópia nova.
Quanto custa um plugin do Claude Code?
O mecanismo é gratuito. Em novembro de 2026, não há cobrança para adicionar um marketplace, instalar um plugin ou mantê-lo ativado. Os marketplaces oficiais e da comunidade são repositórios git públicos, e um plugin é um diretório de ficheiros de texto.
O custo de um plugin é medido em tokens, que são o que o uso da subscrição ou a fatura da API efetivamente contabiliza. Qual dos dois é consumido pelo plugin 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 do contexto permanente. Cada plugin ativado coloca no seu contexto os nomes e as descrições das skills, dos agentes e dos comandos que o Claude pode invocar por iniciativa própria. Essa parte é lida novamente em cada turno da sessão, seja ou não executada. Nem todos os componentes consomem tokens: um hook é executado pelo harness e não adiciona nada ao contexto do modelo. Antes de instalar, a vista de detalhes /plugin mostra uma secção Will install com os comandos, skills, agentes, hooks e servidores MCP e LSP que está prestes a adicionar. Para um plugin no marketplace oficial da Anthropic, também mostra uma secção Context cost com estimativas de Every turn e When invoked, desde que abra o plugin pelo nome no marketplace ou a partir do separador Marketplaces, e não da lista Discover. Consulte ambas. Um plugin do seu próprio marketplace ou de um marketplace de terceiros não tem a secção Context cost, mas não precisa de fazer uma estimativa manualmente: claude plugin details name na sua shell apresenta um valor de tokens Always-on e uma discriminação por componente para qualquer plugin carregado, incluindo um plugin indicado com --plugin-dir. Assim, pode clonar um repositório e executar claude --plugin-dir ./that-plugin plugin details that-plugin antes de instalar qualquer coisa. Esse valor não inclui servidores MCP. Um plugin que inclui um servidor MCP é normalmente o mais pesado, porque as definições das ferramentas são extensas. No entanto, nos modelos compatíveis com a pesquisa de ferramentas MCP, essas definições são adiadas até ser necessária uma ferramenta. Execute /context numa sessão com o plugin ativado e consulte a linha MCP tools para ver o que adicionam.
Custo de invocação. Executar a skill de um plugin acrescenta as respetivas instruções à conversa. Por isso, só paga o corpo da skill quando ela é utilizada. O corpo é a parte barata. O que a skill instrui o agente a fazer pode não ser: o método Depth Tree da skill unlazy consome quase todos os seus tokens nas passagens adicionais que impõe antes de permitir que o agente dê uma tarefa como concluída, e não no ficheiro instalado. Um agente é diferente. Um subagente executa a sua própria conversa, com o seu próprio prompt de sistema 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 sugere.
Custo da cache. Ativar ou desativar um plugin durante uma sessão pode obrigar o pedido seguinte a processar novamente toda a conversa. Skills, comandos, agentes, hooks, monitores e temas nunca fazem isto: 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 veio antes. As exceções são um plugin que fornece um servidor MCP e um plugin de inteligência de código, cujo servidor de linguagem fornece a ferramenta LSP ao Claude. No caso do MCP, depende da pesquisa de ferramentas: se as ferramentas forem adiadas, a cache é preservada; se forem carregadas no prefixo do prompt, o pedido seguinte volta a ler toda a conversa como entrada sem cache. É precisamente por isso que /reload-plugins apresenta um aviso e recusa a alteração quando uma mudança nas ferramentas MCP ou na ferramenta LSP quebraria a cache, até passar --force.
Pode acompanhar estes valores em vez de os estimar. Cada resposta da API apresenta cache_read_input_tokens e cache_creation_input_tokens, e uma statusline personalizada com o uso de tokens em tempo real mostra ambos. Numa sessão saudável, o número de tokens lidos é muito superior ao número de tokens criados. Se a criação continuar elevada em todos os turnos, algo no seu prefixo está a mudar a cada turno. Para uma visão mais ampla do que está a ocupar 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 o custo. O separador Installed agrupa, sob um cabeçalho Not used recently, os plugins instalados a partir de marketplaces que não utilizou durante pelo menos 14 dias e 10 sessões. Na vista de detalhes, apresenta uma linha Last used. O cabeçalho exclui plugins geridos e plugins de diretórios seed, bem como plugins com um tema, estilo de saída, monitor ou fluxo de trabalho. Um servidor LSP conta como utilizado quando fornece diagnósticos ou responde a um pedido de navegação no código. Quando strictKnownMarketplaces está configurado, nem o cabeçalho nem a linha Last used: são apresentados. Esses plugins continuam a consumir tempo de arranque e contexto em todas as sessões. Desative-os ou desinstale-os. A opção mais económica é selecionar cuidadosamente antes de instalar: quais das skills de Matt Pocock vale a pena instalar analisa uma coleção de 27 skills e separa as poucas de que um programador a solo precisa das que só compensam numa equipa.
Um plugin é executado com as suas permissões
A própria documentação da Anthropic é direta sobre isto: um plugin que instala pode 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 durante eventos da sessão, incluindo antes e depois das chamadas de ferramentas. O diretório bin/ do plugin é adicionado ao PATH da ferramenta Bash enquanto o plugin está ativado. Os servidores MCP stdio do plugin são processos que ele inicia, e um mod executa JavaScript dentro do próprio Claude Code. Os hooks, monitores, processos de servidor e processos de mod são executados fora do sandbox do Claude Code; as regras de permissões continuam a aplicar-se às chamadas de ferramentas feitas pelo Claude.
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 deploy, uma sessão da CLI da cloud e acesso ao socket do Docker. Por isso, "código arbitrário como o seu utilizador" significa a máquina. Se o Claude Code for executado numa VPS, leia como executar o Claude Code em 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. Outros harnesses enfrentam o mesmo limite na mesma máquina alugada. Por isso, os plugins do DeepSeek Harness que vale a pena instalar são sobretudo 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 são. 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 precisar de aprovação individual por servidor, e os monitores em segundo plano nem sequer são carregados. Os agentes fornecidos pelos plugins não podem declarar hooks, servidores MCP nem um modo de permissões. Quando os plugins do marketplace são copiados para a cache, os symlinks que apontam para fora do marketplace são ignorados. Assim, um plugin copiado não consegue obter ficheiros arbitrários do host através desses links.
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 controla e execute claude plugin validate em tudo o que escrever. O conteúdo que reviu também pode mudar mais tarde: a atualização automática está ativada por predefinição nos marketplaces oficiais da Anthropic, exceto knowledge-work-plugins e first-party-plugins, e está desativada nos marketplaces de terceiros adicionados por origem. Quando está ativada, o Claude Code atualiza os ficheiros do plugin em segundo plano.
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 ou pela instalação de um plugin. O custo é o uso de tokens, cobrado no seu plano ou no seu consumo de API, como qualquer outro contexto. Um plugin adiciona contexto permanente em cada interação e adiciona mais contexto quando uma das suas skills ou agentes é invocada. Também pode forçar uma interação cara sem cache se fornecer um servidor MCP cujas ferramentas sejam carregadas no prefixo do prompt. Para um plugin no marketplace oficial da Anthropic, a vista de detalhes /plugin mostra uma estimativa Context cost antes da instalação. Para qualquer outro plugin, claude plugin details name apresenta o custo de tokens sempre ativo depois de o plugin ser instalado ou carregado com --plugin-dir.
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, agentes, hooks, servidores MCP, servidores LSP e monitores, com um nome, normalmente uma versão e, geralmente, um marketplace a partir do qual pode ser instalado. Também pode ser partilhado como uma pasta ou como um .zip que as pessoas carregam com --plugin-dir. 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 de plugins usam namespaces. Por isso, uma skill dentro de um plugin é invocada como /plugin-name:skill-name, e não como /skill-name.
Instalei o meu plugin, mas as respetivas skills não aparecem. O que está errado?
Verifique primeiro o resumo da instalação. Se indicar Run /reload-plugins to apply., o Claude Code executa esse reload quando o painel é fechado. 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 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 de plugins usam namespaces. Por isso, procure /plugin-name:skill-name ao escrever /. Se o plugin for de outra pessoa e for carregado sem erros, abra o painel de detalhes no separador Installed. Um plugin que não liste skills nesse separador não tem nenhuma para oferecer. Se o separador Errors indicar que o plugin não está em cache, o diretório de instalação está em falta. Reinstale-o a partir da sua shell com claude plugin install name@marketplace e execute /reload-plugins.
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 que já esteja aberta precisa de /reload-plugins antes de o plugin entrar em vigor. Numa sessão sem terminal interativo, as alterações aos servidores MCP do plugin entram em vigor na sessão seguinte.
É 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 própria conta, porque é algo muito semelhante. 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 apenas a partir de fontes que possa ler, reveja a lista Will install antes de confirmar e seja mais rigoroso num servidor do que num laptop, porque a conta nesse servidor normalmente contém chaves e tokens que podem ser roubados.