Claude Code Subagents: Examples, Best Practices, and When to Use Skills Instead (2026)

How Claude Code subagents work: file locations, frontmatter fields, a working example, model selection, best practices, and how subagents differ from skills and agent teams.

**Short version:** a subagent is a specialist with a clean desk. Claude hands it a task, it works in its own context window — reading files, running tests, grepping logs — and only a summary comes back. Your main conversation stays small and focused. All details below are from Anthropic's subagents documentation.

Why subagents exist: context isolation

Every subagent starts with a fresh context window. It does not see your conversation history or files you already read; Claude writes it a delegation message instead. Verbose output — test runs, logs, file contents — stays inside the subagent, and only the relevant summary returns. That is the whole point: a 4,000-line test log never touches your main context.

This is also a cost lever. If your sessions balloon, routing noisy work to subagents pairs well with the fixes in our token usage guide.

Where subagent files live

Where Claude Code subagent files live and which location wins

Location	Scope	Priority
Managed settings	Organisation-wide	1 (highest)
`--agents` CLI flag	Current session	2
`.claude/agents/`	Current project	3
`~/.claude/agents/`	All your projects	4
A plugin's `agents/` folder	Where the plugin is enabled	5 (lowest)

When two subagents share a name, the higher-priority location wins. Project subagents can be committed so your whole team gets them.

A working example

This is the example from Anthropic's docs — a read-only reviewer on a cheaper model:

---
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. The useful optional fields:

tools / disallowedTools — omit tools and the subagent inherits everything; list them to keep a reviewer read-only
model — sonnet, opus, haiku, fable, a full model ID, or inherit
permissionMode, maxTurns, skills, mcpServers, hooks, memory

Best practices that actually change results

Write the description for delegation. Claude decides when to delegate from the task, each subagent's description, and context. Phrases like "use proactively" encourage automatic delegation.
Keep descriptions short. When combined custom subagent descriptions exceed 15,000 tokens, Claude Code warns at startup.
Give the minimum tools. A reviewer that can only Read, Glob and Grep cannot accidentally edit your code.
Route by model. Search and summarising rarely need your most expensive model.

You can also call a subagent explicitly by naming it, @-mentioning it, or running a whole session as one with --agent. Subagents load CLAUDE.md files, except the built-in Explore and Plan agents, which skip them.

Subagents vs skills vs agent teams

Claude Code subagents compared with skills and agent teams

Skill — reusable instructions that run in the main conversation. Use when the result needs your full context.
Subagent — a task in an isolated context that returns a summary. Use when the work is noisy.
Agent team — several sessions Claude spawns and supervises. Use for genuinely parallel, multi-session work.

They combine: a subagent can preload skills through its `skills` field, and a skill can run in a subagent with `context: fork`. Subagents can also be packaged and shared inside Claude Code plugins.

Frequently asked questions

What are subagents in Claude Code?+

Subagents are specialised assistants that Claude Code delegates tasks to. Each one runs in its own context window with a custom system prompt, its own tool access and its own permissions. Claude hands a subagent a task when it matches the subagent's description, the subagent does the work in isolation, and only a summary returns to your main conversation. They work within a single session and are defined as Markdown files with YAML frontmatter.

Where do I put a Claude Code subagent file?+

Put project-specific subagents in .claude/agents/ inside your repository, where they can be committed and shared with your team. Put personal ones in ~/.claude/agents/ so they work in every project. Subagents can also come from managed organisation settings, the --agents command-line flag, or an enabled plugin. When two share a name, managed settings win first, then the CLI flag, then project, then user, then plugin.

How do I choose the model for a subagent?+

Set the model field in the subagent's frontmatter to sonnet, opus, haiku, fable, a full model ID, or inherit to use the main session's model. A common pattern is putting search, summarising and read-only review on a smaller, cheaper model while keeping complex implementation on your strongest one. Because each subagent has its own context, the model choice only affects the work it is delegated, not your main conversation.

What is the difference between subagents and skills?+

A skill is reusable instructions that run inside your main conversation, so it can use everything already in context. A subagent runs in a separate, fresh context window and returns only a summary, which keeps noisy output such as logs and test runs out of your main session. Use skills when the result needs your full context, subagents when the work is verbose. A subagent can preload skills, and a skill can fork into a subagent.

Why is Claude not using my subagent?+

Claude decides whether to delegate based on your request, each subagent's description field and the current context, so a vague description is the usual cause. Rewrite it to say exactly when the subagent should be used, and add phrases like use proactively to encourage automatic delegation. You can always invoke it directly by naming it or @-mentioning it. Keep descriptions short; very long combined descriptions trigger a startup warning.