A confusão mais comum depois de uma semana usando Claude Code
Depois de uma semana usando o Claude Code, quase todo mundo cai na mesma pergunta: "se skills me deixam instruir o agente e subagents também fazem trabalho especializado, por que existem os dois? Quando uso cada um?"
A resposta curta: skills e subagents resolvem problemas diferentes, mesmo parecendo ensinar a mesma coisa ao agente. A resposta longa — este artigo — começa pela arquitetura, passa por cinco estudos de caso reais e termina com um critério que você consegue aplicar na hora de decidir.
Se você ainda não viu os dois isoladamente, leia primeiro Slash Commands e Skills: personalizando seu fluxo no Claude Code e Subagents no Claude Code: orquestrando tarefas em paralelo. A partir daqui assumo que você sabe o básico de cada um.
A diferença que ninguém explica direito
Skills e subagents vivem em planos completamente diferentes da arquitetura do Claude Code.
Skills são instruções + conhecimento injetados no mesmo contexto do agente principal. Quando uma skill ativa, o conteúdo do SKILL.md (e dos arquivos anexos) entra na janela da conversa atual. O Claude principal "lê" a skill como se você tivesse colado um manual, e passa a seguir suas orientações. Não há isolamento: tudo acontece no mesmo processo, na mesma janela de contexto, com as mesmas ferramentas.
Subagents são processos separados com contexto próprio. Quando você dispara um subagent via Task, o Claude principal pausa, um novo agente é instanciado com sua própria janela de contexto, suas próprias ferramentas permitidas, e seu próprio system prompt. O subagent roda até terminar, devolve uma única mensagem ao orquestrador, e morre. Nada do que ele leu, pensou ou tentou entra no contexto do orquestrador.
Essa assimetria muda tudo. Skills são compartilhamento de conhecimento. Subagents são delegação de trabalho. São coisas diferentes. Você pode precisar de uma sem precisar do outro.
O eixo do custo de contexto
Skills têm um custo oculto: a description de cada skill carregada fica permanentemente no prompt inicial, e se a skill ativa, o corpo inteiro entra também. Em uma sessão longa com cinco skills ativas, você paga o custo de todas o tempo todo. Por isso o conselho de manter poucas skills bem descritas — o ideal são 5-10 bem focadas, não 50 genéricas.
Subagents não têm esse custo contínuo. Eles só consomem tokens quando são disparados, e o consumo fica dentro do contexto do subagent — não no orquestrador. Você pode ter 20 tipos de subagent definidos sem penalizar nenhum dos prompts que não os invocam.
Regra prática: se o conhecimento precisa estar sempre disponível, use skill; se é um processo caro que só roda sob demanda, use subagent.
O eixo da invocação
Skills ativam por match semântico implícito. Você não invoca a skill; o modelo detecta que o seu prompt bate com a description de alguma skill instalada e carrega o conteúdo sozinho. O gatilho é linguístico: "preciso adicionar uma coluna na tabela X" ativa uma skill de migrations, mesmo que você nunca tenha dito "migration".
Subagents ativam por invocação explícita do orquestrador. O Claude principal decide chamar Task({subagent_type: "code-reviewer", ...}) e passa o briefing completo. O subagent só existe porque alguém o invocou deliberadamente.
Regra prática: se quem decide é o modelo a partir de contexto ambíguo, é skill; se quem decide é o orquestrador a partir de uma necessidade específica (pesquisar, revisar, debugar), é subagent.
Cinco estudos de caso
Caso 1: codificar a convenção de migrations do time. Você quer que qualquer desenvolvedor do repo, ao pedir uma nova migration, receba o padrão certo (naming, RLS, rollback). Conhecimento sempre disponível, ativado por gatilho linguístico natural. Skill.
Caso 2: investigar onde vive uma feature num repo desconhecido.
Respostas rápidas para perguntas exploratórias, sem encher o contexto do orquestrador com dezenas de greps. Subagent (Explore).
Caso 3: revisar um diff sensível com olhar independente.
Você quer uma leitura fria, sem as racionalizações que o orquestrador já absorveu. Subagent (code-reviewer).
Caso 4: ensinar o agente a escrever commits no padrão do time. Você quer que toda vez que o agente for comitar, siga conventional commits com o escopo certo. Skill — ou, alternativamente, um slash command dedicado se você prefere invocação explícita em vez de ativação automática.
Caso 5: rodar três investigações paralelas antes de planejar uma refatoração grande.
Três áreas diferentes do código, três ângulos, trabalho paralelo. Três subagents em paralelo, todos Explore ou general-purpose. Esse padrão é a base de fan-out orchestration descrita em Padrões de orquestração multi-agente no Claude Code.
Onde as pessoas erram
Erro 1: criar subagent para substituir skill.
"Vou criar um migration-writer subagent que sabe escrever migrations do nosso padrão." Parece razoável, mas é ruim: cada migration agora exige invocação explícita, perde a ativação automática, e a lógica fica duplicada em um briefing para o subagent. Use skill.
Erro 2: criar skill para substituir subagent.
"Vou criar uma skill code-review-critico com instruções de como revisar diffs." Problema: o conhecimento entra no contexto do orquestrador, que já absorveu sua perspectiva. Você perde a leitura fria. E o SKILL.md vai competir por atenção com todas as outras tarefas da sessão. Use subagent.
Erro 3: skill com descrição ruim. "Migrations do Supabase" ou "Ajuda com testes" são descrições inúteis. O modelo não sabe quando ativar. Descrições devem ser gatilhos explícitos: "Use quando o usuário pedir para criar uma migration, alterar uma tabela ou mudar uma RLS policy." Sem isso, a skill nunca vai ativar na hora certa.
Erro 4: criar subagent ao invés de usar um do catálogo.
Antes de criar seu próprio tipo, olhe o catálogo built-in: code-reviewer, debugger, test-writer, security-auditor, Explore, Plan, refactorer, doc-writer. Se algum bate com o seu caso, use ele — vem com system prompt otimizado. Só crie custom quando o catálogo realmente não cobre, seguindo o tutorial em Criando Subagents customizados passo a passo.
Eles podem combinar?
Sim — e é aí que a coisa fica elegante. Uma skill pode instruir o orquestrador a disparar subagents específicos em determinados momentos. Exemplo: uma skill big-refactor-guard ativa sempre que o pedido envolve "refatorar" ou "mover X para Y", e o conteúdo dela diz "antes de começar, dispare um subagent Explore para mapear as dependências; depois um Plan para desenhar a abordagem; só então implemente". A skill codifica o processo, o subagent executa o trabalho pesado. Os dois papéis em harmonia, não em competição.
A regra para combinar: skills ensinam quando e como delegar, subagents executam a delegação. Se você mantém essa disciplina, nenhum dos dois atropela o outro.
Próximos passos
Leia o artigo de 10 skills essenciais para produtividade se o seu próximo passo é encher o arsenal de skills. Leia Criando Subagents customizados se quer escrever seu primeiro tipo custom. E quando já tiver os dois em produção, o artigo sobre padrões de orquestração multi-agente mostra como combiná-los em fluxos de fan-out/fan-in que escalam para tarefas realmente grandes.
