Como criar plugins do Claude Code: guia passo a passo

O Claude Code resolve a maior parte das tarefas de desenvolvimento logo de cara, mas cada time tem fluxos específicos que os padrões não cobrem. Talvez você queira um comando personalizado que crie componentes na estrutura preferida da sua empresa, um lint automático antes de cada commit ou acesso rápido à documentação de um framework que você usa o tempo todo.

Os plugins do Claude Code permitem que você adicione esses recursos por conta própria. Você pode instalar plugins criados pela comunidade ou desenvolver os seus.

Se você é novo na ferramenta de codificação com agentes da Anthropic, recomendo começar pelo guia do Claude Code ou pelo curso de introdução aos modelos Claude. Este tutorial parte do princípio de que você já instalou o Claude Code e o usou para tarefas básicas.

Ao final, você vai saber como:

• Encontrar e instalar plugins no diretório da Anthropic e em fontes da comunidade
• Entender os três tipos de componentes que um plugin pode conter
• Escolher o tipo certo para cada caso de uso
• Criar e compartilhar seus próprios plugins

Para uma visão geral das capacidades do modelo mais recente da Anthropic, confira nosso guia sobre o Claude Sonnet 5.

Resumo

• Plugins do Claude Code agrupam skills, servidores MCP e hooks em pacotes compartilháveis que você instala com claude plugin add

• Skills carregam sob demanda (~100 tokens cada); servidores MCP pré-carregam definições de ferramentas (reduzido pelo Tool Search); hooks rodam como scripts shell sem custo de tokens

• Use skills para conhecimento e fluxos, servidores MCP para acesso a APIs externas e hooks para regras que precisam rodar sempre

• Crie um plugin com três arquivos: um manifesto .claude-plugin/plugin.json, um diretório skills/ e um arquivo de instruções SKILL.md

O que são plugins do Claude Code?

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

Plugins podem conter três tipos de componentes:

• Skills: Comandos personalizados que você invoca com /skill-name ou prompts com reconhecimento de contexto que o Claude usa automaticamente quando fizer sentido

• 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

• Hooks: Scripts shell que rodam automaticamente em eventos específicos, como antes de um arquivo ser editado ou após um commit

Um plugin pode conter apenas um desses componentes ou combinar vários que trabalham em conjunto. Um plugin de "deploy" pode incluir uma skill /deploy para deploys manuais, um servidor MCP que verifica o status do ambiente de staging e um hook que executa testes antes de qualquer comando de deploy.

O arquivo de manifesto plugin.json define o que o plugin contém. Ele especifica quais skills, servidores MCP e hooks instalar, além de metadados como nome, versão e autor do plugin. Ao instalar um plugin, o Claude Code lê esse manifesto e configura cada componente no lugar certo.

Esse formato de empacotamento significa que você não precisa entender a estrutura interna de arquivos das extensões do Claude Code. Você instala o plugin e tudo vai para onde deve ir.

Como encontrar e instalar plugins do Claude Code

A maioria dos plugins está em dois lugares. O diretório oficial da Anthropic em claude.com/plugins inclui plugins criados pela Anthropic, contribuições verificadas da comunidade e extensões populares de terceiros. Cada listagem mostra os componentes do plugin, informações de compatibilidade e instruções de instalação.

A segunda fonte é o GitHub:

Depois de encontrar um plugin, o comando de instalação depende de onde ele está hospedado:

# Do diretório oficial
claude plugin add @anthropic/deploy-helper
 
# De um repositório GitHub
claude plugin add github:username/repo-name
 
# De um diretório local (útil durante o desenvolvimento)
claude plugin add ./my-plugin

Após instalar alguns plugins, você vai querer acompanhá-los. O comando plugin cuida de listar, atualizar e remover:

# Listar todos os plugins instalados
claude plugin list
 
# Atualizar um plugin específico para a última versão
claude plugin update @anthropic/deploy-helper
 
# Atualizar todos os plugins
claude plugin update --all
 
# Remover um plugin
claude plugin remove @anthropic/deploy-helper

Uma decisão durante a instalação é o escopo. Plugins podem viver em dois lugares: no escopo de usuário, instalados em ~/.claude/plugins/ e válidos para todos os seus projetos; ou no escopo de projeto, instalados em .claude/plugins/ dentro de um repositório específico.

