Claude Code Guide — Part 4: Subagents — forked-context workers

When Skills are not enough

By the end of Part 3 you have a .claude/skills/ directory full of reusable procedures. They work. They also surface a failure mode that no amount of additional Skills will fix.

A Skill that runs to completion in the main thread spills every intermediate read, every grep result, every sketched draft into the conversation Claude Code is using to do the next thing. By the time the Skill returns, the main thread is carrying transcript it does not need. Long Skills choke the context window.

Subagents fix that. The work runs in a separate context, the controller (your main session) only sees the report at the end, and the rest of your conversation stays clean. This part teaches the on-disk subagent — the file at .claude/agents/<name>.md invoked via the Task tool. Part 5 picks up the rules-as-prose drift problem and fixes it with hooks.

Subagents — what they are

A subagent is a forked context window. When the controller (you, in the main session) invokes one via the Task tool, Claude Code spawns a fresh thread that does not see your transcript, does not inherit your in-flight scratch work, and returns only its final report to your main session. The work it did along the way stays in its own context.

A subagent definition is a markdown file at .claude/agents/<name>.md with a frontmatter block and a system prompt body. Claude Code's canonical reference for the file format is at docs.claude.com/en/docs/claude-code/sub-agents; the rest of this section is the load-bearing fields and how to think about them.

A note on terminology before the rest of the section uses it: Claude Code subagents (the file at .claude/agents/<name>.md, invoked via the Task tool) are not the same thing as Cowork Agents (multi-step runners in the web product — see cowork-guide Part 4), and they are not the same thing as the cAgents plugin (a separate orchestration layer — see cagents getting started). Three different products share the word. This series is about the on-disk file in your repo. The next section walks the boundaries explicitly; for now, when you read "subagent" or "agent" below, read it as the on-disk file.

Four frontmatter fields matter:

• name — the identifier the Task tool routes to.
• description — a one-line summary the controller reads to decide whether to delegate to this subagent.
• tools — an explicit whitelist of tools this subagent may use. The subagent's effective permissions are the intersection of this list with the project settings from Part 2. A read-only researcher should list Read, Grep, Glob, WebFetch and nothing else.
• model — which model to run on. Cheap models for routine work, stronger models for reasoning. Skipping this field defaults to the controller's model, which is usually overkill.

The body is a system prompt. Treat it like a job description: scope, inputs, outputs, anti-patterns. Short and concrete beats long and aspirational.

Author your first subagent

Pick read-only research as the first one. It is the lowest-stakes specialization, and it is the subagent you will reach for most often once it exists — every time a task starts with "go figure out how the codebase does X" before any edits happen.

---
name: repo-researcher
description: Reads the repo to answer factual questions about how something is currently implemented. Returns a focused report with file paths and line numbers. Read-only.
tools: Read, Grep, Glob, WebFetch
model: haiku
---

You are a researcher. Your job is to answer one question about the
codebase and return a short report. You do not write code. You do not
edit files. You do not run the build.

