Como criar plugins Claude Code: Um guia passo a passo

O Claude Code cuida da maioria das tarefas de desenvolvimento de forma imediata, mas cada equipe tem fluxos de trabalho específicos que as configurações padrão não cobrem. Você pode querer um comando personalizado que crie componentes na estrutura preferida da sua empresa, ou uma verificação automática antes de cada commit, ou acesso rápido à documentação de uma estrutura que você usa constantemente.

Os plugins do Claude Code permitem que você mesmo adicione esses recursos. Você pode instalar plugins criados pela comunidade ou fazer o seu próprio.

Se você é novo na ferramenta de codificação de agentes da Anthropic, recomendo começar com o  Guia do Claude Code ou o curso Introdução aos Modelos Claude. Esse tutorial parte do princípio de que você já tem o Claude Code instalado e já o usou para tarefas básicas.

No final, você vai saber como:

• Encontre e instale plug-ins do diretório da Anthropic e de fontes da comunidade
• Entenda os três tipos de componentes que os plugins podem ter
• Escolha o tipo certo para diferentes casos de uso
• Crie e compartilhe seus próprios plugins

O que são plugins Claude Code?

Um plugin é um pacote que junta uma ou mais extensões do Claude Code pra facilitar o compartilhamento e a instalação. Em vez de copiar manualmente os arquivos de configuração entre máquinas ou colegas de equipe, você pode juntar tudo em um plugin e distribuir como uma única unidade.

Os plugins podem ter três tipos de componentes:

• Habilidades: Comandos personalizados que você usa com o comando " /skill-name" ou prompts contextuais que o Claude usa automaticamente quando for relevante.
• Servidores MCP: Conexões com serviços externos e APIs que dão ao Claude acesso a dados que ele não teria de outra forma.
• Ganchos: Scripts Shell que rolam automaticamente em eventos específicos, tipo antes de um arquivo ser editado ou depois de um commit.

Um plugin pode ter só um desses recursos ou juntar vários que funcionam juntos. Um plugin de “implantação” pode incluir uma habilidade /deploy para implantações manuais, um servidor MCP que verifica o status do seu ambiente de teste e um gancho que executa testes antes de qualquer comando de implantação ser executado.

O arquivo manifestoplugin.json define o que um plugin contém. Ele diz quais habilidades, servidores MCP e hooks instalar, junto com metadados como o nome do plugin, versão e autor. Quando você instala um plugin, o Claude Code lê esse manifesto e coloca cada componente no lugar certo.

Esse formato de pacote significa que você não precisa entender a estrutura interna dos arquivos das extensões do Claude Code. Você instala o plugin e tudo fica onde deveria.

Encontrando e instalando plugins Claude Code

A maioria dos plugins fica em um desses dois lugares. Diretório oficial da Anthropic em plugins.claude.ai tem plugins criados pela Anthropic, contribuições verificadas da comunidade e extensões populares de terceiros. Cada listagem mostra quais componentes o plugin contém, informações de compatibilidade e instruções de instalação.

A segunda fonte é o GitHub. O awesome-claude-code tem uma lista organizada por categoria, e os desenvolvedores individuais publicam plugins nos seus próprios repositórios.

Depois de encontrar o plugin que você quer, o comando de instalação depende de onde ele está:

# From the official directory
claude plugin add @anthropic/deploy-helper
 
# From a GitHub repository
claude plugin add github:username/repo-name
 
# From a local directory (useful during development)
claude plugin add ./my-plugin

Depois de instalar alguns plugins, você vai querer acompanhar o que está rolando com eles. O comando ` plugin ` lida com listagem, atualização e remoção:

# List all installed plugins
claude plugin list
 
# Update a specific plugin to the latest version
claude plugin update @anthropic/deploy-helper
 
# Update all plugins
claude plugin update --all
 
# Remove a plugin
claude plugin remove @anthropic/deploy-helper

Uma decisão que você vai tomar durante a instalação é o escopo. Os plugins podem ficar em dois lugares: o escopo do usuário é instalado em ~/.claude/plugins/ e funciona em todos os seus projetos, enquanto o escopo do projeto é instalado em .claude/plugins/ dentro de um repositório específico.

O padrão é o escopo do usuário. Para instalar um plugin só para o projeto atual, adicione a flag ` --project `:

claude plugin add @anthropic/deploy-helper --project

Plugins com escopo de projeto fazem sentido quando a extensão está ligada a uma base de código específica. 

Um plugin que conhece o processo de implantação da sua empresa deve fazer parte desse projeto. Um plugin que formata o código de acordo com suas preferências pessoais deve estar no nível do usuário. Quando um plugin existe nos dois escopos, a versão do projeto tem prioridade, permitindo que as equipes apliquem configurações específicas do projeto, enquanto os desenvolvedores mantêm seus plugins pessoais ativos em outros lugares.

Escolhendo o tipo certo de plugin Claude Code

