🧩 Agent × Subagent × Skill

Think of a professional kitchen. The agent is the chef who talks with you the whole time and leads the way. The skill is a recipe the chef pulls from the drawer: instructions that go at their workstation and guide the next action. The subagent is a cook sent to a separate kitchen with a well-defined task—they work alone and return only when the dish is ready. Same building, different roles; mixing them up delays dinner.

↑ The three primitives side by side. Notice: the skill runs in the same context; the subagent works in a separate context and returns only the summary.

Before any table, write down a pocket definition for each one. If you take only this away from the module, it will already be worth your time: the agent leads, the skill instructs, the subagent runs separately.

This is the axis that matters most. The skill runs in shared context — everything it does and reads stays in the yours window, adding tokens. The subagent runs in a clean, own context — it uses as many tokens as it needs internally, and your window only receives the report at the end.

Subagents run in parallel: the agent can launch five at once, each in its own window, all at the same time. Skill isn't parallel — it is an instruction that runs in the thread of your conversation, one step at a time. Wanting "five skills at once" is a sign that the work belonged to subagents.

A subagent can choose its own model — run Haiku for a cheap scan, or Opus for heavy reasoning — regardless of the agent's model. A skill doesn't choose a model: it’s an instruction, so it runs on the model that already is driving the conversation. A skill always inherits it; the subagent can switch.

Here's the most overlooked rule — and the one that most often breaks orchestration designs. Skill and agent call each other both ways: the agent uses a skill, and a skill can launch a subagent. But a agent doesn't call another agent straightforward: subagents don't invoke subagents. If you need a sequence A→B→C, the main agent handles the chaining.

Everything we’ve seen fits in a single table — the backbone of this module. Keep this image in mind: it answers at a glance which primitive to use. Notice the last line (when to prefer): it’s what you’ll refer to whenever you’re unsure.

↑ The "When to prefer" line is your decision map: procedure in the workflow → skill; heavy, isolated, or parallel work → subagent.

Nothing makes the difference clearer than taking a single task — "run the release checklist"—and writing it both ways. Notice: the instruction content is almost the same; what changes is where they run e what you get back.

--- # 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.

--- # 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.

Three prompts to help you feel the difference firsthand: one triggers a skill (in the workflow), one delegates to a subagent (isolated), and one asks the agent to choose between the two — that way you can hear the reasoning.

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.

Side by side, the same work in both modes. At left, the skill runs within from your session — you see every step and the context bar rising. At right, the subagent runs in a separate session—you only see its panel, and the your context barely changes.

↑ Illustrative recreation (not a real screenshot). Same job: the skill fills your context (58%); the subagent preserves it (9%) because the clutter stayed in its window.