O padrão é o escopo de usuário. Para instalar um plugin apenas no 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á atrelada a uma base de código específica. 

Um plugin que conhece o processo de deploy da sua empresa deve ficar nesse projeto. Já um plugin que formata código de acordo com suas preferências pessoais fica melhor no nível do usuário. Quando um plugin existe nos dois escopos, a versão do projeto tem precedência, permitindo que times apliquem configurações específicas do repositório enquanto os desenvolvedores mantêm seus plugins pessoais ativos em outros lugares.

Como escolher o tipo certo de plugin do Claude Code

Os três tipos de componentes têm finalidades diferentes e consomem tokens da janela de contexto de formas distintas. Entender esses trade-offs ajuda você a escolher o melhor para cada tarefa.

Skills vs. servidores MCP: o trade-off de tokens

Servidores MCP pré-carregam todas as definições de ferramentas na sua janela de contexto no início da sessão. Cada ferramenta precisa de nome, descrição e todo o schema de parâmetros, o que normalmente consome de 100 a 300 tokens por ferramenta. Uma configuração com cinco servidores pode consumir aproximadamente 55.000 tokens antes mesmo de você digitar um caractere:

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

Uma análise encontrou setups com 7+ servidores consumindo mais de 67.000 tokens, o que representa um terço da sua janela de contexto de 200K antes da conversa começar.

Skills seguem outra abordagem, com divulgação progressiva. No início da sessão, o Claude vê apenas o nome e uma descrição de uma linha do frontmatter YAML de cada skill, cerca de 100 tokens por skill. 

As instruções completas só são carregadas quando o Claude determina que a skill é relevante para a tarefa atual. Arquivos de referência só carregam quando realmente necessários. E scripts nunca entram na janela de contexto: o Claude os executa externamente e apenas o output retorna.

A Anthropic abordou esse desequilíbrio no fim de 2025 com o Tool Search, um recurso que traz lazy loading para servidores MCP. 

Em vez de pré-carregar todas as definições das ferramentas, o Claude Code agora detecta quando as descrições consumiriam mais de 10% do contexto disponível e passa a carregar sob demanda. 

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

Veja como decidir entre eles.

Skills funcionam melhor quando você quer que o Claude tenha acesso a conhecimento ou fluxos que ele pode aplicar com julgamento. Uma skill que descreve o checklist de code review do seu time é carregada quando o Claude vai revisar código, mas ele ainda decide como aplicar cada item conforme o contexto. 

Skills também fazem sentido para operações que exigem scripts de computação pesada, já que o código do script fica fora da janela de contexto.

Servidores MCP são ideais quando o Claude precisa de dados em tempo real de serviços externos, como mensagens do Slack, PRs do GitHub ou consultas a banco de dados. Eles também são a melhor escolha quando vários agentes de IA precisam das mesmas ferramentas ou quando você precisa de recursos corporativos como trilhas de auditoria e permissões explícitas.

Muitas configurações combinam ambos: skills fornecem o "como" e o "quando" por meio de instruções em linguagem natural, enquanto servidores MCP fazem as chamadas reais às APIs.

Skills populares do Claude Code para instalar

• Superpowers (nosso tutorial): 20+ fluxos testados em produção para TDD, depuração e planejamento estruturado
• frontend-design: Instrui o Claude a evitar estética genérica e tomar decisões de design mais ousadas
• mcp-builder: Guia para criar servidores MCP e integrar APIs externas
•  webapp-testing: Testa aplicações web locais usando Playwright para verificação de UI
•  skill-creator: Ferramenta interativa que orienta você na criação de novas skills

Servidores MCP populares para conectar

• Context7: Busca de documentação em tempo real e por versão
• GitHub: Busca em repositórios, gestão de PRs, acompanhamento de issues
• Playwright: Automação de navegador usando árvores de acessibilidade em vez de screenshots
• Supabase: Consultas a banco com reconhecimento de Row Level Security
• Sentry: Rastreamento de erros e performance direto no seu editor

Você também pode ler nosso guia dos principais servidores MCP remotos.

Hooks: a camada determinística

Hooks ficam fora do debate entre skills e MCP. Enquanto skills e servidores MCP ficam do lado do Claude (ele decide quando usar), hooks ficam do lado do sistema. Eles disparam em eventos como PreToolUse ou PostToolUse, executando scripts shell antes ou depois de o Claude tomar ações específicas. O Claude não decide se um hook roda.

