Quais tipos de sistema existem para o Claude Code? O mapa entre skill, agente, comando, hook e plugin

Fala aí, beleza? Existe uma bagunça de vocabulário rolando nas comunidades, e ela atrapalha antes mesmo de você instalar qualquer coisa

A mesma pessoa chama de "agente" o que é skill, de "comando" o que virou skill, e de "framework" o que é plugin

A boa notícia é que a documentação oficial trata as formas de estender o Claude Code como um conjunto definido de categorias: CLAUDE.md, skills, subagentes, hooks, MCP e plugins

E isso não é lista decorativa, cada uma dessas peças pluga em um ponto DIFERENTE do loop do agente

É mais ou menos como aprender a diferença entre variável de ambiente, arquivo de config e script de build: são três coisas que "configuram" seu projeto, mas ninguém troca uma pela outra depois que entende onde cada uma age

Neste post eu mapeio os sistemas do Claude Code peça por peça: o que cada uma faz, onde ela mora no seu sistema de arquivos, quem dispara ela e em que momento ela entra

Bora? 😀

O mapa em uma tabela: onde cada peça vive e quem dispara

Antes de descer no detalhe, o resumão

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Se você olhar a coluna "quem dispara", já mata metade da confusão

Peça que depende do modelo querer usar é uma coisa

Peça que roda porque um evento aconteceu é outra bem diferente

CLAUDE.md: o contexto que entra em toda sessão

Essa é a peça mais simples de todas, e por isso é a primeira que você deveria configurar

O CLAUDE.md é contexto persistente: ele entra sozinho, sem você precisar chamar

E é ADITIVO entre níveis: os arquivos do diretório de trabalho para cima carregam no lançamento, e os de subdiretórios carregam conforme você trabalha neles

Então dá pra ter uma regra geral na raiz do projeto e regras mais específicas dentro de uma pasta que só valem quando o Claude está mexendo ali

Quando o CLAUDE.md é a peça certa:

Quando é coisa que vale SEMPRE

Convenção de nomes, stack do projeto, o que nunca pode ser mexido, como rodar os testes, o padrão de commit

E quando não é:

Se o comportamento só faz sentido em uma tarefa específica, isso é skill, não CLAUDE.md

Se o comportamento precisa acontecer de forma garantida, não "quando o modelo lembrar", isso é hook

Tome cuidado com o instinto de jogar TUDO no CLAUDE.md: ele é o balde fácil, e é exatamente por isso que ele vira depósito

Skill: a pasta com SKILL.md que absorveu os comandos customizados

Skill é uma pasta com um arquivo SKILL.md dentro

O SKILL.md é o único arquivo obrigatório

Arquivos de apoio (scripts, referências) são opcionais, você põe se precisar

A estrutura fica assim:

~/.claude/skills/<nome>/SKILL.md   (pessoal, vale em qualquer projeto seu)
.claude/skills/<nome>/SKILL.md     (do projeto, vive no repositório)

Os dois modos de disparo:

Aqui está o detalhe que mais confunde gente nova

Uma skill pode ser chamada por VOCÊ, com /<nome>

Ou pode ser carregada pelo PRÓPRIO Claude, de forma autônoma, quando a descrição dela bate com a tarefa que você pediu

Quem controla isso é o frontmatter da skill

Ou seja: a descrição que você escreve não é enfeite, é ela que decide se a skill entra sozinha ou fica dormindo

Se você quer ver isso aplicado num caso concreto, eu já destrinchei o assunto no post sobre skill de design responsivo no Claude Code, que é justamente um caso onde a regra precisa ser seguida com precisão

E os comandos customizados? 🤔

Essa é a parte que quebra a cabeça de quem chegou pelo vocabulário antigo

Os comandos customizados foram FUNDIDOS nas skills

O diretório .claude/commands/ é formato legado e continua funcionando, mas o formato recomendado hoje é .claude/skills/<nome>/SKILL.md

Na prática, os dois criam a mesma coisa:

.claude/commands/deploy.md          -> cria /deploy  (legado)
.claude/skills/deploy/SKILL.md      -> cria /deploy  (recomendado)

Então quando alguém falar "criei um comando", provavelmente ele criou uma skill, ou está usando o formato antigo sem saber

Essa distinção entre skills, comandos e subagentes é onde a maior parte da confusão de vocabulário nasce