Os três tipos de componentes têm funções diferentes e consomem recursos de maneiras diferentes. Entender essas vantagens e desvantagens mantém sua janela de contexto saudável e ajuda você a escolher a ferramenta certa para cada tarefa.

Habilidades vs servidores MCP: A troca simbólica

Os servidores MCP carregam todas as definições de ferramentas na janela de contexto no início da sessão. Cada ferramenta precisa de seu nome, descrição e esquema completo de parâmetros, que normalmente tem de 100 a 300 tokens por ferramenta. Uma configuração com cinco servidores consome cerca de 55.000 tokens antes mesmo de você digitar um único caractere:

• GitHub: 35 ferramentas
•  Slack: 11 ferramentas
• Sentinela: 5 ferramentas
• Grafana: 5 ferramentas
• Splunk: 2 ferramentas

Uma análise descobriu configurações com mais de 7 servidores consumindo mais de 67.000 tokens, o que é um terço da sua janela de contexto de 200 mil, que acaba antes mesmo da conversa começar.

As habilidades têm uma abordagem diferente por meio da divulgação progressiva. No começo da sessão, Claude só vê o nome de cada habilidade e uma descrição de uma linha do frontmatter YAML, tipo 100 tokens por habilidade. 

As instruções completas só são carregadas quando Claude decide que a habilidade é importante para a tarefa atual. Os arquivos de referência só são carregados quando realmente precisamos deles. E os scripts nunca entram na janela de contexto; Claude os executa externamente, e só a saída volta.

A Anthropic resolveu esse problema no final de 2025 com o Tool Search, um recurso que traz o carregamento lento para os servidores MCP. 

Em vez de pré-carregar todas as definições de ferramentas, o Claude Code agora percebe quando as descrições das ferramentas ocupariam mais de 10% do contexto disponível e muda para o carregamento sob demanda. 

Testes internos mostraram que o uso de contexto caiu de ~134.000 tokens para ~5.000 tokens em grandes bibliotecas de ferramentas. A precisão na escolha das ferramentas também melhorou, com o Opus 4 passando de 49% para 74% e o Opus 4.5 de 79,5% para 88,1% nas avaliações do MCP.

Então, quando você deve usar cada um deles?

As habilidades são mais adequadas quando você quer que o Claude tenha acesso a conhecimentos ou fluxos de trabalho que ele possa aplicar com bom senso. Uma habilidade que descreve a lista de verificação de revisão de código da sua equipe é carregada quando o Claude revisa o código, mas o Claude ainda decide como aplicar cada item com base no contexto. 

As habilidades também fazem sentido para operações que precisam de scripts para cálculos pesados, já que o código do script fica fora da janela de contexto.

Os servidores MCP são mais adequados quando Claude precisa de dados em tempo real de serviços externos, como mensagens do Slack, PRs do GitHub ou consultas a bancos de dados. Eles também são a escolha certa quando vários agentes de IA precisam das mesmas ferramentas ou quando você precisa de recursos empresariais, como registros de auditoria e permissões explícitas.

Muitas configurações juntam as duas coisas: as habilidades mostram o “como” e o “quando” com instruções em linguagem natural, enquanto os servidores MCP cuidam das chamadas de API de verdade.

Habilidades populares do Claude Code que vale a pena instalar

• Superpoderes: Mais de 20 fluxos de trabalho testados em produção para TDD, depuração e planejamento estruturado
• frontend-design: Diz pro Claude evitar uma estética genérica e tomar decisões ousadas de design.
• mcp-builder: Guia para criar servidores MCP para integrar APIs externas
•  teste de aplicativos web: Teste aplicativos web locais usando o Playwright para verificação da interface do usuário
•  criador de habilidades: Ferramenta interativa que te ajuda a desenvolver novas habilidades

Servidores MCP populares que vale a pena conectar

• Context7: Pesquisa de documentação em tempo real e específica para cada versão
• GitHub: Pesquisa no repositório, gerenciamento de relações públicas, acompanhamento de problemas
• Dramaturgo: Automação do navegador usando árvores de acessibilidade em vez de capturas de tela
• Supabase: Consultas ao banco de dados com reconhecimento de segurança em nível de linha
• Sentinela: Rastreamento de erros e monitoramento de desempenho direto no seu editor

Você também pode ler nosso guia sobre os melhores servidores MCP remotos.

Ganchos: A camada determinística

Os ganchos ficam totalmente fora do debate sobre habilidades versus MCP. Enquanto as habilidades e os servidores MCP são voltados para Claude (Claude decide quando usá-los), os ganchos são voltados para o sistema. Eles disparam em eventos como PreToolUse ou PostToolUse, executando scripts shell antes ou depois de Claude realizar ações específicas. Claude não tem voz ativa na decisão de usar ou não um gancho.

Isso faz do Hooks a escolha certa quando algo precisa acontecer sem exceção: fazer linting antes de cada commit, bloquear gravações em diretórios protegidos, registrar cada comando bash ou rodar testes antes de qualquer implantação.

