Claude Code Subagents

What are Claude Code subagents?

Subagents are specialized Claude configurations that live as Markdown files in your project. Each one has its own system prompt, its own restricted tool set, and — crucially — its own separate context window. When Claude Code needs to do specialized work (security review, database migration, framework-specific refactor), it can either be told to use a specific subagent or it can automatically route work to one whose description matches the task.

Think of subagents as spawning a purpose-built specialist. Your main Claude Code conversation delegates a chunk of work to a subagent, the subagent does the work in isolation, and only the result comes back — not the intermediate context. This keeps your main context window clean and lets each specialist have exactly the system prompt it needs.

Anatomy of a subagent

Every subagent is a single Markdown file with YAML frontmatter and a system-prompt body:

Three things worth calling out:

1. The description is critical. When you type > use the security-reviewer agent… Claude Code looks for a subagent whose description matches. Include trigger keywords like "Use PROACTIVELY" to encourage automatic routing.
2. tools is a hard boundary. This subagent literally cannot write files, run git push, or do anything outside its allowed list. That's the security guarantee — a reviewer role that can't accidentally modify code.
3. The body is the system prompt. Everything after the frontmatter becomes the subagent's system prompt. Be specific about role, checklist, and output format.

Frontmatter fields you'll actually use

• name — unique identifier used when explicitly invoking the agent. Kebab-case.
• description — when the agent should be used. Write this from Claude's perspective: "Use when X". Add PROACTIVELY to encourage auto-invocation.
• tools — comma-separated list of allowed tool patterns. Narrow is safer.
• model — haiku, sonnet, or opus. Match model to task complexity to control cost.

Why subagents change how you use Claude Code

• Context isolation. A subagent's work — reading 40 files, running 20 tool calls, iterating on a diff — happens in its own window. Only the final result returns to your main conversation. Your main context stays lean.
• Specialized system prompts. Every subagent is essentially a mini-Claude with a domain expert's brief. A next-js-15 agent knows App Router patterns cold. A postgres-dba agent thinks in indexes and query plans.
• Tool-level guardrails. Give your test-writer agent write access only to tests/**. Give your code-reviewer read-only access. Enforce these boundaries at the config layer, not in the prompt.
• Cost matching. Route cheap tasks (formatting, renaming) to Haiku subagents. Reserve Opus for architecture, security, and complex refactors. Each subagent picks its own model.
• Automatic delegation. If descriptions are well-written, Claude routes to the right subagent without being told. This is where PROACTIVELY and specific trigger phrasing pay off.
• Team standardization. Commit .claude/agents/ to git. Every dev gets your team's security reviewer, your team's test writer, your team's DBA — with the same standards baked in.

Subagents vs slash commands vs hooks — the decision framework

All three shape Claude Code behavior. Here's how to pick:

• Subagent when you need a specialized role with its own context: security reviewer, framework expert, DB migration specialist. Runs on demand or via auto-routing.
• Slash command when you need a repeatable prompt template: /commit, /review, /deploy. Runs in the main conversation, expands to a prompt.
• Hook when you need automatic enforcement at lifecycle events: block git push --force, auto-format on save, log every tool call. Runs without being invoked. See our hooks hub.

Real projects use all three. A /security-review slash command delegates to a security-reviewer subagent, whose file writes are further gated by a PreToolUse hook.