Main agent, subagents, skills · the three Claude Code primitives that matter

Honest opener. 2,030 contributions this year, and I did not type most of them. Agents did. Running in their own worktrees, shipping PRs while I slept.

The thing that took me from "Claude wrote one nice function" to "Claude ships features in parallel while I review" was not a fancier model. It was finally getting three primitives straight: the main agent, subagents, and skills.

Most teams I talk to mix these up. They reach for a subagent where a skill would do. They write a skill where a subagent is needed. Or they pile everything into the main agent and then wonder why Claude got dumb at 60% context. So this is the mental model I wish someone had handed me on day one.

01 · The main agent is a loop

Type claude in your terminal. A process starts. It holds one conversation in memory. Your system prompt, your CLAUDE.md, every skill description, every user message, every tool call, every result, every reply. All of it sits in one growing transcript. That transcript is the context window. The "agent" is one in-flight LLM call, repeated, replaying the whole transcript every time.

Three things follow from that, and they shape everything else.

• →No hidden memory. If a fact is not in context, the model cannot use it.
• →Every tool result costs context. A Bash command that prints 4,000 log lines costs 4,000 lines of transcript for the rest of the session. Even if Claude only cared about two.
• →The window has a hard limit. Claude Code auto-compacts older turns near the limit. Useful, but a summarised turn is a forgotten turn.

Once you accept that the context window is finite and that every part of the session is fighting over it, the design of subagents and skills stops being clever and starts being obvious.

02 · Subagents keep your main context clean

A subagent is what happens when the main agent calls the Task tool. Claude Code spins up a second conversation. Different system prompt. Often a different tool list. Its own context window. The parent waits. When the subagent finishes, only its final reply comes back. Every file it read, every grep, every reasoning step, gone.

Why this matters: ask the main agent to audit a 50-file auth module and Claude reads every file. Now your main context holds the whole module. Delegate that same audit to a subagent and the parent only grows by the audit report. Maybe 600 tokens instead of 15,000.

Three rules I keep coming back to.

• →The reason to spawn a subagent is almost never "to go faster." It is to keep the parent context clean.
• →A subagent that returns 50,000 tokens of analysis is failing at its job, no matter how fast it got there. Ask for a bounded summary. A numbered list, a JSON shape, something small.
• →The tools list in a subagent's frontmatter is actually enforced. A reviewer with tools: Read, Grep, Glob cannot call Write or Bash, no matter how you prompt it. Use that.

Subagents can run in parallel. The main agent can call Task three times in one turn and Claude Code dispatches three concurrent inference streams. Each gets its own clean window. None of them know the others exist. That is how a single "refactor the payments module" request fans out to reviewer plus test-writer plus migration-writer, all working at once.

03 · Skills ship expertise on demand

A skill is a folder with a SKILL.md and any supporting files. The frontmatter has a name and a description. Everything else is optional. No daemon, no execution model, no runtime. A skill is text that knows when to enter the context.

The trick is called progressive disclosure. At session start, Claude Code injects only every skill's name and description into the system prompt. Roughly 30 to 80 tokens each. The body is not loaded. The references are not loaded. Only when Claude judges that a description matches the current task (or when you type /skill-name) does the body actually enter the window.

So you can have fifty skills installed and the session still feels fast. Fifty descriptions might cost two thousand tokens of baseline overhead. The bodies, which could be tens of thousands of tokens combined, are never paid for unless they are actually used.

A SKILL.md that works in production usually shares two design choices.

• →The description reads like a trigger list. "Use when editing migrations/*.sql, when running raw SQL through better-sqlite3, when resolving a P3009" beats "Helps with database stuff" every time. Claude is matching descriptions to your live conversation. Be precise.
• →The body is short. Under 300 words. Anything bigger gets pushed into reference/*.md files Claude only reads when it actually needs them. A 30k-token reference manual is fine if it lives at level 3.

04 · How they compose

The question I see most often is "should this be a skill or a subagent?" That question is the bug. They are not substitutes. They are different layers.

A code-review skill describes the review process. A code-reviewer subagent runs in isolation with restricted tools and pre-loads that skill in its frontmatter. The subagent literally cannot forget the skill, because the skill is sitting in its system prompt.

One subtlety that bit me the first time. In a normal main-agent session, skill descriptions load at startup and bodies load on demand. Inside a subagent, when you list a skill in the frontmatter, the full body is injected at the subagent's startup. Not on demand. That is deliberate. A subagent has a clean window and a focused job, so paying the full skill cost up front buys you guaranteed compliance.

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: >
  Reviews code for correctness, style, and security.
  Use proactively after the main agent writes or edits any source file.
tools: Read, Grep, Glob
skills: [security-audit, ts-style]
---

You are a meticulous code reviewer. When invoked you must:
1. Read every file mentioned in the task.
2. Cross-reference against the loaded skills.
3. Return a numbered list of findings with file:line references.
4. Mark each finding as 'blocking' or 'suggestion'.
Do not edit files. Read-only review only.

Three things in that file matter. The description is what the main agent reads when deciding whether to delegate. Write it as a usage guide, not a brochure. The tools list is enforced. The skills list is pre-injected into the subagent's system prompt at startup, so it begins the task already knowing the rules.

05 · Picking the right one

Once you stop treating them as alternatives, the choice gets boring.

• →You keep telling Claude the same thing every session. The company report style. The migration rules. The team's API conventions. Repeated procedural knowledge. Make it a skill.
• →You want Claude to investigate a 50-file area without polluting your main session, or you want three independent jobs running in parallel. Delegated, bounded work. Make it a subagent task. Give it the relevant skill in its frontmatter.
• →You need a brand new capability the model cannot express through code. Talking to a stateful external system, say a live browser. That is MCP. Different post.

06 · Take-home

A subagent is an agent. It is a Claude inference run. A skill is not an agent. It is text loaded into one. An agent with no skills still works. A skill with no agent is a markdown file doing nothing.

That clarity is what unlocked the green squares. Once I stopped dumping everything into the main agent, once I had focused subagents with restricted tools, each pre-loaded with the right skill, I could let several of them work in parallel worktrees while I reviewed PRs. My job moved from typing code to dispatching, reviewing, occasionally guiding. Closer to a tech lead than a dev at a keyboard.

That's how 2,030 commits in five months actually happens.

Pierre