Claude Code subagents: how to create one, call it and keep context clean

What a subagent is and when to use one

The point is isolation. Per the docs, each subagent runs in its own context window with a custom system prompt, its own tool access and independent permissions. A search across a hundred files or a test run with a long log stays inside the subagent; the main thread gets the conclusion.

Three are built in: Explore (fast, read-only codebase search), Plan (gathers context in plan mode) and General-purpose (multi-step work that edits files). Write your own when a role keeps coming back: a reviewer that never touches files, a tester limited to Bash, a docs researcher.

For a one-off task, skip it. If you are describing the same role for the third time, make it a file.

Where subagent files live

• .claude/agents/*.md in the project (Claude Code searches upward from the working directory), committed with the code;
• ~/.claude/agents/ for personal subagents across projects;
• the agents/ folder of a plugin;
• --agents '<json>' for a single session;
• organization managed settings.

In current versions /agents just reminds you to edit the files directly or ask Claude. Up to v2.1.197 it opened a wizard with Running and Library tabs.

File format and frontmatter fields

Two fields are required: name (up to 256 characters, no colon) and description. The body becomes the system prompt.

---
name: code-reviewer
description: Reviews changes before commit. Use after edits in src/.
tools: Read, Grep, Glob
model: inherit
---
You are a reviewer. Read the diff, look for logic errors and missing checks.
Do not edit files. Finish with a list of findings with path and line.

This is a sketch; test it on your own repo. Optional fields: tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, effort, isolation, background, omitClaudeMd, color, initialPrompt.

Leave out tools and the subagent inherits every tool available to subagents, minus a few that are always removed, such as AskUserQuestion. For a reviewer or researcher, list tools explicitly. That is the only way to be sure it will not rewrite anything.

How to invoke a subagent

• Automatically. Claude Code delegates when a task matches the description, so write the description as a trigger: "use when…".
• By @-mention in your message.
• With a flag: claude --agent <name> runs the whole session as that agent.
• In plain words: "hand the review to the code-reviewer subagent".

Limits and gotchas

• Up to 20 subagents in parallel, set by CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
• Nesting goes three levels below the main conversation (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; 1 turns nesting off).
• Claude Code warns when custom subagent descriptions exceed 15,000 tokens in total, because descriptions always sit in context.
• The skills preload takes the first 32 skills.
• Plugin subagents ignore hooks, mcpServers and permissionMode. If a role needs its own hook, ship it in .claude/agents/, not in a plugin.

Source: Claude Code docs.

Which other agents read Claude Code subagents

Cursor and VS Code take Claude Code files as they are. Codex needs the role rewritten as TOML (Codex docs); for Gemini CLI, moving the folder and checking the fields is usually enough (Gemini CLI docs). Ready-made roles are in Subagents and the best Claude Code subagents list.