CHECK 09 12 MIN · HANDS-ON

Subagents

What you’ll know by the end of this check

  • What a subagent actually is (and isn’t)
  • When to spawn one vs. keep the work in your main context
  • How to create your own subagent with /agents

The shortest possible answer

A subagent is Claude Code spawning a second instance of itself with its own fresh context window to handle a scoped task. When it finishes, it hands back a summary — not the transcript of how it got there.

Your main context stays clean.

Why it matters

The expensive part of Claude Code isn’t thinking. It’s the exploration: reading 40 files to find 2 relevant lines, running searches, scanning test output. All of that clutter lives in the main context by default and crowds out what you actually need.

Subagents quarantine the mess. The subagent does the reading and the grepping in its own window. You get back the answer.

Example scenarios:

  • “Find every place that calls the deprecated auth helper” — subagent explores, returns a list.
  • “Review this diff for security issues” — subagent reviews with a clean slate, returns findings.
  • “Summarize the failing test output and propose a root cause” — subagent reads the test runner, returns the hypothesis.

Creating your own subagent

Run:

/agents

Select Create new agent. You’ll step through:

  1. Scope — project (checked in) or user (your account only).
  2. Purpose — what this agent is for. Claude drafts a name, description, and system prompt from this.
  3. Tools — which tools the subagent has access to. Less is more.
  4. Color — cosmetic, but helps you spot which agent is running.

The generated agent is a markdown file with YAML frontmatter. You can edit it directly.

Customization worth knowing

  • Persistent memory. A subagent that retains memory across invocations. Useful when the same subagent is called repeatedly on the same project (e.g. a domain-specific code reviewer who’s “read” the codebase once).
  • Preload skills. Add a skill key listing skill names. Unlike main-context Skills (which load only when needed), a subagent loads the full skill content into its context upfront. Use sparingly.

When NOT to use a subagent

  • The task is small enough to fit inline. Subagents have setup cost.
  • You need the conversation to continue with this context. Subagents summarize — they don’t hand back everything.
  • The task requires tools your subagent isn’t configured to use.

Things to try right now (15 minutes)

  1. Run /agents in a Claude Code session.
  2. Create a simple project-scoped subagent: code-reviewer. Give it file-read tools only.
  3. Make a small diff in your repo.
  4. Invoke the subagent: “code-reviewer: review my staged changes.”
  5. Read the summary. Compare it to your main context — the main window should still be clean.

The canonical version

Full official lesson is at anthropic.skilljar.com/claude-code-101/469796.

Deeper dive: Anthropic’s Introduction to subagents course.

Ready to verify this check?

You’ve created and invoked a subagent at least once. You can name two scenarios where a subagent beats keeping the work inline. Mark it cleared.