Subagente: contexto isolado dentro da mesma sessão

Subagente é um arquivo markdown com frontmatter YAML

O Claude Code observa duas pastas pra carregar eles: ~/.claude/agents/ (usuário) e .claude/agents/ (projeto)

No frontmatter, só name e description são obrigatórios

E o corpo do arquivo vira o system prompt do subagente

---
name: revisor
description: revisa mudanças de código procurando bug de lógica
---

Você revisa o diff atual e aponta apenas problemas de correção.

O que ele resolve de verdade:

O subagente roda com contexto PRÓPRIO, sem a conversa do pai, e reporta de volta ao agente principal

Isso serve pra três coisas: isolar contexto, rodar análises em paralelo e aplicar instruções especializadas

É o critério mais útil pra decidir entre skill e subagente

Se a tarefa é suja de contexto (varrer arquivo demais, ler log gigante) e você não quer isso entupindo a sua conversa principal, é subagente

Se é uma instrução de COMO fazer uma tarefa dentro da sua conversa, é skill

Nota operacional sobre o /agents:

A partir da v2.1.198 o comando /agents deixou de abrir painel, e passou a apenas imprimir um aviso apontando onde ficam os arquivos de subagente

Criação e edição são feitas nos arquivos, ou pedindo pro próprio Claude criar

Caso você tenha visto um tutorial mostrando o painel e não encontre ele aí, é isso

E os agent teams, é a mesma coisa?

Não, e essa confusão é comum

Agent teams são experimentais e vêm DESLIGADOS por padrão no Claude Code

Pra habilitar, define CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 no settings.json ou no ambiente

A diferença de conceito é grande: agent teams coordenam VÁRIAS instâncias do Claude Code

Uma sessão é o lead, que distribui e sintetiza

Os teammates têm cada um a sua janela de contexto, compartilham lista de tarefas e conversam entre si

Já o subagente roda dentro de uma sessão e só reporta ao agente principal

Um é time, o outro é auxiliar 😀

Hook: o que roda sem depender da vontade do modelo

Aqui mora a peça mais mal compreendida do conjunto

Hook é um handler que executa automaticamente em um ponto fixo do ciclo de vida do Claude Code

De forma DETERMINÍSTICA, não a critério do modelo

Ele dispara em pontos fixos: antes de uma ferramenta rodar, depois de uma edição, no início da sessão

Onde configura:

Na chave hooks do settings.json

Pode ser escopo de projeto, em .claude/settings.json, ou de usuário, em ~/.claude/settings.json

Os eventos:

Existem eventos de hook pra diferentes momentos do ciclo de vida

Entre eles:

• PreToolUse: antes da ferramenta rodar, podendo NEGAR a chamada
• PostToolUse: depois do resultado
• SessionStart
• UserPromptSubmit
• Stop
• SubagentStop
• PreCompact

E o handler não precisa ser script shell: pode ser comando shell, endpoint HTTP, ferramenta MCP, prompt de LLM ou até um subagente

Quando o hook é a peça certa:

Quando "às vezes o Claude esquece" NÃO é aceitável

Rodar o formatter depois de toda edição, bloquear uma ferramenta perigosa antes dela executar, injetar algo no começo de toda sessão

Se a regra é crítica e você escreveu ela numa skill, você escolheu a peça errada, porque skill depende de invocação

MCP: a ponte para dados e ferramentas de fora

MCP é um padrão aberto pra conectar o Claude Code a dados e ferramentas externas

Com ele dá pra ler documentos no Google Drive, atualizar tickets no Jira, puxar dados do Slack ou usar ferramentas próprias

Ele não ensina o Claude a trabalhar melhor, ele dá ACESSO ao que estava fora do alcance

Como registra e os três escopos:

O registro é por comando, com claude mcp add

Por padrão ele registra em escopo local, que é privado e vale só no projeto atual

Com --scope user, ele grava na chave mcpServers de ~/.claude.json

E o escopo de projeto usa o arquivo .mcp.json na raiz, que é o caminho quando você quer o servidor versionado junto com o repositório

Quando o MCP é a peça certa:

Quando o problema é falta de ACESSO, não falta de instrução

Se o Claude está errando porque não sabe COMO você quer que ele faça, MCP não resolve nada

Se ele está errando porque o dado está num sistema que ele não alcança, aí sim

Plugin: a embalagem que junta skill, hook, subagente e MCP