Esse desenvolvedor recomenda hooks "block-at-submit" em vez de hooks "block-at-write". Bloquear Claude no meio de uma tarefa confunde o agente e gera resultados piores. A equipe dela usa um gancho PreToolUse que envolve Bash(git commit) e verifica se existe um arquivo temporário que só aparece se os testes forem aprovados. Sem arquivo, sem commit. O agente termina o trabalho e, em seguida, a validação acontece no final.

Os ganchos não adicionam sobrecarga de token, pois são executados como scripts de shell fora da janela de contexto.

Ganchos Claude úteis para configurar

• ESLint/Prettier na edição: Formatação automática dos arquivos depois que Claude os gravar
• Teste gate no commit: Bloqueie os commits até que os testes sejam aprovados
• Caminhos protegidos: Evite gravações em migrações, configurações ou diretórios de fornecedores
• Notificação sobre a conclusão: Manda alertas pelo Slack ou no desktop quando tarefas longas acabarem
• Cópia de segurança da transcrição: Salve o histórico de conversas antes de fazer a compactação

Como criar seus próprios plug-ins Claude Code

Quando uma habilidade fica no seu diretório pessoal .claude/, só você pode usá-la. Empacotá-lo como um plugin permite que você o compartilhe com colegas de equipe ou reutilize em outros projetos.

Vamos criar um plugin chamado session-logger que adiciona um comando/session-logger:summarize. Quando chamado, Claude dá uma olhada na conversa e adiciona um resumo estruturado a SESSION_LOG.md.

Crie a estrutura do plugin

Os plugins podem ficar em qualquer lugar no seu sistema de arquivos. Para este tutorial, vamos criar um no seu diretório pessoal:

cd ~
mkdir -p session-logger/.claude-plugin
mkdir -p session-logger/skills/summarize

Isso cria:

~/session-logger/
├── .claude-plugin/
│   └── plugin.json  	# manifest goes here, nowhere else
└── skills/
	└── summarize/   	# folder name becomes the command name
    	└── SKILL.md 	# must be named exactly this

Escreva o manifesto

Criar um ~/session-logger/.claude-plugin/plugin.json:

{
  "name": "session-logger",
  "description": "Log session summaries to a markdown file",
  "version": "1.0.0"
}

O campo “ name ” vira o prefixo do namespace. Todos os comandos neste plugin começam com /session-logger:.

Escreva a habilidade

Criar ~/session-logger/skills/summarize/SKILL.md:

---
description: Log a summary of the current session to SESSION_LOG.md
disable-model-invocation: true
---
 
When invoked, review the conversation and create a summary with these sections:
 
- **Date/time**: Current timestamp
- **Tasks completed**: What was accomplished
- **Files modified**: List of files created or changed
- **Decisions made**: Architectural or implementation choices
- **Open questions**: Unresolved items for future sessions
 
Append the summary to SESSION_LOG.md in the project root. Create the file if it doesn't exist.

A linha “ disable-model-invocation: true ” diz ao Claude que só você,, pode ativar essa habilidade. Sem essa bandeira, o Claude pode decidir executar o comando sozinho se achar que isso ajuda na conversa. Para um registrador ou ferramenta de implantação, geralmente você quer controle manual.

Teste localmente

Vá até qualquer projeto onde você queira usar o plugin e, em seguida, inicie o Claude Code com a --plugin-dir sinalizador apontando para o seu plugin:

cd ~/your-project
claude --plugin-dir ~/session-logger

Digite /session-logger:summarize para usar o comando. Observe que os comandos do plug-in não aparecem nas sugestões de preenchimento automático até você digitar o nome completo. O texto fica azul assim que o Claude Code reconhece que é um comando válido.

Depois de fazer algumas coisas na sessão, dá o comando. Claude analisa a conversa e adiciona uma entrada ao arquivo SESSION_LOG.md no diretório atual do seu projeto.

Compartilhe com outras pessoas

Envie seu plugin para o GitHub. Para distribuir além da clonagem manual, adicione-o a um mercado de plugins. O guia do mercado fala sobre como criar seu próprio mercado ou se inscrever em mercados já existentes.

Conclusão

Os plug-ins transformam o Claude Code de um assistente genérico em algo feito sob medida para o seu fluxo de trabalho específico. O registrador de sessão que criamos levou cerca de cinco minutos e três arquivos. A maioria dos plugins úteis não é muito mais complicada do que isso.

Se você seguiu tudo direitinho, agora tem um plugin funcionando na sua máquina. Tenta ajustar isso. Mude o formato do resumo, adicione novas seções ou troque-o por algo que sua equipe realmente precisa. A estrutura continua a mesma, seja você criando uma ferramenta pessoal rápida ou algo que vai distribuir para centenas de desenvolvedores.

Dá uma olhada nos repositórios da comunidade quando tiver tempo. Ver como os outros organizam seus plugins te ensina padrões que a documentação não mostra. E quando você criar algo útil, publique. O ecossistema cresce um plugin compartilhado de cada vez.