Como Usar Plugins no Claude Code

Claude Code direto da caixa já é impressionante. Ele lê seu código, edita arquivos, roda comandos e responde perguntas sobre o projeto. Mas chega um ponto onde você quer que ele faça as coisas do seu jeito.

Talvez você queira um comando /commit que segue as convenções do seu time. Ou um hook que impede commits sem testes. Ou um agente especializado que faz code review com os critérios da sua empresa.

É aí que entram os plugins.

Neste artigo, você vai entender o que são plugins, como instalar e usar os que já existem, e como criar o seu próprio do zero. Sem teoria desnecessária — tudo com exemplos reais.

O que são plugins

Um plugin do Claude Code é uma pasta com um arquivo de configuração e um conjunto de componentes que estendem o que o Claude pode fazer.

Pense assim: Claude Code é como um smartphone novo. Funciona bem de fábrica. Mas quando você instala apps — câmera melhor, editor de fotos, gerenciador de tarefas — ele se adapta ao seu estilo de vida. Plugins são os apps do Claude Code.

Na prática, um plugin é uma pasta com esta estrutura mínima:

meu-plugin/
├── .claude-plugin/
│   └── plugin.json          ← identidade do plugin
├── skills/                  ← comportamentos que Claude aprende
├── commands/                ← slash commands (/meu-comando)
├── hooks/                   ← scripts automáticos (antes/depois de ações)
└── agents/                  ← sub-agentes especializados

O plugin.json é o cartão de identidade. Ele diz ao Claude Code o nome do plugin, o que faz e quem criou:

{
  "name": "meu-plugin",
  "description": "Automações para meu workflow de desenvolvimento",
  "author": {
    "name": "Seu Nome"
  }
}

O resto são componentes opcionais. Um plugin pode ter só um comando. Ou só hooks. Ou uma combinação de tudo. Você monta conforme a necessidade.

Os componentes de um plugin

Cada tipo de componente resolve um problema diferente. Aqui está o que cada um faz:

Skills — ensinando comportamentos novos

Uma skill é um arquivo Markdown que ensina ao Claude como executar uma tarefa específica. Quando invocada, o conteúdo da skill é carregado no contexto da conversa — como se você tivesse colado instruções detalhadas.

Exemplo: uma skill de code review que define critérios específicos, checklists e formato de saída. Ao invocá-la, o Claude sabe exatamente como revisar código do jeito que você quer.

Skills são arquivos .md com um frontmatter YAML:

---
name: minha-skill
description: Use quando o usuário pedir para fazer X
---

# Instruções da Skill

Aqui vão as instruções detalhadas que o Claude
vai seguir quando esta skill for invocada.

O campo description é crítico — é ele que permite ao Claude decidir quando usar a skill automaticamente.

Commands — atalhos com slash

Commands são slash commands personalizados. Você digita /meu-comando e o Claude executa um workflow pré-definido.

A diferença entre command e skill: commands são invocados explicitamente pelo usuário (via /), enquanto skills podem ser ativadas automaticamente quando o Claude identifica que são relevantes.

Exemplos reais de commands:

Command	O que faz
`/commit`	Commit seguindo Conventional Commits
`/code-review`	Code review de um pull request
`/criar-pr`	Cria PR vinculado a uma issue

Commands também são arquivos Markdown com frontmatter:

---
description: Faz code review de um pull request
allowed-tools: Bash(gh *), Read, Grep, Glob
---

# Code Review

Instruções para o Claude executar o review...

O campo allowed-tools define quais ferramentas o command pode usar — um controle de segurança importante.

Hooks — automação invisível

Hooks são scripts que rodam automaticamente em resposta a eventos do Claude Code. Eles são invisíveis para o usuário — trabalham nos bastidores.

Os principais eventos:

Evento	Quando dispara
`PreToolUse`	Antes de executar qualquer ferramenta
`PostToolUse`	Depois que uma ferramenta termina
`UserPromptSubmit`	Quando o usuário envia uma mensagem
`Stop`	Quando o Claude termina uma resposta

Exemplo prático: um hook PreToolUse que verifica se um comando Bash é destrutivo (rm -rf, git push --force) e bloqueia a execução com um aviso.

Hooks são registrados em hooks/hooks.json e executados por scripts (Python, bash, Node.js):

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

A variável ${CLAUDE_PLUGIN_ROOT} aponta para a raiz do plugin — use sempre ela para caminhos relativos.

Agents — sub-agentes especializados

Agents são sub-processos autônomos que o Claude pode criar para tarefas complexas. Pense neles como assistentes do assistente.