Plugin não é uma sétima categoria de comportamento, ele é a camada de EMPACOTAMENTO

Ele junta skills, hooks, subagentes e servidores MCP numa unidade instalável

Pra vários plugins coexistirem sem pisar no pé um do outro, as skills vindas de plugin ficam com namespace no formato plugin-name:skill-name

O manifesto é opcional:

O manifesto do plugin fica em .claude-plugin/plugin.json, e ele é opcional

Se o plugin.json for omitido, o Claude Code descobre os componentes nos locais padrão

O manifesto serve pra metadados ou pra caminhos customizados

Como instala, passo a passo:

1. Adicione o marketplace, que é a fonte de onde os plugins vêm:

/plugin marketplace add <owner/repo>

2. Instale o plugin daquele marketplace:

/plugin install <nome-do-plugin>@<marketplace>

3. Se o resumo da instalação pedir, rode o reload pra ativar

/reload-plugins

O erro comum deste passo: instalar, mandar o prompt seguinte e achar que o plugin não funciona

Enquanto os plugins não são recarregados (ou a sessão reiniciada), a coisa simplesmente não entra em ação

A própria documentação cita um marketplace da comunidade como exemplo:

/plugin marketplace add anthropics/claude-plugins-community

Depois de adicionado, ele passa a ser referenciado como claude-community na hora de instalar

E o tal do framework? SuperClaude, BMAD e o vocabulário da comunidade

Agora a parte que dá nó na cabeça de muita gente

"Framework" NÃO aparece como categoria de extensão na documentação oficial do Claude Code

A página oficial de extensões lista CLAUDE.md, skills, subagentes, hooks, MCP e plugins, ponto

Framework é vocabulário da comunidade pra bundles opinativos montados com essas MESMAS peças

Ou seja: quando alguém te vende um "framework", pergunta o que tem dentro, porque a resposta sempre vai ser alguma combinação de skill, hook, subagente e MCP

Dois exemplos verificáveis:

O SuperClaude Framework é um projeto de terceiros mantido na organização SuperClaude-Org no GitHub, e se descreve como framework de configuração que estende o Claude Code

O BMAD-METHOD tem repositório oficial próprio, com autoria atribuída a Brian (BMad) Madison no package.json

Aqui vale um alerta: os pacotes que levam o BMAD para o Claude Code são PORTS feitos pela comunidade

Adaptações como PabloLION/bmad-plugin são repositórios separados, não o oficial

Já me confundi com isso, e é fácil sair citando um port achando que é o projeto original

E os output styles, entram onde?

Eles entram numa gaveta própria: output styles mudam COMO o Claude responde, não o que ele sabe

Eles modificam o system prompt pra definir papel, tom e formato de saída

Se o seu problema é o Claude não conhecer o projeto, output style não vai resolver

Se o problema é ele responder num formato que não te serve, aí é a peça certa

Na prática: por que a skill é a peça que mais muda o dia a dia

De todas essas categorias, a skill é a que mais mexe no seu dia a dia, e eu vi isso na pele

No vídeo abaixo eu instalo uma skill (a do arquivo que me fez parar de brigar com o Claude Code) e testo em um projeto meu de gestão de produtos, um CRUD com tabela e filtro

Instalei pelo caminho de plugin: adicionei o marketplace, depois adicionei o plugin, e deixei valendo só no projeto atual em vez de global, pra testar antes de espalhar pra tudo

E aí bati de frente com o erro que citei lá em cima: depois de instalar, é preciso recarregar os plugins ou reiniciar a sessão, senão a skill simplesmente não entra em ação no prompt seguinte

A prova de que estava tudo ativo foi a própria sessão mostrando as skills sendo carregadas antes da execução

O que mudou de fato:

Pedi um botão de exportar CSV que exportasse SÓ os produtos visíveis (respeitando o filtro)

Nesse pedido a IA não fez pergunta nenhuma e foi direto pra execução, porque a tarefa era simples e o prompt já era específico

Mas ela seguiu as demais etapas da skill: no final veio um relatório do que foi alterado e uma verificação declarada de que as colunas exportadas batiam com as colunas visíveis da tabela

Cliquei no botão, abri o CSV gerado no editor e o conteúdo correspondia aos produtos que eu queria

Depois forcei um segundo teste com um pedido propositalmente VAGO: adicionar um sistema de autenticação

