A Claude Code subagent is a specialized worker — defined in a plain Markdown file — that your main session delegates bounded tasks to, and the reason they matter has almost nothing to do with parallelism. It has to do with context. In a long Claude Code session, capability is rarely the limit. The limit is that every grep, every test run, every log dump piles raw output into the conversation until the model is reasoning through a landfill. Subagents move that landfill into a separate thread and send back three sentences.

So if you’ve been searching for Claude Code subagents explained without the “10x your engineering team” theater: this is the tutorial. What they are, the exact file format, the context math that justifies them, the 5-agent setup that runs the 500k.io content factory, and the four mistakes I made so you don’t have to. If you’ve already read the hooks tutorial and the Plan Mode tutorial, this is the third leg of the stool. One disclaimer up front: my numbers come from a content-heavy solo workflow — calibrate to your own repo before copying anything.

What a subagent actually is

The anatomy: one Markdown file, two jobs

A subagent is a single .md file whose YAML frontmatter configures the agent and whose body becomes its system prompt. That’s the entire format. Per the official subagents documentation, the file lives in one of two places: .claude/agents/<name>.md in your repo (project-scoped, committed, shared with the team) or ~/.claude/agents/<name>.md (user-scoped, follows you across every repo, never committed). Project scope wins on name collisions.

A minimal working example — 14 lines:

---
name: test-runner
description: Use when tests need to be run and failures diagnosed. Returns a summary of failures with file:line references, not full logs.
tools: Bash, Read, Grep
---

You run the test suite and diagnose failures.

Rules:
- Run `pnpm test` unless told otherwise.
- Never paste full logs. Summarize each failure as: test name, file:line, one-line cause hypothesis.
- If more than 5 tests fail, group by root cause instead of listing all.

The frontmatter restricts tools (this agent can’t Write or Edit — it diagnoses, it doesn’t fix), and the body sets behavior. You can also pin a model per agent: Haiku for mechanical work, your main model for judgment calls.

One file, one job, one summary back — that’s the whole design.

The context economics (the part nobody explains)

The honest math: subagents make total token consumption go up and main-session context consumption go down — and the second number is the one that matters. A typical “find where X is handled” exploration burns 20,000-40,000 tokens of greps, file reads, and dead ends. Do that in your main session and those tokens sit in the conversation forever, degrading every subsequent response. Delegate it and the subagent burns those same tokens in a disposable thread, then returns a 200-300 token summary. Your main session pays 1% of the context cost for 100% of the conclusion.

The flip side: heavily parallel workloads can cost 10-15x more total tokens than doing everything in one session, because each subagent re-reads overlapping context. On per-token API pricing, that’s a real bill. On Claude Code Max at $100/month flat, it’s free leverage — see my Claude Code pricing breakdown for why the flat-rate plan changes which patterns are rational.

Subagents trade cheap disposable tokens for expensive main-session context. Know which one you’re optimizing.

The description field is a routing signal

Claude Code decides which subagent to invoke by reading the description field and matching it against the current task. This is the single highest-leverage line in the file, and most people write it wrong. “Security agent” tells the router nothing. “Use when reviewing code changes for injection risks, secrets exposure, or auth bypasses — returns findings ranked by severity” tells it exactly when to fire.

The pattern that works: start with “Use when,” name the trigger conditions concretely, and state what comes back. I rewrote the descriptions on my five agents in March 2026 using this pattern and delegation accuracy went from “picks the right agent maybe 60% of the time” to “I stopped thinking about it.” Builder.io’s subagent guide lands on the same conclusion: think of the description as a matching signal, not a label.

If your subagent never gets invoked, the file isn’t broken — the description is.

When to delegate (and when not to)

The delegation test: bounded, noisy, summarizable

Three questions decide whether a task belongs in a subagent. Is it bounded — does it have a clear done-state that doesn’t need mid-flight steering? Is it noisy — will it generate 10x more raw output than useful conclusion? Is it summarizable — can the result compress to a paragraph without losing what you need? Three yeses: delegate. The classic fits are codebase exploration (“map every place we touch the payments API”), test-run diagnosis, dependency audits, and research sweeps.

Three kinds of task fail the test. Interactive work — anything where you’ll react to intermediate results — because subagents start fresh and can’t absorb your conversation history. Trivial work — a 30-second single-file edit — because delegation overhead (spinning up, re-reading context) exceeds the task itself. And judgment calls that depend on everything discussed in the last hour, because the subagent wasn’t in the room.

Bounded, noisy, summarizable — the three-question test that beats any listicle of use cases.

Subagents vs skills vs hooks: pick the right primitive

These three get conflated constantly, and picking wrong wastes hours. A skill is packaged instructions your main session loads and follows in place — same context, same conversation. Use it to change how Claude works on a task. A hook is a shell command that fires automatically on lifecycle events — use it to enforce rules deterministically, as covered in the hooks tutorial. A subagent is a separate worker with its own context — use it to move work out of the room.

The composition is where it gets good. My quality-auditor subagent is triggered by a PreToolUse hook on git commit: the hook fires, the subagent scores the article in its own thread, and only the score plus three fix suggestions land back in my session. Hook enforces, subagent works, main session decides. Anthropic’s own subagents course frames it the same way: subagents are the context boundary, not the automation layer.

Skills change how. Hooks enforce when. Subagents change where.

The 5 subagents that run 500k.io

researcher, internal-linker, quality-auditor: the content spine

