Pense numa cozinha profissional. O agente é o chef que fala com você o tempo todo e conduz. A skill é uma receita que o chef pega da gaveta: instruções que entram na bancada dele e guiam a próxima ação. O subagente é um cozinheiro mandado pra uma cozinha separada com uma tarefa fechada — trabalha sozinho e volta só com o prato pronto. Mesmo prédio, papéis diferentes; trocar um pelo outro sem querer atrasa o jantar.
↑ As três primitivas lado a lado. Repare: a skill entra no mesmo contexto; o subagente trabalha num contexto separado e só devolve o resumo.
Conteúdo detalhado
🧩 As três primitivas em uma frase
Antes de qualquer tabela, grave a definição de bolso de cada uma. Se você só levar isto do módulo, já vale o tempo: o agente conduz, a skill instrui, o subagente executa em separado.
Agente
O chat com que você fala. Conduz a conversa, usa skills e dispara subagentes. Pode ser built-in ou um .md seu.
Skill
Um bloco de instruções (uma receita) que entra no mesmo contexto do agente e guia a próxima ação. Não tem janela própria.
Subagente
Um trabalhador acionado pelo agente, que roda numa janela própria e separada e devolve só um relatório.
💡 O atalho mental que resolve 90% da confusão
Pergunte: "isso abre uma janela nova ou não?" Skill não abre — ela é texto que entra no contexto atual. Subagente abre — é uma sessão separada. O agente é a janela onde você já está.
a definição de bolso das três primitivas — agente (conduz), skill (instrui no mesmo contexto), subagente (executa em contexto separado).
quase todo erro de iniciante é usar uma onde caberia outra: criar subagente pra algo que era skill, ou esperar que uma skill rode em paralelo. A frase certa evita isso.
agente = chat · skill = instrução no contexto · subagente = janela própria · pergunta-filtro "abre janela nova?".
🪟 Contexto: próprio e limpo × compartilhado
Esse é o eixo que mais importa. A skill roda no contexto compartilhado — tudo que ela faz e lê fica na sua janela, somando tokens. O subagente roda num contexto próprio e limpo — ele queima quantos tokens precisar lá dentro, e a sua janela só recebe o relatório no fim.
📜 Skill — contexto compartilhado
- •Tudo que ela lê e escreve fica na sua sessão
- •Soma no seu uso de contexto (a barra sobe)
- •Ótimo quando você quer o resultado no fluxo
- •Ruim se a tarefa despeja muita coisa que você não relê
🛰️ Subagente — contexto próprio
- •Janela separada, isolada da sua conversa
- •Pode queimar 200k tokens e não tocar a sua barra
- •A sessão dele some quando termina (descartável)
- •Você fica só com a conclusão, sem a sujeira
📊 O mesmo trabalho, dois custos de contexto
Imagine "leia 40 arquivos e ache o bug". Como skill, os 40 arquivos entram na sua janela — ela pode ficar pesada. Como subagente, os 40 arquivos ficam na janela dele; você recebe "está no auth.js:88" e sua barra mal se move. É exatamente o motivo nº 1 dos subagentes — o tema do módulo 1.2.
⚡ Paralelismo: muitos de uma vez × um por vez
Subagentes rodam em paralelo: o agente pode disparar cinco de uma vez, cada um na sua janela, todos ao mesmo tempo. Skill não é paralela — ela é uma instrução que executa no fio da sua conversa, um passo de cada vez. Querer "cinco skills ao mesmo tempo" é um sinal de que o trabalho era de subagentes.
Skill: um passo, no seu fio
Sequencial por natureza.
A skill injeta instruções e o agente age na hora, na mesma sessão. Se você tem três receitas, ele segue uma, depois a outra — não há "três ao mesmo tempo".
Subagente: muitos, lado a lado
Paralelo de verdade.
O agente abre cinco subagentes numa tacada — revisar um texto sob cinco olhares, por exemplo. Os cinco trabalham simultaneamente; o agente dispara, recolhe e junta os cinco relatórios no fim (eles não conversam entre si — relação 1-para-1 do módulo 1.1).
🎚️ Modelo: próprio × herda do agente
Um subagente pode escolher o próprio modelo — rodar em Haiku para escanear barato, ou em Opus para um raciocínio pesado — independente do modelo do agente. Uma skill não escolhe modelo: ela é instrução, então roda no modelo que já está conduzindo a conversa. Skill sempre herda; o subagente pode trocar.
🛰️ Subagente — modelo próprio
- •Define
model:no frontmatter dele - •Haiku pra varrer · Sonnet pra construir · Opus pra decidir
- •Ou
inherit— herda o do agente de propósito - •É a base da economia (tema da Trilha 3)
📜 Skill — herda, sempre
- •Não tem campo de modelo — não há janela própria
- •Roda no modelo que está na conversa naquele momento
- •Quer outro modelo? Troque o do agente, não da skill
- •Simplicidade: é só texto guiando a ação
💡 Por que isso é um superpoder
Modelo próprio é o que deixa um agente caro (Opus) coordenar uma frota barata (Haiku): o chefe pensa, os trabalhadores executam por uma fração do custo. Skill não dá esse controle — e tudo bem, porque o trabalho dela é outro.
model: · chefe caro + frota barata · inherit.🔀 Quem chama quem (a regra que pega todo mundo)
Aqui está a regra mais esquecida — e a que mais quebra desenhos de orquestração. Skill e agente se chamam nos dois sentidos: o agente usa uma skill, e uma skill pode disparar um subagente. Mas um agente não chama outro agente direto: subagentes não invocam subagentes. Se você precisa de uma sequência A→B→C, quem encadeia é o agente principal.
✓ Chamadas que acontecem
- ✓Agente → usa uma skill
- ✓Agente → dispara um subagente
- ✓Skill → pode disparar um subagente
- ✓Subagente → usa skills dentro da janela dele
✗ O que não rola
- ✗Subagente A → subagente B (sem passar pelo agente)
- ✗Dois subagentes "combinando" entre si
- ✗Uma skill rodando "sozinha" sem um agente
- ✗Você digitando direto pra um subagente
⚠️ O erro de orquestração mais comum
Desenhar "o subagente de pesquisa chama o subagente de escrita, que chama o de revisão". Não funciona: quem encadeia é o agente. Ele recebe o relatório de A, decide, e só então dispara B. Subagente não é um nó que comanda outro nó — é uma folha que responde ao agente.
📊 A tabela canônica: onde mora e quando preferir
Tudo o que vimos cabe numa tabela só — a espinha deste módulo. Guarde esta imagem: ela responde, de relance, qual primitiva usar. Repare na última linha (quando preferir): é o que você vai consultar toda vez que ficar em dúvida.
| Eixo | 🎼 Agente (built-in) | 📜 Skill | 🛰️ Subagente |
|---|---|---|---|
| Contexto | Compartilhado — é a janela onde você está | Compartilhado — entra no contexto do agente | Próprio e limpo — janela separada e descartável |
| Paralelismo | É quem orquestra os paralelos | Não — executa no fio da conversa | Sim — vários ao mesmo tempo |
| Modelo | O modelo da sua sessão | Herda — roda no modelo do agente | Próprio — escolhe (ou inherit) |
| Quem chama quem | Usa skills · dispara subagentes · não chama outro agente | Chamada pelo agente · pode disparar subagente | Disparado pelo agente · não dispara outro subagente |
| Onde mora | Built-in (já vem) ou .claude/agents/*.md |
.claude/skills/<nome>/SKILL.md |
.claude/agents/*.md (projeto ou global) |
| O que devolve | A conversa contínua com você | Ações/efeitos no fluxo atual | Um relatório — não a sessão inteira |
| Quando preferir | Sempre presente — é o maestro do trabalho | Padronizar um procedimento no fluxo (passos, regras, formato) que você quer ver acontecer | Isolar trabalho pesado/paralelo cuja saída suja o contexto e você só quer a conclusão |
↑ A linha "Quando preferir" é o seu mapa de decisão: procedimento no fluxo → skill; trabalho pesado/paralelo isolado → subagente.
💡 Regra de bolso final
Quer guiar como o agente faz algo, no seu fluxo? Skill. Quer terceirizar um trabalho pesado/paralelo e receber só o resultado? Subagente. Quer conversar e coordenar? Você já está no agente. As três se complementam — não competem.
Exemplo real: o MESMO job, como skill × como subagente
Nada deixa a diferença tão clara quanto pegar um único trabalho — "rodar a checklist de release" — e escrevê-lo das duas formas. Repare: o conteúdo das instruções é quase igual; o que muda é onde elas rodam e o que você recebe de volta.
--- # frontmatter de SKILL
name: release-check
description: Roda a checklist de release no
fluxo atual. Use quando o usuário disser
"checar release" ou "pronto pra publicar".
# sem campo model: herda o do agente
---
# corpo: guia a ação do AGENTE, aqui mesmo
Ao ser acionada, no contexto atual:
1. Conferir CHANGELOG e versão.
2. Rodar os testes e mostrar o resultado.
3. Listar pendências aqui na conversa.
Tudo acontece na janela do usuário.→ Os passos rodam no seu contexto. Você vê tudo no fluxo. Bom quando você quer acompanhar e agir junto.
--- # frontmatter de SUBAGENTE
name: release-checker
description: Roda a checklist de release numa
janela própria e devolve só um resumo. Use
pra checar release sem poluir o contexto.
tools: Read, Grep, Bash # só o necessário
model: haiku # barato: é varredura
---
# corpo: roda na janela DELE, isolado
You are a release checker.
1. Conferir CHANGELOG e versão.
2. Rodar os testes.
3. Devolver só: pronto? sim/não + pendências.
Reporte um resumo. Não cole logs brutos.→ Os passos rodam na janela dele. Você recebe só "pronto: não — faltam 2 testes". Bom quando a saída é grande e você não quer relê-la.
🔍 O que muda entre os dois arquivos
Mesma lógica, três diferenças que denunciam a primitiva: a pasta (skills/<nome>/SKILL.md × agents/<nome>.md); os campos (a skill não tem model nem tools; o subagente tem os dois, porque a janela própria precisa declarar ferramentas e modelo); e a saída (skill mostra tudo no fluxo, subagente devolve um resumo e some).
Prompts prontos (copie e cole)
Três prompts para você sentir a diferença na pele: um aciona uma skill (no fluxo), um delega a um subagente (isolado), e um pede ao agente para escolher entre as duas — assim você ouve o raciocínio.
Rode a checklist de release aqui mesmo, passo a passo,
me mostrando cada item conforme for conferindo. Quero
acompanhar no fluxo, não em separado.Abra um subagente pra rodar a checklist de release numa
janela própria e me devolva só: pronto pra publicar
(sim/não) + a lista de pendências. Não despeje os logs
no meu contexto.Preciso revisar 25 arquivos atrás de senhas hardcoded.
Isso é melhor como skill (no meu fluxo) ou como subagente
(janela própria)? Decida e me explique em 2 linhas por que.Tela simulada: skill no fluxo × subagente em paralelo
Lado a lado, o mesmo trabalho nos dois modos. À esquerda, a skill roda dentro da sua sessão — você vê cada passo e a barra de contexto subindo. À direita, o subagente roda numa sessão à parte — você vê só o painel dele, e o seu contexto mal se mexe.
↑ Recriação ilustrativa (não é screenshot real). Mesmo job: a skill enche o seu contexto (58%); o subagente o preserva (9%) porque a sujeira ficou na janela dele.
Exercício: classifique 6 cenários
Para cada cenário abaixo, decida: é skill, subagente ou simplesmente o agente conversando? Escreva sua resposta antes de abrir o gabarito.
Os 6 cenários
- Padronizar como o assistente formata todo commit (mensagem, co-author, tom) — você quer ver acontecer no fluxo.
- Vasculhar 50 PDFs de contrato atrás de uma cláusula e receber só "achei na página X de cada".
- Revisar um texto sob 5 perspectivas diferentes ao mesmo tempo (iniciante, técnico, editor…).
- Te ajudar a pensar em voz alta sobre qual arquitetura escolher, trocando ideias.
- Sempre que você pedir "deploy", rodar uma sequência fixa de verificações no fluxo antes de prosseguir.
- Rodar um verificador de segurança barato (Haiku) em 30 arquivos sem encher seu contexto.
✅ Critério de verificação — como saber que acertou
Use estas três perguntas, nesta ordem, para cada cenário:
- 1.Abre uma janela nova? Se a saída é pesada/paralela e você só quer a conclusão → subagente.
- 2.É um procedimento que você quer ver no fluxo? Padronizar passos/regras/formato no contexto atual → skill.
- 3.É conversa/coordenação? Pensar junto, decidir, trocar ideias → o agente mesmo.
Acertou se a sua justificativa cita contexto (compartilhado × próprio) e/ou paralelismo — não só o "feeling".
Gabarito comentado
- 1 → Skill. Procedimento de formato no fluxo; você quer ver e ajustar. Mesmo contexto.
- 2 → Subagente. 50 arquivos é leitura pesada que não pode sujar seu contexto; você quer só a conclusão.
- 3 → Subagente (×5, em paralelo). "5 ao mesmo tempo" só existe com subagentes; cada um na sua janela.
- 4 → Agente. É diálogo e raciocínio com você — precisa da conversa inteira, não cabe terceirizar.
- 5 → Skill. Sequência fixa de passos no fluxo, disparada por um gatilho ("deploy"). Contexto compartilhado.
- 6 → Subagente (Haiku). Trabalho paralelo/barato em 30 arquivos, isolado, com modelo próprio — protege o contexto.
Placar: 5–6 certos = você internalizou os eixos. 3–4 = revise contexto e paralelismo. 0–2 = releia a tabela do tópico 6.
✅ Resumo do módulo
Próximo módulo:
1.4 — Built-in × Custom. Os subagentes que já vêm prontos × os que você cria, e por que o Claude só lê o name+description até decidir (progressive disclosure).