Exemplo: um agente de code review que usa modelo Haiku (mais rápido e barato) para fazer uma primeira passada, e só escala para o modelo principal quando encontra problemas sérios.

MCP Servers — conexão com o mundo

Plugins podem incluir configurações de MCP (Model Context Protocol) servers, que conectam o Claude a ferramentas externas — bancos de dados, APIs, navegadores, serviços de busca.

Comparativo rápido

Componente	Ativação	Formato	Uso típico
Skill	Automática ou manual	Markdown	Ensinar comportamentos
Command	Manual (`/comando`)	Markdown	Workflows repetíveis
Hook	Automática (evento)	Script + JSON	Validação, segurança
Agent	Via Claude	Markdown	Tarefas complexas
MCP	Sempre ativo	JSON config	Ferramentas externas

Instalando e usando plugins

Existem dois caminhos para ter plugins no Claude Code: instalar de um marketplace ou adicionar manualmente.

Marketplaces

Marketplaces são repositórios no GitHub que contêm coleções de plugins. O principal é o oficial da Anthropic (anthropics/claude-plugins-official), mas qualquer pessoa pode criar o seu.

Para adicionar um marketplace:

/plugin marketplace add usuario/repositorio

Para instalar um plugin de um marketplace:

/plugin install nome-do-plugin

O Claude Code baixa o plugin, coloca em ~/.claude/plugins/cache/ e registra a instalação.

Escopo: user vs project

Ao instalar, você escolhe o escopo:

User (global): O plugin funciona em todos os projetos. Ideal para ferramentas genéricas como code review, git workflows, frontend design.
Project: O plugin funciona apenas naquele projeto. Ideal para plugins específicos de um time ou stack.

Plugins populares do marketplace oficial

Estes são plugins reais do marketplace anthropics/claude-plugins-official:

Plugin	O que faz	Escopo recomendado
code-review	Code review automatizado de PRs com scoring	User
hookify	Cria regras de validação sem código	User
frontend-design	Interfaces com design de alta qualidade	User
plugin-dev	Ferramentas para criar plugins	User
claude-md-management	Mantém CLAUDE.md organizado	User
context7	Busca docs atualizadas de qualquer lib	User
playwright	Automação de browser para testes	User
firecrawl	Web scraping e busca	Project
stripe	Integração com Stripe	Project

Usando plugins no dia a dia

Uma vez instalado, o plugin se integra naturalmente ao Claude Code:

Commands aparecem como slash commands. Digite / e você verá os comandos disponíveis. Exemplo:

> /code-review 42

Isso invoca o plugin code-review para revisar o PR #42.

Skills são ativadas automaticamente quando o Claude identifica que são relevantes. Se você tem a skill frontend-design instalada e pede "crie um componente de login", o Claude vai usar a skill automaticamente.

Hooks rodam em background. Você não precisa fazer nada — eles monitoram eventos e atuam quando necessário.

Criando seu primeiro plugin

Vamos criar um plugin real: um command /status que mostra um resumo do estado do projeto (git, testes, lint).

Passo 1: Criar a estrutura

Na raiz do seu projeto (ou em ~/.claude/plugins/ para escopo global):

mkdir -p meu-status-plugin/.claude-plugin
mkdir -p meu-status-plugin/commands

Passo 2: Criar o plugin.json

{
  "name": "project-status",
  "description": "Mostra um resumo rápido do estado do projeto",
  "version": "1.0.0",
  "author": {
    "name": "Seu Nome"
  }
}

Salve em meu-status-plugin/.claude-plugin/plugin.json.

Passo 3: Criar o command

O command é um arquivo Markdown em commands/:

---
description: Mostra resumo do estado do projeto (git, lint, testes)
allowed-tools: Bash(git *), Bash(pnpm *), Bash(npm *)
---

# Project Status

Gere um resumo conciso do estado atual do projeto:

1. **Git:** branch atual, commits pendentes, arquivos modificados
2. **Lint:** rode o linter e reporte erros (se configurado)
3. **Testes:** rode os testes e reporte resultados (se configurado)

Formato de saída:

## Status do Projeto

- **Branch:** main (2 commits à frente de origin)
- **Modificados:** 3 arquivos
- **Lint:** 0 erros, 2 warnings
- **Testes:** 14/14 passando

Se alguma ferramenta não estiver configurada, mencione isso
em vez de falhar silenciosamente.

Salve como meu-status-plugin/commands/status.md.

Passo 4: Testar

Para plugins locais (de projeto), basta colocar a pasta no diretório do projeto. O Claude Code detecta a pasta .claude-plugin/plugin.json automaticamente.