Isso torna os hooks a escolha certa quando algo precisa acontecer sem exceção: lint antes de todo commit, bloquear gravações em diretórios protegidos, registrar cada comando bash ou rodar testes antes de qualquer deploy.

Esta desenvolvedora recomenda hooks de "bloqueio na submissão" em vez de "bloqueio na escrita". Interromper o Claude no meio da tarefa confunde o agente e piora os resultados. O time dela usa um hook PreToolUse que envolve Bash(git commit) e verifica um arquivo temporário que só existe se os testes passaram. Sem arquivo, sem commit. O agente termina o trabalho e a validação acontece no fim.

Hooks não adicionam custo de tokens, já que rodam como scripts shell fora da janela de contexto.

Hooks úteis do Claude para configurar

• ESLint/Prettier na edição: Autoformatar arquivos depois que o Claude os escreve
• Gate de testes no commit: Bloquear commits a menos que os testes passem
• Caminhos protegidos: Impedir alterações em migrations, configs ou diretórios vendor
• Notificação ao concluir: Enviar alertas no Slack ou no desktop quando tarefas longas terminarem
• Backup de transcrição: Salvar o histórico da conversa antes do processo de compactação

Como criar seus próprios plugins do Claude Code

Quando uma skill vive no seu diretório pessoal .claude/, só você pode usá-la. Empacotá-la como um plugin permite compartilhá-la com o time ou reutilizá-la em vários projetos.

Vamos criar um plugin chamado session-logger que adiciona o comando /session-logger:summarize. Quando invocado, o Claude revisa a conversa e acrescenta um resumo estruturado ao arquivo SESSION_LOG.md.

Crie a estrutura do plugin

Plugins podem ficar em qualquer lugar do seu sistema de arquivos. Para este tutorial, vamos criar um no seu diretório home:

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

Isso cria:

~/session-logger/
├── .claude-plugin/
│   └── plugin.json  	# o manifesto fica aqui, e só aqui
└── skills/
	└── summarize/   	# o nome da pasta vira o nome do comando
    	└── SKILL.md 	# deve ter exatamente esse nome

Escreva o manifesto

Crie ~/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 deste plugin começarão com /session-logger:.

Escreva a skill

Crie ~/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 informa ao Claude que apenas você pode acionar essa skill. Sem essa flag, o Claude pode decidir executar o comando sozinho se achar que ajuda a conversa. Para um logger ou ferramenta de deploy, geralmente você quer controle manual.

Teste localmente

Navegue até qualquer projeto onde queira usar o plugin e inicie o Claude Code com a flag --plugin-dir apontando para o seu plugin:

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

Digite /session-logger:summarize para invocar o comando. Observe que comandos de plugin não aparecem nas sugestões de autocomplete até você digitar o nome completo. O texto fica azul quando o Claude Code reconhece como um comando válido.

Depois de fazer algum trabalho na sessão, execute o comando. O Claude revisa a conversa e acrescenta uma entrada no SESSION_LOG.md no diretório do seu projeto atual.

Compartilhe com outras pessoas

Faça push do seu plugin para o GitHub. Para distribuí-lo além da clonagem manual, adicione-o a um marketplace de plugins. O guia do marketplace explica como criar o seu próprio marketplace ou enviar para os já existentes.

Considerações finais

Plugins transformam o Claude Code de um assistente genérico em algo moldado para o seu fluxo de trabalho. O logger de sessão que criamos levou cerca de cinco minutos e três arquivos. A maioria dos plugins úteis não é muito mais complexa do que isso.

Se você acompanhou o passo a passo, agora tem um plugin funcional na sua máquina. Tente ajustá-lo: mude o formato do resumo, adicione novas seções ou troque por algo que o seu time realmente precise. A estrutura é a mesma, seja para uma ferramenta pessoal rápida ou algo que você vai distribuir para centenas de desenvolvedores.

Além disso, dê uma olhada nos repositórios da comunidade quando puder. Ver como outras pessoas estruturam seus plugins ensina padrões que a documentação não alcança.

Para ir mais fundo com o Claude Code, confira nossos tutoriais de boas práticas do Claude Code, o framework de skills Superpowers, slash commands para sessões longas e segurança e permissões. Se quiser aprender mais sobre os modelos Claude, recomendo o curso Introduction to Claude Models.