Skills vs Subagents vs Hooks vs MCP: o guia de decisão do Claude Code (2026)

Se você usa o Claude Code há mais de uma semana, provavelmente já bateu nesta parede: você quer estendê-lo, abre a documentação e encontra quatro mecanismos diferentes que soam todos como "adicionar capacidade ao Claude" - Skills, Subagents, Hooks e o Model Context Protocol (MCP). Eles se sobrepõem só o suficiente para confundir, e ninguém te diz qual escolher. Eu construí e coloquei os quatro em produção em projetos reais, então este é o guia de decisão que eu queria que existisse. Se você está começando agora, comece por o que é o Claude Code primeiro e depois volte aqui.

Skills, Subagents, Hooks e MCP num relance

Aqui está a tabela de decisão. Cada uma dessas quatro primitivas vive no seu diretório .claude (ou em settings.json), e cada uma responde a uma pergunta diferente de extensibilidade. Passe o olho pelas colunas que importam para você: o que ela acrescenta, o que a dispara, se ela ganha a própria janela de contexto, se é determinística e onde você a configura.

A distinção mais nítida desta tabela: só os Hooks são determinísticos e só os Subagents ganham a própria janela de contexto. Guarde esses dois fatos e metade da confusão desaparece.

O que é uma Skill no Claude Code?

Uma Skill é uma pasta com um arquivo SKILL.md que guarda instruções, checklists ou conhecimento de domínio que o Claude carrega só quando é relevante. O mecanismo se chama divulgação progressiva: o Claude lê uma breve descrição de cada skill na inicialização, mas não puxa o corpo inteiro para o contexto até decidir que a skill se aplica à tarefa em questão. Isso significa que uma skill quase não custa tokens até realmente ser acionada. As Skills podem ser invocadas automaticamente pelo modelo ou disparadas à mão com /skill-name.

.claude/skills/
└── pr-review/
 └── SKILL.md # instructions Claude loads when reviewing a PR

Correção de informação para 2026: os comandos de barra personalizados agora foram fundidos nas skills. Um antigo .claude/commands/deploy.md é, na prática, a mesma ideia de .claude/skills/deploy/SKILL.md - muitos posts mais antigos ainda tratam os "commands" como uma quinta primitiva separada, mas a documentação oficial do Claude Code (verificada em 08/2026) os incorpora às skills. Ou seja, são quatro primitivas para considerar, não cinco.

Recorra a uma Skill quando quiser padronizar conhecimento ou um procedimento repetível - uma convenção de código, um checklist de revisão, um estilo da casa para mensagens de commit. Para um passo a passo completo, veja as skills do Claude Code explicadas a fundo. A limitação honesta: uma skill é instrução, não código nem ferramenta. Sozinha, ela não alcança nada fora do Claude Code - é para isso que existe o MCP.

O que é um Subagent?

Um Subagent é um assistente especializado com a própria janela de contexto, o próprio prompt de sistema, a própria lista de ferramentas permitidas e as próprias permissões. Quando o Claude encontra uma tarefa que combina com a descrição de um subagent, ele delega: o subagent trabalha de forma independente na sua janela isolada e devolve apenas um resumo à conversa principal. Como é isolado, o trabalho intermediário barulhento - logs, despejos de arquivos, becos sem saída - nunca polui o seu contexto principal. Os Subagents também podem rodar em modelos mais baratos (por exemplo, o Haiku) para manter o trabalho delegado em conta.

.claude/agents/
└── code-reviewer.md # name, description, tools, model, system prompt

A melhor pista para um subagent: uma tarefa paralela inundaria o seu contexto principal. Uma pesquisa profunda por dezenas de arquivos, uma análise longa de logs, uma refatoração autocontida - qualquer coisa em que você só se importa com a conclusão, não com a bagunça. Aprenda a encadear vários deles em um fluxo de trabalho real de dev com IA usando o AgentKit.

O antipadrão honesto: usar subagents demais queima tokens. Cada delegação sobe um contexto novo e reestabelece o estado, então embrulhar uma tarefa de duas linhas em um subagent é puro overhead. Use-os quando o isolamento se pagar.

Uma nuance que vale separar: algumas ferramentas de aconselhamento rodam em linha, como uma única chamada de ferramenta, e não como um subagent isolado - veja como a ferramenta advisor difere de um subagent (advisor vs kongming).

O que é um Hook?

