Skills vs subagentes vs comandos: qual usar para cada coisa

Uma das três deixou de existir como categoria separada. Comando personalizado virou skill, e a documentação de comandos aponta direto para a de skills. Um arquivo em .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy e funcionam igual.

Sobra uma escolha de verdade, e ela é maior que duas opções: skill, subagente, hook ou CLAUDE.md. Quatro perguntas resolvem quase todo caso.

Antes das tabelas, o caminho curto. Responda na ordem e pare na primeira que der "sim".

1. Precisa acontecer sempre, sem depender de o modelo concordar? É hook. Ele dispara no evento do ciclo de vida, independentemente do que o agente decidir.

2. Vai ler muito arquivo ou gerar saída que você não vai reler? É subagente. O trabalho acontece num contexto separado e só o resumo volta.

3. Vale para toda tarefa do projeto, o tempo inteiro? É CLAUDE.md, ou uma regra em .claude/rules/ se o escopo for por caminho.

4. É conhecimento ou procedimento que você usa às vezes? É skill.

E há um quinto caso que não é nenhum dos quatro: se o que falta é acesso a dado ou ação externa, o mecanismo é MCP, tratado em MCP na prática.

A documentação organiza a mesma decisão por gatilho, o que funciona melhor no dia a dia:

Skill e subagente parecem alternativas e resolvem problemas diferentes. Skill é conteúdo reutilizável que carrega no contexto que você já tem. Subagente é um trabalhador isolado, com janela própria.

Vale saber exatamente o que entra num subagente quando ele nasce, porque a lista surpreende:

• O prompt de sistema dele, não o do Claude Code inteiro
• A mensagem de delegação que o agente principal escreveu
• Toda a hierarquia de CLAUDE.md, inclusive o pessoal e as políticas gerenciadas
• Um retrato do estado do git, tirado no início da sessão-mãe
• O conteúdo completo das skills listadas no campo skills: da definição dele

Duas consequências práticas. A primeira: subagente não é contexto vazio. Ele carrega seu CLAUDE.md inteiro, então um arquivo inchado encarece cada delegação. A segunda: skill preenchida no campo skills: entra inteira, não só a descrição, o que é ótimo quando você quer garantir que o trabalhador saiba algo, e caro se você listar demais.

Os agentes embutidos Explore e Plan pulam CLAUDE.md e o estado do git. É por isso que eles saem mais baratos que um subagente próprio para a mesma busca.

Fork é o caso especial que vale conhecer. Ele herda a conversa inteira em vez de começar do zero, o que abre mão do isolamento de entrada e ganha outra coisa: como o prompt de sistema e as ferramentas são idênticos aos do pai, a primeira requisição dele lê o cache do pai. Para tarefa lateral que precisa do mesmo contexto, forkar sai mais barato que subir um subagente novo.

Na medição de custo em 48 mil turnos reais, turno de subagente custou de 3,3 a 5,2 vezes menos que turno da conversa principal, controlando por modelo. O critério de quando delegar está em subagentes: quando delegar.

Essa é a distinção que mais gente erra, e a documentação é direta sobre ela.

Uma instrução como "nunca edite o .env", escrita no CLAUDE.md ou numa skill, é um pedido, não uma garantia. Um hook PreToolUse que bloqueia a edição é enforcement. Se a regra precisa valer toda vez, ela vira hook, não instrução de prompt.

O corolário é útil na direção inversa: saída de hook entra no contexto. Um PostToolUse que roda seu linter devolve o resultado como texto que o agente lê. A mecânica completa está em hooks no Claude Code.

A regra que eu uso: processo que muda o estado do mundo e precisa de garantia é hook. Processo que precisa de julgamento é skill.

Os dois guardam instrução, e a diferença é quando carregam.

CLAUDE.md é para o que o agente precisa saber sempre: convenção de código, comando de build, arquitetura. Skill é para o que ele precisa às vezes: documentação de API, checklist de release, guia de estilo.

O alvo recomendado continua sendo abaixo de 200 linhas no CLAUDE.md. Quando crescer, o excedente vai para regra com escopo de caminho ou para skill. A anatomia completa está em CLAUDE.md: a anatomia.

Abstração fica clara com um caso só. Tome "os testes precisam passar antes do commit" e veja o que cada mecanismo entrega.

Como CLAUDE.md:

## Convenções
- Rode `npm test` antes de qualquer commit.

Entrega um pedido que vale em toda sessão e custa em toda requisição. O agente costuma obedecer, e nada impede que ele pule quando o contexto ficar cheio.

Como skill:

