🌱 Fundamentals

Your main chat is the conductor: it understands the request and decides what to delegate. The subagent is the specialist musician who handles one part.

Without this separation of roles, you try to do everything in a single conversation and lose control of what’s happening.

Maestro = orchestrates and decides; subagent = performs a task and reports back.

The subagent receives the task, opens its own context window, works, and returns only the result to the conductor.

This is the cycle that keeps your conversation lean — the grunt work stays in the subagent’s window.

Dedicated window = isolation; report = only the essentials come back.

Five different subagents can run in parallel, each with its own role, returning five summaries to the orchestrator.

Visualizing the fleet helps you understand the benefit: multiple workstreams at once, without mixing contexts.

Parallelism = N independent windows; each persona = a specialist.

The subagent doesn’t talk with you turn by turn. It gets a task, carries it out, and disappears—it’s not a second chat.

Expecting dialogue from the subagent is the most common mental error. Knowing what it is NOT avoids frustration.

No back-and-forth; no memory of your conversation; one task.

Each subagent speaks only to the conductor that called it. Subagents do not talk to each other.

Defines what can and cannot be orchestrated—and why coordination always belongs to the conductor.

Star topology; the conductor is the only point of convergence.

Claude Code comes with ready-to-use subagents (such as general-purpose). You can invoke one without creating anything.

Experimenting before theorizing makes the concept stick: you see the report come back clean in practice.

Built-in = ready to use; delegate by asking “open a subagent to…”

The context window is the session’s working memory. The status line shows how many tokens and what percentage you’ve used.

Whoever understands the window understands why delegation matters. It’s a finite resource you spend with every file you read.

Context = limited resource; %/tokens = your budget.

Everything you read in the main conversation — logs, files, large outputs — stays there taking up space until the session ends.

Polluted context degrades subsequent responses. Recognizing the pollution is the first step to avoiding it.

Reading = ongoing cost; accumulated noise makes it harder to focus.

Read 300 pages in the main conversation versus having a subagent read them and bring you only the 3 facts that matter.

It’s the course’s central decision. Internalizing the tradeoff changes how you work day to day.

You = dirty context; subagent = preserved context.

The subagent does the heavy lifting in its own window and returns a distilled summary—not the raw pile.

It’s what goes into your conversation. A good summary is the subagent’s output; you only see the gold.

Distillation; the report is the interface between the two windows.

Many people think subagents are about being faster. The main benefit is preserving context.

Targeting the right reason helps you use subagents in the right situations, not just “to go faster.”

Context > speed; speed is a bonus, not the goal.

A product research task involving huge documentation: the subagent reads it all and returns the 3 decisive points.

A concrete number makes the idea stick better than theory: hundreds of pages would cost half your context window.

Compression ratio; the summary fits where the raw source wouldn’t.

Agent = the main assistant; subagent = a specialist delegated to its own window; skill = an instruction/capability loaded into the current context.

Confusing the three leads you to use the wrong tool. One clear sentence for each unlocks everything.

Three primitives, three roles; they're not synonyms.

The subagent has its own isolated window; the skill runs inside the current agent’s shared context.

It’s the axis that makes the biggest difference: a skill dirties your context; a subagent protects it.

Isolation (subagent) vs. in-place (skill).

You can run multiple subagents in parallel; a skill runs within the agent’s sequential workflow.

When you need N fronts at the same time, only a subagent can deliver that.

Parallel = subagent; inline = skill.

A subagent can run on a different model than the orchestrator; a skill uses the model of the agent that loaded it.

It’s the foundation of savings: a cheap Haiku subagent while the lead stays on Opus.

Model per agent; skill inherits the current model.

Skills and agents call each other, but an agent does not invoke another agent — coordination always goes back to the conductor.

Defines the limits of orchestration. Trying to make an agent call another agent breaks the model.

skill ↔ agent OK; agent → agent NO.

A living table that cross-references context, parallelism, model, and invocation to point to the right primitive for each scenario.

It’s the deliverable you’ll refer to forever. Memorize the axes, not the cells.