Um Hook é um comando de shell determinístico que dispara em um evento do ciclo de vida, configurado em settings.json. Diferente das outras três primitivas, um hook é código, não um prompt - ele roda independentemente do que o modelo decide. Eventos comuns incluem PreToolUse (antes de o Claude rodar uma ferramenta), PostToolUse (depois) e Stop (quando um turno termina). Isso faz do hook a ferramenta certa para proteções: formatar e passar o lint a cada edição, bloquear um comando arriscado, procurar segredos antes de um commit ou disparar uma notificação na área de trabalho quando uma tarefa longa termina.

// settings.json
{
 "hooks": {
 "PostToolUse": [
 { "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": "npm run format" }] }
 ]
 }
}

O contraste-chave com todo o resto desta página: um hook não pede permissão ao modelo. Se o evento combina, ele roda - toda santa vez. É justamente esse determinismo que faz você usá-lo para coisas que nunca podem ser puladas. Veja o mergulho profundo em fundamentos do Claude Code se eventos do ciclo de vida forem novidade para você. O antipadrão honesto: hooks que bloqueiam de forma agressiva demais vão brigar com você em trabalho legítimo, então mantenha seus matchers bem enxutos.

O que é o MCP (Model Context Protocol)?

O MCP (o Model Context Protocol) é um padrão aberto que conecta o Claude Code a ferramentas e fontes de dados externas por meio de servidores MCP. Um servidor expõe um conjunto de ferramentas - ler um PR do GitHub, consultar um banco Postgres, controlar um navegador, acessar uma API interna - e o Claude chama essas ferramentas do mesmo jeito que chama as nativas. O MCP é o que padroniza a integração de ferramentas, para você não escrever uma ponte sob medida para cada serviço. Os servidores são declarados em .mcp.json.

// .mcp.json
{
 "mcpServers": {
 "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
 }
}

A melhor pista para o MCP: você precisa que o Claude alcance um sistema que ele não controla - seu banco de dados, seu rastreador de issues, uma API ao vivo. Se você se pega copiando e colando dados no chat para o Claude poder agir sobre eles, esse trabalho é de um servidor MCP. O antipadrão honesto: recorrer ao MCP quando uma Skill simples resolveria. Se você só precisa que o Claude saiba uma convenção, isso é uma skill; o MCP é para quando ele precisa fazer algo em um sistema externo.

As diferenças de verdade (comparativo lado a lado)

As definições são fáceis; a confusão mora nas sobreposições. Aqui está o comparativo nos eixos que realmente separam os quatro.

Skill vs MCP é a confusão mais comum. Uma skill acrescenta instruções - muda o que o Claude sabe e como ele se comporta. O MCP acrescenta capacidade - deixa o Claude tocar um sistema que, de outro modo, ele não alcança. "Siga nosso checklist de PR" é uma skill; "leia o PR de verdade no GitHub" é MCP. Eles trabalham juntos com frequência.

Skill vs Subagent é a segunda armadilha. Os dois parecem "dar uma especialidade ao Claude", mas uma skill é conhecimento em contexto que o próprio modelo principal aplica, enquanto um subagent é um trabalhador fora de contexto que sai e faz o serviço isolado. Se você quer que a thread principal se comporte de um jeito, use uma skill. Se você quer descarregar uma tarefa para ela não bagunçar sua janela, use um subagent.

Cola de onde configurar cada coisa, tudo num lugar: as skills ficam em .claude/skills/, os subagents em .claude/agents/, os hooks em settings.json e os servidores MCP em .mcp.json. Quatro primitivas, quatro casas.

Quando usar qual? (decisão por objetivo)

Pule a teoria - comece pelo que você está tentando fazer. Aqui vão frases reais de uma linha mapeadas para a primitiva certa:

• Quero padronizar um procedimento repetível (checklist de revisão, estilo de commit) → Skill
• Quero manter uma tarefa cheia de pesquisa ou de logs fora do meu contexto principal → Subagent
• Quero forçar formatação, testes ou varredura de segredos toda santa vez → Hook
• Quero que o Claude consulte meu banco de dados, abra um PR ou acesse uma API → MCP
• Quero uma convenção da casa que o Claude sempre siga → Skill
• Quero uma refatoração grande feita sem assistir ao barulho do meio do caminho → Subagent
• Quero bloquear um comando perigoso antes que ele rode → Hook

Repare no padrão: conhecimento e comportamento pendem para as Skills, isolamento pende para os Subagents, imposição inegociável é sempre Hook, e qualquer coisa que cruze a fronteira do seu app é MCP.