Three agents carry the daily article pipeline. The researcher (Bash, Read, WebSearch — no Write) pulls the live SERP for a target keyword, extracts 8-12 citable data points with source URLs, and returns a one-page dossier; it burns 30,000-50,000 tokens per run and my session sees ~400 of them. The internal-linker greps all 100+ published articles for semantic-match anchors and returns 3-5 link candidates per new draft — the ≥3 inbound links rule from the workflow deep-dive doesn’t survive without it. The quality-auditor scores drafts 0-100 against a 12-point rubric; below 85 blocks publish.

Each one exists because I did the job manually for a month first, then wrote down what “done” looked like. That’s the pattern I’d steal: never write a subagent for a job you haven’t personally done at least ten times — the system prompt writes itself from your own checklist.

Automate the job you already understand, in the order you already do it.

seo-checker and distributor: the leverage agents

The last two agents run after publish. The seo-checker validates every new article’s schema JSON-LD, canonical URL, sitemap presence, and internal-link count — an 8-item checklist that takes it 90 seconds and used to take me 15 minutes of clicking. Across 5 articles a week, that’s roughly 65 minutes recovered weekly from one 20-line Markdown file. The distributor drafts the LinkedIn post and X thread for each article in my voice (its system prompt embeds the voice rules from my CLAUDE.md file); I review and paste — 90 seconds of my attention instead of 20 minutes of drafting.

Neither agent is clever. Both are checklists with a context window. The five files together total under 150 lines of Markdown and replace what I’d conservatively estimate at 4-5 hours of weekly manual work. Your mileage will differ — that’s the honest disclaimer — but the shape of the win transfers: the best subagents are boring.

150 lines of Markdown, 4-5 hours a week. The boring agents pay the rent.

Build your first subagent this week

Day 1 — write the file, test the routing

Pick the noisiest recurring task in your workflow — for most founders it’s “go find out how X works in this codebase.” Create .claude/agents/explorer.md, write a “Use when” description, restrict tools to Read, Grep, Glob, Bash, and give the body three rules including “never return more than 400 words.” Then test the routing: ask your main session something that should trigger it and watch whether it delegates (you’ll see the delegation in the transcript). If it doesn’t fire, sharpen the description — trigger conditions, not job titles. Total setup: 15-20 minutes.

Verification step people skip: invoke it directly (“use the explorer agent to map the auth flow”) before trusting automatic routing. Direct invocation isolates whether the problem is the agent’s behavior or the router’s matching. Debug them separately and you’ll fix both in minutes instead of an evening.

First agent in 20 minutes: one noisy task, one ‘Use when’ description, one word-limit rule.

Days 2-5 — add one agent per real friction point

Resist the temptation to scaffold ten agents from a GitHub list on day one. Add the second agent only when you feel the friction it solves — a test-runner the next time logs flood your session, a reviewer the next time you ship something you wish you’d checked. By day 5 you’ll have 3-4 agents that map to your workflow instead of someone else’s. The common errors at this stage: two agents with overlapping descriptions (the router flips a coin — merge them or sharpen the boundary), agents with unrestricted tools (a researcher that can Write will eventually write), and system prompts over 100 lines (past that length, split the job).

For the wider ecosystem — packaged skills, marketplace agents, MCP-connected workers — start from the beginner guide and layer up. Subagents compose with all of it.

One agent per felt friction, never two agents with one description, no writer-tools on reader-agents.

The honest verdict on subagents

Back to the question — Claude Code subagents explained, minus the hype: they’re Markdown files that buy back your main session’s context by exporting noisy work to disposable threads. The decision tree is short. Task is bounded, noisy, and summarizable → subagent. Task needs your conversation history or your reaction mid-flight → main session. Rule needs deterministic enforcement → that’s a hook, not an agent. You’re on per-token pricing and the workload is heavily parallel → do the math first; on flat-rate Max, delegate freely.

Start with one explorer agent this week, add one agent per real friction, and keep every file under 50 lines. Five boring agents beat one impressive one.

For the rest of the stack: Claude Code hooks, Plan Mode, and how to write a CLAUDE.md — or start from the complete Claude Code guide for the full map.

FAQ

What is a Claude Code subagent in one sentence?

A subagent is a specialized assistant defined in a Markdown file — its own system prompt, its own context window, its own tool permissions — that the main Claude Code session delegates bounded tasks to, getting back a condensed summary instead of pages of raw output.

Where do subagent files live?

Two places: .claude/agents/<name>.md in your repo (project-scoped, committed to git, shared with your team) or ~/.claude/agents/<name>.md in your home directory (user-scoped, available in every repo, never committed). Project wins when both define the same name.

Do subagents cost more tokens?

Yes — each subagent re-reads whatever context it needs, so total token burn goes up, sometimes 10-15x on heavily parallel workloads. What you buy with that is main-session context: the expensive, long-lived conversation stays clean. On a flat-rate Max plan the trade is almost always worth it.

How does Claude Code decide which subagent to use?

It reads the description field in the YAML frontmatter and matches it against the task at hand. Write descriptions as routing signals ('Use when reviewing PRs for security issues'), not labels ('Security agent'). A vague description means your subagent never gets picked.

When should I NOT use a subagent?

When the task needs the full conversation history (subagents start fresh), when it's a 30-second single-file edit (delegation overhead beats the task), or when you'll need to iterate on the result interactively. Subagents are for bounded, noisy, summarizable work.

Subagent vs skill vs hook — what's the difference?

A skill is packaged instructions the main session loads and follows. A hook is a shell command that fires automatically on lifecycle events. A subagent is a separate worker with its own context. Skills change how Claude works, hooks enforce rules around it, subagents move work out of the room.