Inputs you receive:
- A question (e.g. "where does auth live?", "how are markdown callouts
  rendered?")
- Optional file paths or directories to focus on

Output shape:
- A 5-15 line report
- Cite specific files with line numbers (e.g. `lib/markdown.ts:142`)
- If the answer is "this does not exist in the repo", say so plainly
- Do not paraphrase code that the controller can read directly — quote
  the smallest relevant excerpt and point at the file

You are a fork of the main session and your context returns to the
controller. Keep the report tight; the controller will read it cold.

The tools whitelist is doing real work here. Even if your project settings allow Edit and Bash, this subagent cannot reach for them — the intersection is empty for those tools. Least-privilege survives the handoff.

# In the main session, ask the controller to delegate to it:

Use the repo-researcher subagent to find where Mermaid diagrams are
rendered in this project. Tell me the file and the function name.

# Expected handoff:
# - The controller fires the Task tool with subagent_type=repo-researcher
# - The subagent runs in its own context, greps and reads
# - It returns ~10 lines: file path, function name, brief excerpt
# - The main session continues with that report, not the grep results

If the controller tries to do the research itself instead of delegating, your description was too vague — rewrite it to name the trigger ("when the user asks where something lives in the codebase") so the controller's routing decision is obvious.

Subagent vs. Cowork Agent vs. cAgents plugin

Three products. Same word. Worth a paragraph each so the boundaries are clean.

A Claude Code subagent is the file you just authored. It lives at .claude/agents/<name>.md in your repo. It is invoked via the Task tool from a main session. Its context is a fork of the controller's, and its tools are a whitelist intersected with project settings. Everything in this series teaches the on-disk version.

A Cowork Agent is a feature of the Cowork web product. It is a multi-step runner authored in a UI, not a file in a repo. It runs against the web product's primitives, not your local CLI. If you came here from Cowork, cowork-guide Part 4 is the article that teaches it. The two are siblings, not the same thing.

The cAgents plugin is a separate orchestration layer that installs on top of Claude Code and adds slash-command workflows for coordinating multiple subagents at once. It is a plugin, not a built-in. If you have it installed and you want to learn it, cagents getting started is the entry point. This series does not teach it — Claude Code's built-in subagents stand on their own.

Three products, three series. The vocabulary collision is unfortunate; the surfaces are genuinely different.

When to reach for a subagent

Once you have a subagent definition on disk, the question is when to use it. Three triggers, in order of how often they come up:

Research before action. Any time a task begins with "figure out how X currently works" before you change anything. The research is read-only, the report is short, and you do not want every grep result polluting the main thread for the rest of the session. Delegate to the researcher.

Bounded execution with a clean return. Refactoring a function, writing a test for a known shape, drafting a doc page from a spec. Anything where the deliverable is a small artifact (a diff, a file, a paragraph) and the path to it involves a lot of intermediate reading or scratch work the controller does not need to see.

Validation as a separate role. A reviewer subagent — read-only, sees the original brief and the produced artifact, returns PASS / FAIL / REVISE — keeps the validation step honest. The reviewer cannot fix the work; it can only judge it. That separation is part of the four-phase method Part 7 teaches.

The tradeoff. A subagent fork is a real cost — fresh context, fresh model load, the controller waits for the report. For a one-line question you would have answered in five seconds yourself, the fork is overkill. The threshold is roughly "would the steps to get the answer leave a useful trail in the main thread?" If yes, do it inline. If no, fork it.

Pointer line in CLAUDE.md

The ## Skills, subagents, hooks (pointers) anchor in your CLAUDE.md now has half its content authored. Add a line for subagents:

## Skills, subagents, hooks (pointers)

- Skills live in `.claude/skills/`. See `house-style/` for the reference Skill that shapes prose, and `commit/` for the task Skill behind `/commit`.
- Subagents live in `.claude/agents/`. See `repo-researcher.md` for read-only research; delegate to it via the Task tool.
- Hooks live in the `hooks` stanza of `.claude/settings.json` (Part 5).

The hooks line is a placeholder until Part 5 authors them; you will replace the stub with concrete examples then.

What just changed

The on-disk workspace has filled in another surface. State of your repo, in inventory form:

• CLAUDE.md at the root, with the five anchors from Part 1.
• .claude/settings.json Claude Code built and you audited in Part 2.
• .claude/skills/ with the reusable procedures you authored in Part 3.
• .claude/agents/repo-researcher.md (and any others you add), each one a forked-context worker the controller can delegate bounded tasks to.

You now have the primitive that fixes the first failure mode Part 3 surfaced: long Skills move to subagents and stop flooding the main context. The second failure mode — rules-as-prose drift — is what Part 5 fixes with hooks.

What is next

Part 5 — Hooks introduces the deterministic event handlers that fire on lifecycle events regardless of what the model decides. Hooks are the one stanza in .claude/settings.json that you do hand-author — Part 2's no-author-from-scratch rule has its one exception there. The remaining placeholder in your ## Skills, subagents, hooks (pointers) anchor gets filled in next.