Dá para usar os quatro juntos? (sim - e você deveria)

Essas primitivas se compõem; elas não competem. Uma configuração madura do Claude Code usa as quatro de uma vez, cada uma fazendo a única coisa em que é melhor. Aqui vai um exemplo concreto de ponta a ponta de um fluxo de revisão de código:

1. Uma Skill define o seu procedimento de revisão - o que checar, em que ordem, e os padrões do seu time.
2. O Claude delega a revisão de fato a um Subagent, então a análise arquivo por arquivo roda no próprio contexto e só o veredito volta.
3. Esse subagent usa um servidor MCP do GitHub para ler o pull request de verdade - diffs, comentários, status de CI.
4. Um Hook bloqueia o commit de forma determinística se os testes falharem, não importa o que o modelo concluiu.

É esse o ponto: uma skill, um subagent, um servidor MCP e um hook, cada um cobrindo uma lacuna que os outros não cobrem. Montar tudo isso na mão é trabalho de verdade - você escreve arquivos de skill, redige prompts de subagent, conecta servidores MCP e testa hooks. Se você prefere não construir cada peça do zero, kits selecionados já entregam essas primitivas prontas; o AgentKit para o Claude Code (20% de desconto pelo link) é o que eu indico para as pessoas. Falo mais dele a seguir.

Pule a configuração - tenha os quatro prontos com o AgentKit

Um esclarecimento rápido, porque o nome se confunde: este é o AgentKit para o Claude Code em agentkit.best (CLI ak) - não o AgentKit da OpenAI (Agent Builder / ChatKit). Produto completamente diferente.

Leia minha opinião completa e honesta na resenha do AgentKit antes de decidir, ou compare com outras opções em AgentKit vs as alternativas.

Perguntas frequentes

Skill ou subagent - qual para uma tarefa repetível?

Use uma Skill. Um procedimento repetível (um checklist de revisão, um estilo de mensagem de commit) é conhecimento que o modelo principal aplica em contexto. Só recorra a um subagent quando a tarefa for pesada o bastante a ponto de você querer isolá-la na própria janela de contexto para não bagunçar a conversa principal.

O MCP substitui as skills?

Não. Eles resolvem problemas diferentes. Uma Skill acrescenta instruções e conhecimento; o MCP acrescenta a capacidade de alcançar ferramentas e dados externos, como um banco de dados ou o GitHub. Se o Claude só precisa saber algo, use uma skill. Se ele precisa fazer algo em um sistema externo, use o MCP. Eles costumam trabalhar juntos.

Hooks são IA ou só scripts?

Só scripts. Um hook é um comando de shell determinístico que dispara em um evento do ciclo de vida, como PreToolUse ou Stop. Ele roda independentemente do julgamento do modelo, e é exatamente por isso que é a escolha certa para proteções como formatação automática, imposição de testes ou varredura de segredos.

Subagents custam mais tokens?

Podem custar. Cada subagent sobe o próprio contexto e reestabelece o estado, então tarefas triviais embrulhadas em um subagent são puro overhead. O lado bom é que manter o trabalho pesado fora do contexto principal pode economizar tokens no geral. Você também pode rodar subagents em modelos mais baratos para controlar o custo.

Os comandos de barra viraram skills?

Sim. A partir de 2026, os comandos de barra personalizados foram fundidos nas skills - um antigo .claude/commands/x.md é o mesmo conceito de um SKILL.md. Trate os comandos como uma forma de invocar uma skill pelo nome, não como uma quinta primitiva separada.

Preciso dos quatro?

Não para começar. A maioria das pessoas começa com um ou dois e adiciona o resto conforme as necessidades aparecem. Uma configuração completa, porém, usa os quatro, e se você quer tudo pronto, um kit selecionado como o AgentKit entrega skills, subagents e integrações MCP já construídos, para você só conectar os hooks por conta própria.

Conclusão + próximos passos

A regra prática vale a pena decorar: para acrescentar conhecimento → Skill; para acrescentar uma ferramenta ou fonte de dados → MCP; para isolar um trabalho pesado → Subagent; para impor algo de forma determinística → Hook. Lembre dos dois pilares - só os Hooks são determinísticos, só os Subagents ganham a própria janela de contexto - e você vai escolher a primitiva certa toda vez. Daqui, aprofunde nas skills do Claude Code ou, se preferir partir de uma base pronta, pegue o kit (20% de desconto pelo link) e leia primeiro a resenha honesta do AgentKit.