Claude Code Subagents: Split the Work, Verify the Result

Claude Code subagents are specialized assistants that Claude hands a task to: each runs in its own context window with its own system prompt, tool access and permissions, and returns only a summary to your main conversation (Claude Code docs: subagents). You define one as a Markdown file with YAML frontmatter in .claude/agents/ or ~/.claude/agents/, and Claude delegates to it when a task matches its description or when you name it. Everything below was checked against the docs on October 3, 2026, followed by the pattern that made subagents worth it for this blog: one agent writes, then a verifier with a fresh context re-reads the sources.

What does a subagent get, and what does it not see?

Each subagent except a fork, which inherits the whole conversation, starts with a fresh, isolated context window (fork the conversation). It does not see your conversation history, the skills you already invoked or the files Claude already read (what loads at startup). It gets its own system prompt, which is the body of its file and not the Claude Code system prompt, plus the task message Claude writes when it delegates, your CLAUDE.md files and a git status snapshot. The built-in Explore and Plan agents skip CLAUDE.md and git status to stay fast, and a custom subagent can skip CLAUDE.md with omitClaudeMd: true.

Where are subagents defined?

In Markdown files: the frontmatter configures the subagent, the body becomes its system prompt, and only name and description are required (frontmatter reference). When two definitions share a name, the higher-priority location wins (subagent scope).

A verifier in this format looks like this. tools is an allowlist, so this one can read and edit files and fetch web pages but cannot run shell commands; leave the field out and the subagent inherits every tool available to subagents.

---
name: fact-checker
description: Checks a draft article against the vendor documentation it cites. Use after a draft is written.
tools: Read, Edit, WebFetch, WebSearch
model: sonnet
---
 
You check one draft. For every claim about a product, open the cited
page and confirm it says that. Fix a claim the page supports in other
words, cut a claim no official page supports, and return a list of
every change with its source URL.

Claude Code picks up a new or edited file within a few seconds without a restart; one case that still needs a restart is an agents folder that did not exist when the session started (write subagent files).

How do you invoke a subagent?

Four ways, from a hint to a hard choice (invoke subagents):

• Automatic: Claude matches your request against each subagent's description. Phrases like "use proactively" in the description encourage delegation.
• By name in your prompt, such as "Use the fact-checker subagent on this draft". Claude still decides whether to delegate.
• By @-mention: type @ and pick it from the list, or write @agent-fact-checker. This guarantees that subagent runs for the task.
• For the whole session: claude --agent fact-checker, or the agent key in .claude/settings.json.

The @-mention picks the subagent, not its prompt: Claude still writes the task message from what you asked. Claude Code also ships built-in subagents it uses on its own: Explore for read-only codebase search, Plan for research in plan mode, and general-purpose for tasks that need both exploration and changes (built-in subagents).

When should you use a subagent?

The docs draw the line by context (subagents or main conversation). Use one when the task produces verbose output you will not need again, when you want to restrict tools or permissions, or when the work is self-contained and can come back as a summary. Stay in the main conversation for back-and-forth, for phases that share a lot of context, for quick targeted changes, and when latency matters, since a subagent that is not a fork starts fresh and may need time to gather context. For a reusable procedure that should run inside your conversation, the docs point to skills instead. For dozens of agents in one run, dynamic workflows orchestrate subagents from a script rather than turn by turn.

The list does not name the use that matters most to me: checking work another agent did.

Why should the verifier be a separate subagent?

Because a fresh context cannot lean on the writer's reasoning. The agent that wrote a claim has already argued itself into it, so asking it to check its own draft mostly gets that argument back. A subagent that is not a fork starts without the conversation, so the only way it can confirm a claim is to open the source. The docs' own example of nesting points the same way: a reviewer subagent that dispatches a verifier per finding (nested subagents).

In a recorded talk, Lauren Tan, an engineer at Cursor, puts verification at the center of how she came to trust coding agents: give the agent a way to run the real app and test its own change, because that is "the thing that really closes the loop". Without it, she says, you are the verifier and the bottleneck. She also turned failures she watched, such as an agent confidently naming a cause without reading the code, into skills that tell it to look the code up, use subagents and stop guessing. My work here is articles, not an app, but the loop is the same: a claim counts as checked when a second agent has read its source, and a page counts as checked when an agent has rendered it.

How does this blog use writer and verifier agents?

Each article goes through a multi-agent workflow. One writer agent drafts it. An independent fact-checker then re-reads the vendor help pages behind it and fixes or cuts every claim it cannot match. Editor passes tighten the copy, and one agent renders every page in a real browser at desktop and phone width. One run on October 2, 2026 used 32 agents to write 13 manuals, tighten 5 drafts and render-check 20 pages. Nothing from a run reaches the live site on its own: I approve every commit and every push.

Two choices make a fact-checker useful. Give it the draft and the sources, not the writer's notes: a subagent does not see your conversation, so the task is where that rule lives. And let it cut, as mine does: a checker that can only flag leaves a weak claim in place until someone argues it out.

What did the verifiers catch?

Three errors that read fine to the agents that wrote them:

• A claim about Google Ads "Calls from ads" that missed Google's newer AI rating of recorded calls. Google's help now says that with call recording on, every call is recorded and evaluated by AI and only qualified calls count, and call length decides only when a call cannot be recorded (AI-qualified call leads). The forwarding-number manual covers the current rules.
• An outreach hook saying a practice's Wix site sent its Google hits with consent "denied" and showed no banner. The denied state came from where the check ran, which was Bulgaria: Wix's help says that without a banner, a visitor from a country that requires consent, such as those covered by GDPR, sends no data to Google Analytics (Wix Help). The finding was withdrawn (testing Consent Mode from Europe).
• A sentence that invented frequency: "the case I see most", with no count behind it. The phrase now fails my content linter, one of the hard checks that replaced reminders in prompts.

The writer had no reason to doubt itself in any of these. The verifier had nothing to defend, only a page to read.

Where to start

The smallest useful setup is two agents and one rule: a writer, a verifier that reads the sources with a fresh context, and nothing ships until the verifier has finished. Once that runs across many pages at once, you need something that hands out the work and collects the verdicts. That is the subject of a coordinator, workers and a verifier.