D3 · Claude Code › Cluster 7 · Subagents

7.1 · What Subagents Are

.claude/agents custom types

CONCEPT Specialized assistants defined as Markdown files

Subagents are specialized AI assistants that handle specific types of tasks. Each one is a Markdown file with YAML frontmatter: the frontmatter is the configuration (name, when to delegate, which tools, which model) and the Markdown body becomes the subagent's system prompt. When Claude meets a task that matches a subagent's description, it delegates to that subagent, which works independently in its own context and returns a result to the main conversation.

The core reason subagents exist is context management. Use one when a side task — running the test suite, fetching docs, sweeping log files — would flood your main conversation with output you'll never reference again. The subagent does that work in its own context window and returns only the summary, so your main thread stays clean.

🔑 A subagent = a Markdown file (YAML frontmatter + system-prompt body) that runs in a separate context window and hands a summary back to the main agent.

CONCEPT Where they live and how you create them

Custom subagents are discovered from two main on-disk scopes:

LocationScopeUse for
.claude/agents/Project — this codebaseTeam-shared agents; check into version control
~/.claude/agents/User — all your projectsPersonal agents available everywhere on your machine

Both directories are scanned recursively, so you can organise files into subfolders — but identity comes only from the name field, not the path. To create one, the doc's recommended path is to ask Claude to write the file for you, or write the Markdown file yourself. The /agents command manages subagents; in current versions running it prints a reminder to ask Claude or edit .claude/agents/ directly rather than opening a wizard.

⚠️ If Claude can't find a brand-new subagent, restart Claude Code. A running session doesn't detect an agents directory that didn't exist when the session started.

Claude Code also ships built-in subagents — Explore (fast read-only search), Plan (research during plan mode), and general-purpose (complex multi-step work) — that Claude uses automatically. Your custom types extend, not replace, these.

DIAGRAM A file on disk becomes a delegatable worker

flowchart TD F["📄 .claude/agents/code-reviewer.md
YAML frontmatter + system-prompt body"] --> LOAD["Claude Code loads it
as a named subagent"] LOAD --> MATCH{"Task matches its
description?"} MATCH -->|"yes"| SPAWN["🟢 Delegate:
runs in its OWN context window"] MATCH -->|"no"| MAIN["Stays in main conversation"] SPAWN --> RET["Returns only a summary
to the main agent"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef file fill:#e7f1ff,stroke:#4a90d9,color:#1a3a5a; class SPAWN ok; class RET ok; class F file;

CODE A minimal subagent file

The frontmatter is metadata + config; everything below the closing --- is the system prompt that guides the subagent.

# file: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Only name and description are required. Omit tools and the subagent inherits every tool; omit model and it inherits the main conversation's model.

TRADE-OFFS Delegate to a subagent vs. stay in the main thread

✅ Reach for a subagent when

  • The task produces verbose output you won't reference again
  • You want to enforce specific tool restrictions
  • The work is self-contained and can return a summary

⚠️ Stay in the main conversation when

  • The task needs frequent back-and-forth / iteration
  • Multiple phases share significant context
  • It's a quick, targeted change — or latency matters (a subagent starts fresh)

EXAM TRAPS

Trap: "A subagent is a separate running app / parallel session you monitor." → No. A subagent works within a single session; it's a specialized assistant Claude delegates to and that returns a result. Many independent monitored sessions are a different feature (background agents / agent teams).
Trap: "Subagents are defined in settings.json." → Custom subagents are Markdown files with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (user), not JSON settings entries.
Trap: "The whole Markdown file is config." → Only the frontmatter is config; the body is the system prompt. The subagent receives that prompt plus basic environment details, not the full Claude Code system prompt.
Trap: "You must use /agents to build one." → You can just ask Claude to write the file, or author the Markdown by hand. /agents is one way to manage them, not the only way.

PRACTICE

Q1 · In one sentence, what is a subagent and why use one?

A subagent is a specialized AI assistant — a Markdown file with YAML frontmatter — that Claude delegates matching tasks to; it runs in its own context window and returns only a summary, keeping verbose side-work out of your main conversation.

Q2 · Where do project vs. user subagents live, and what's the difference?

Project subagents live in .claude/agents/ and apply to that codebase (check them into version control for the team). User subagents live in ~/.claude/agents/ and are available in all your projects on that machine.

Q3 · Which part of the file becomes the subagent's system prompt?

The Markdown body below the frontmatter. The YAML frontmatter (name, description, tools, model) is configuration; the body is the prompt.