Decisions by axis; the table is the backbone of Track 1.

Claude Code comes with built-in subagents: Explore (search), Plan (architecture), general-purpose (all-purpose), and Claude itself.

Before creating anything, you already have powerful tools. Knowing which ones exist helps you avoid reinventing the wheel.

Built-in = ready; covers search, planning, and general tasks.

Giving the general-purpose agent a persona in a prompt doesn't create a custom subagent—it's just a temporary instruction.

This is a common mix-up. A true custom is a persistent, reusable file that runs on its own.

Ad hoc persona ≠ saved agent; custom = file.

A custom subagent is a Markdown file with frontmatter + body. It lives on disk and is always available.

It’s the bridge to Track 2. Understanding that “it’s just a .md” demystifies creating one.

.md = subagent; frontmatter (config) + body (brain).

Claude reads only the name and description of each agent until deciding to use one. The full body is loaded only when the agent is called.

Explains why the description is so important and why having many agents doesn't weigh down the context.

Progressive disclosure; load the details only when needed.

Since only name+description stay loaded, you can have dozens of agents without bloating the context.

Takes the fear out of “having too many agents.” The catalog is lightweight by design.

Catalog cost ≈ metadata only; body on demand.

The command /agents lists the available subagents (built-in and custom) and opens the creation assistant.

It’s the practical entry point. Before you create one, see what’s already there with a command.

/agents = list + create; starting point for T2.

One question covers most cases: “Will this generate a pile I’ll never read again?” If so, delegate.

It’s the heuristic that saves you from memorizing lists. One phrase in your pocket is worth ten rules.

Future reuse of the output = criterion; “reading junk” → subagent.

Many files, a wall of output, a repeated task, independent jobs in parallel, or the need for an impartial reviewer.

Recognizing the quick green light helps you delegate at the right time, without hesitation.

Volume, noise, repetition, parallelism, impartiality.

Quick edits, dependent steps, agents that would need to talk to each other, when you need the full conversation or need to ask you a question.

Forcing a subagent where it doesn't fit creates rework. The red flag saves time.

Speed, dependency, dialogue, personal context.

Rule of thumb: 10+ files to scan or output you’ll never reread = subagent.

A number makes the decision objective when intuition falters.

10-file threshold; output wall = trigger.

When the job requires dozens or hundreds of subagents, you move to a dynamic workflow that orchestrates the fleet.

Marks the boundary between “one subagent” and “an operation at scale” — a topic explored in depth in Learning Path 3.

Scale changes the tool; watch the cost.

For something quick, doing it directly in chat is better. A subagent has startup costs—it isn’t worth using for everything.

Balance: the right tool for each task size, without dogma.

Startup overhead; small tasks stay in the chat.

There's nothing magical about it: the subagent is literally a Markdown file, with the same structure as a skill.md.

Demystify it once and for all. If you can edit text, you can create a subagent.

File = agent; plain text, versionable.

The top among --- is the frontmatter (YAML configuration); the rest is the body, the brain with the instructions.

Viewing both zones gives you the mental map for all of Track 2. Each has a distinct role.

Frontmatter = how the agent is selected; body = how it acts.

The essential frontmatter fields: name, description, tools e model.

With these four, you can already create a functional subagent. The rest is refinement.

name (id), description (trigger), tools (permission), model (cost).

A good body defines the role (“you are a…”), the numbered steps, the output format, and what NOT to do.

This structure is what separates a reliable agent from a generic one. It's the skeleton of Track 2.

Role → steps → output → constraints.

The file is in .claude/agents/ (in the project) or ~/.claude/agents/ (global) — topic of Track 2.

Knowing where it lives is what connects “create the .md” with “Claude finding and using it.”

Folder determines scope; project vs. global.

Beyond the 4 key fields, there are advanced fields (color, memory, disallowed-tools, MCP) documented officially.

You don’t need to memorize everything: you need to know that the complete reference exists and where to find it.

4 fields to get started; official docs for the rest.