---
name: commit
description: Roda os testes e commita se passarem
disable-model-invocation: true
---

1. Rode `npm test`
2. Se falhar, mostre a saída e pare
3. Se passar, gere a mensagem e commite

Entrega um procedimento com julgamento, que só acontece quando você digita /commit. Custo zero até a invocação, porque disable-model-invocation tira a skill da listagem.

Como hook:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": ".claude/hooks/testa-antes-de-commitar.sh" }]
    }]
  }
}

Entrega garantia. O script inspeciona o comando, roda os testes e sai com código 2 para bloquear. Acontece toda vez, independente de o agente concordar, e custa zero de contexto a menos que devolva texto.

Como subagente: não se aplica. O problema aqui não é volume de contexto, é determinismo, e subagente não resolve determinismo. Reconhecer onde um mecanismo não entra economiza mais tempo que escolher bem entre os que entram.

A leitura das três primeiras opções em conjunto: CLAUDE.md é o que o agente sabe, skill é o que você dispara, hook é o que acontece de qualquer jeito. As três podem coexistir para o mesmo assunto, com papéis diferentes. O passo a passo de escrita de skill está em como escrever a sua primeira Agent Skill.

Aqui está a parte que ninguém escreve, e que explica comportamento estranho quando o mesmo nome existe em dois lugares. Cada mecanismo resolve conflito de um jeito diferente.

Olhe as duas linhas do meio com atenção. Em skill, pessoal vence projeto. Em subagente, projeto vence pessoal. A ordem se inverte entre dois mecanismos que moram lado a lado em .claude/.

Isso tem efeito prático. Sua skill deploy pessoal sobrescreve a que o time versionou no repositório, e você pode nem lembrar que a criou. Já seu subagente revisor pessoal não sobrescreve o do projeto: ali o time vence.

Quando o comportamento não bate com o esperado, a pergunta certa não é o que o mecanismo faz, e sim qual das definições com esse nome está valendo. Para skill de plugin, o namespace plugin:nome evita o conflito de saída, como detalhado em plugins e marketplaces.

Nenhuma escolha é neutra. A tabela oficial de custo:

Duas alavancas que saem daí. disable-model-invocation: true tira a skill da listagem inicial: ela fica com custo zero até você digitar /nome, o que vale para tudo que tem efeito colateral. E CLAUDE.md é o único item que paga em toda requisição, o que faz de cada linha nele uma decisão recorrente, não pontual. O detalhamento está em por que seu agente esquece.

Os mecanismos não competem. Configuração madura usa vários, cada um no que ele faz melhor.

O exemplo mais comum de configuração completa é banal e funciona: CLAUDE.md com as convenções, uma skill com o fluxo de deploy, MCP para o banco, e um hook rodando o linter depois de cada edição.

Comando personalizado ainda existe?

Existe e continua funcionando, mas deixou de ser categoria separada: virou skill. Arquivos em .claude/commands/ seguem criando o comando com o nome do arquivo. Para conteúdo novo, skill dá mais: pasta para arquivos de apoio, frontmatter que controla quem invoca, e carregamento automático quando relevante. A gramática completa está em slash commands próprios.

Quando skill vira subagente?

Quando o trabalho gera contexto que você não vai reler. Uma skill que faz o agente ler trinta arquivos deixa os trinta na sua janela para o resto da sessão. O mesmo trabalho num subagente devolve só o resumo. Existe também o meio-termo: context: fork no frontmatter faz a skill rodar em contexto isolado.

Por que minha skill do projeto não está sendo usada?

Provavelmente existe uma skill pessoal com o mesmo nome. Em skill, a ordem é gerenciado, depois pessoal, depois projeto — o pessoal vence. Vale conferir ~/.claude/skills/ antes de investigar o arquivo do repositório. Em subagente a ordem é a oposta, o que confunde quem aprendeu uma e assume a outra.

Preciso escolher só um?

Não, e configurações boas combinam vários. A pergunta não é qual mecanismo adotar, e sim qual deles resolve cada necessidade: garantia é hook, isolamento é subagente, contexto permanente é CLAUDE.md, e conhecimento sob demanda é skill. O checklist de operação que junta tudo está em Claude Code em produção.

• Anthropic — Claude Code Docs: Extend Claude Code. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Create custom subagents. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Extend Claude with skills. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Automate actions with hooks. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Acesso em 20/08/2026.

Verificado em 20 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) a precedência de skill ou de subagente mudar de ordem, (b) .claude/commands/ for descontinuado, ou (c) surgir um mecanismo de extensão além de CLAUDE.md, regras, skills, subagentes, hooks, MCP e plugins.