Aí ela parou antes de codar pra alinhar as escolhas comigo, dizendo que autenticação tem várias formas e que a decisão muda o escopo

Eu já tinha testado antes de gravar e já sabia que esse comportamento varia conforme a tarefa: pedido claro segue direto, pedido ambíguo dispara as perguntas

Por que isso importa pro mapa:

Esse é exatamente o caso onde escrever a instrução no SKILL.md bate repetir a mesma coisa no chat toda vez

Porque o problema que motiva esse tipo de skill é conhecido: sem orientação a IA até entrega o resultado, mas mexe em arquivos demais, cria código além do necessário, altera o que não precisava e não testa antes de dizer que está pronto

Eu vejo valor real em a IA PERGUNTAR antes de assumir

Os modelos já começaram a fazer isso sozinhos, mas muitas vezes ainda é preciso pedir explicitamente

E tem o lado prático: economizar interações por meio de prompts melhores também economiza tokens e chega mais rápido no resultado

Onde ainda frustra? No fato de o disparo autônomo depender da descrição do frontmatter casar com a tarefa

É o preço de a skill ser uma peça de invocação, não de evento

No vídeo você vê a instalação inteira, o recarregamento dos plugins, os dois testes (o pedido específico e o pedido vago) e o CSV aberto no editor pra conferir o resultado

As confusões mais comuns entre skill, agente, hook e plugin

Agora que as peças estão no lugar, se liga nos quatro tropeços clássicos

1. Criou uma skill pra algo que precisa rodar sempre, e o Claude às vezes ignora

Causa: skill depende de invocação, seja sua com /<nome>, seja do modelo pela descrição

Se o modelo não achou que era o caso, a skill não entra, e isso não é bug

Solução: move a regra pra um hook, num evento fixo do ciclo de vida

Como prevenir: antes de escrever, pergunta "isso pode falhar uma vez em dez?"

Se a resposta for não, é hook

2. Chama de "agente" o que é skill

Causa: mistura entre o /<nome> que dispara uma skill e o subagente, que é outra coisa

Como os dois "fazem uma tarefa especializada", o nome escorrega

Solução: use o critério do contexto isolado

Subagente roda com contexto próprio, sem a conversa do pai, e reporta de volta

Skill roda dentro da SUA conversa

Como prevenir: olha a pasta

.claude/agents/ é subagente, .claude/skills/ é skill, sem meio termo

3. Instalou um "framework" esperando uma categoria oficial

Causa: framework é vocabulário da comunidade, não categoria de extensão da documentação

É um bundle opinativo montado com as mesmas peças que você já conhece

Solução: abre o repositório e olha QUAIS skills, hooks e subagentes ele traz

Como prevenir: confere também se o que você está instalando é o repositório oficial ou um port da comunidade, porque nem sempre é o mesmo projeto

4. Ainda escreve em .claude/commands/

Causa: formato legado, que continua funcionando

E justamente por continuar funcionando ninguém percebe que mudou

Solução: migra pra .claude/skills/<nome>/SKILL.md, que é o formato recomendado

Como prevenir: lembra que os dois criam o mesmo /deploy, então o teste "funciona?" não te diz qual formato você está usando 😛

Conclusão: por onde começar agora que o vocabulário está no lugar

Recapitulando a lógica de escolha, uma frase por peça:

• CLAUDE.md quando a regra vale sempre
• Skill quando é o COMO de um tipo de tarefa
• Subagente quando você quer contexto isolado e análise em paralelo
• Hook quando não pode falhar nunca
• MCP quando falta acesso, não instrução
• Plugin quando você quer distribuir tudo isso junto

E o próximo passo concreto é bem chato de tão simples: começa pelo CLAUDE.md do projeto

Depois escreve a sua primeira skill em .claude/skills/<nome>/SKILL.md, com uma descrição decente no frontmatter

Só DEPOIS disso você avalia hooks, MCP e plugins, que são as camadas onde a coisa fica mais séria

Começar por plugin de terceiros antes de entender as peças é o caminho mais rápido pra ter um monte de coisa ligada sem saber o que faz o quê

Dá uma olhada no vídeo pra ver uma skill funcionando de ponta a ponta, e me conta aí qual peça você já usa no seu setup

Tem muito conteúdo sobre esses sistemas vindo por aí…

Até o próximo post! 😀