Abra o Claude Code no projeto e digite:

> /status

O Claude vai ler o command, executar os passos descritos e apresentar o resumo.

Estrutura final

meu-status-plugin/
├── .claude-plugin/
│   └── plugin.json
└── commands/
    └── status.md

Três arquivos. Um plugin funcional.

Hooks: automatizando comportamentos

Hooks são onde plugins ficam realmente poderosos. Enquanto commands e skills esperam sua ação, hooks agem sozinhos.

Anatomia de um hook

Um hook precisa de duas coisas:

Registro em hooks/hooks.json — diz ao Claude Code quando rodar
Script que executa a lógica — recebe JSON via stdin, retorna JSON via stdout

Exemplo: bloqueando comandos perigosos

Vamos criar um hook que impede a execução de comandos destrutivos como rm -rf / ou git push --force no main.

hooks/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/guard.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

hooks/guard.py:

#!/usr/bin/env python3
"""Bloqueia comandos destrutivos antes da execução."""

import json
import sys
import re

DANGEROUS_PATTERNS = [
    r'rm\s+-rf\s+/',
    r'git\s+push\s+.*--force.*\s+main',
    r'git\s+reset\s+--hard',
    r'drop\s+database',
]

def main():
    input_data = json.load(sys.stdin)
    tool_name = input_data.get('tool_name', '')

    if tool_name != 'Bash':
        print(json.dumps({}))
        sys.exit(0)

    command = input_data.get('tool_input', {}).get('command', '')

    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            result = {
                "decision": "block",
                "reason": f"Comando bloqueado por segurança: {command}"
            }
            print(json.dumps(result))
            sys.exit(0)

    print(json.dumps({}))
    sys.exit(0)

if __name__ == '__main__':
    main()

Como funciona

O usuário (ou o Claude) tenta executar um comando Bash
Antes da execução, o Claude Code chama guard.py
O script recebe os detalhes do comando via stdin (JSON)
Se o comando bate com um padrão perigoso, retorna "decision": "block" — e o comando não executa
Se o comando é seguro, retorna {} — e a execução prossegue normalmente

O hook sempre sai com sys.exit(0). Se o hook crashar, o Claude Code segue em frente — nunca trava por causa de um hook com erro.

Sem código: hookify

Se você não quer escrever Python, o plugin hookify permite criar regras de hook usando apenas Markdown. Você descreve a regra em linguagem natural e o hookify cuida da execução.

Próximos passos

Plugins transformam o Claude Code de uma ferramenta genérica em sua ferramenta. Comece simples:

Instale 2-3 plugins do marketplace oficial e use por uma semana
Crie um command para um workflow que você repete todo dia
Adicione um hook para algo que te irrita (ex: commits sem mensagem descritiva)

A documentação oficial dos plugins está em constante evolução. Os melhores exemplos são os plugins do marketplace oficial — leia o código deles.

E se você quer ir além — criar plugins completos com agents, MCP servers e lógica avançada — o Curso Claude Code: Criador de Apps cobre isso em profundidade, com projetos reais e acompanhamento passo a passo.

Referências

Discover and install prebuilt plugins through marketplaces — Documentação oficial sobre instalação e gerenciamento de plugins
Plugins reference — Referência técnica completa da arquitetura de plugins
Create and distribute a plugin marketplace — Como criar e distribuir seu próprio marketplace
Hooks reference — Referência completa de hooks: eventos, configuração e formatos de entrada/saída
anthropics/claude-plugins-official — Marketplace oficial da Anthropic no GitHub
Plugins — Claude Code Docs — Guia para criar skills, agents e hooks

Como Usar Plugins no Claude Code: Do Básico à Criação do Seu Próprio

#Como Usar Plugins no Claude Code

#O que são plugins

#Os componentes de um plugin

#Skills — ensinando comportamentos novos

#Commands — atalhos com slash

#Hooks — automação invisível

#Agents — sub-agentes especializados

#MCP Servers — conexão com o mundo

#Comparativo rápido

#Instalando e usando plugins

#Marketplaces

#Escopo: user vs project

#Plugins populares do marketplace oficial

#Usando plugins no dia a dia

#Criando seu primeiro plugin

#Passo 1: Criar a estrutura

#Passo 2: Criar o plugin.json

#Passo 3: Criar o command

#Passo 4: Testar

#Estrutura final

#Hooks: automatizando comportamentos

#Anatomia de um hook

#Exemplo: bloqueando comandos perigosos

#Como funciona

#Sem código: hookify

#Próximos passos

#Referências