What are Claude Code subagents, and how are they different from agent skills?

What a subagent actually is

A subagent is a separate AI worker that the main Claude Code session can delegate a piece of work to. The Claude Code documentation defines it as a specialized AI assistant that handles specific types of tasks, runs in its own context window, and returns a summary to the main conversation instead of dumping its tool output into the parent context. That summary mechanism is the entire reason the primitive exists: large volumes of search results, file listings, log lines, or test output stay in the subagent's window, and the parent only sees what the subagent judges worth saying back.

Subagents are not interactive sessions of their own. They run inside the parent session, get spawned by the Agent tool, and finish when their task finishes. For genuinely separate sessions that should run in parallel and be monitored from a parent view, the documentation points at background agents. For sessions that pass messages to each other across longer timeframes, the documentation points at cross-session messaging. For coordinated teams of sessions that Claude spawns and supervises, the documentation points at agent teams. Subagents are the smallest of those primitives, the one you reach for first.

The file that defines a subagent

Every subagent is a Markdown file with YAML frontmatter. The Claude Code documentation is explicit that only two frontmatter fields are required: a name field, which is a unique identifier made of lowercase letters and hyphens, and a description field, which is the string the main agent matches against your request to decide whether to delegate. The documentation warns that the name cannot contain a colon, which is reserved for plugin-scoped identifiers, and that Claude Code will not load a file with a colon in its name.

The supported optional fields read like a small configuration language. tools narrows the built-in tool set; disallowedTools removes tools from whatever pool the subagent inherits; model picks a model alias such as sonnet, opus, haiku, fable, or a full model ID like claude-opus-5, with inherit as the default. permissionMode selects from default, acceptEdits, auto, dontAsk, bypassPermissions, plan, and the manual alias for default. skills preloads a set of Skills into the subagent's context at startup. mcpServers exposes a configured MCP server or defines one inline. memory turns persistent memory on with user, project, or local scope. isolation: worktree runs the subagent inside a temporary git worktree branched from the project default branch rather than the parent HEAD. The breadth of the field set is itself a signal that subagents are meant to be configured deliberately rather than improvised per task.

• name: required, lowercase letters and hyphens, must be unique, no colons.
• description: required, the matching string the main agent uses to decide when to delegate.
• tools: optional allowlist narrowing the subagent's tool set.
• disallowedTools: optional denylist; tools are removed from the inherited or specified pool.
• model: sonnet, opus, haiku, fable, a full model ID, or inherit. Defaults to inherit.
• permissionMode: default, acceptEdits, auto, dontAsk, bypassPermissions, plan, or manual.
• skills: preload the full content of named Skills into the subagent's context at startup.
• mcpServers: either a configured server name or an inline server definition.
• memory: user, project, or local to enable persistent cross-session memory.
• isolation: worktree runs the subagent in a temporary git worktree.

Built-in subagents vs your own

Claude Code ships with built-in subagents that fire automatically when the main agent decides a request matches them. The documentation lists three primary built-ins and a small group of helpers. Explore is a fast read-only agent that searches and analyzes code, inherits the main conversation's model up to Opus on the Claude API, and as of v2.1.198 no longer forces Haiku; it now runs on whatever the parent runs on, capped at Opus. Plan is the read-only research agent used while you are in plan mode. General-purpose is the capable multi-step agent that can both read and modify the codebase, and it has access to every tool available to subagents.

The helpers are claude, the catch-all background-session default, statusline-setup on Sonnet for the /statusline command, and claude-code-guide on Haiku for product questions. You can disable any specific built-in by adding it to permissions.deny, remove the Agent tool entirely with permissions.deny, or remove only the Explore and Plan built-ins by setting CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 in the environment, which is supported from v2.1.198 onward. Beyond the built-ins, the documentation expects you to write your own subagents for the workflows you keep repeating, which is the practical signal that a custom subagent is justified.

Where the subagent lives on disk

Subagent files live in one of five locations and the location decides who can use them. The priority order, highest first, is managed settings, the --agents CLI flag for the current session, .claude/agents/ inside the project, ~/.claude/agents/ for the user, and a plugin's agents/ directory. Project and user subagents are discovered by walking up from the current working directory, so every .claude/agents/ between the working directory and the repository root is scanned, and Claude Code uses the definition closest to the working directory when names clash across nested project directories.

Claude Code watches .claude/agents/ and ~/.claude/agents/ for changes. A new file in an existing scope is picked up within a few seconds, no restart needed. The exception is the very first agent file you add to a scope whose agents/ directory did not exist when the session started: that case still needs a restart, and sessions started with --disable-slash-commands do not watch the directories at all. The watcher is one of the reasons keeping procedures as files rather than as inline instructions is the durable pattern.

Subagents versus Skills, in one sentence

A subagent is a process. A Skill is a document. Subagents are spawned to do work and they run with their own system prompt, their own tool allowlist, and their own model choice; Skills are read on demand and they only ever put instructions into the agent that is already running. The two compose cleanly: the documentation's skills frontmatter field preloads the full content of named Skills into the subagent's context at startup, so a subagent can be told to follow a documented procedure without re-loading the Skill's text every time the subagent runs.

Practically, the decision comes down to whether the work needs its own context. If the answer is no, the right primitive is almost always a Skill, because Skill cost is amortized across every agent that reads it. If the answer is yes, a subagent is the right primitive, because keeping a long exploration or a noisy log stream out of the main context is the whole point. Most real setups end up with a small library of Skills that describe the procedures and a smaller library of subagents that perform the work the procedures reference, with skills: lines in the subagent frontmatter wiring them together.

Choosing a model and a permission mode

The model field is where most of the cost discipline lives. The documentation lists four model aliases, sonnet, opus, haiku, and fable, plus the option of a full model ID and inherit, which uses the main conversation's model. The Claude Code model resolution order is the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then a per-invocation model parameter, then the frontmatter, and finally the main conversation's model. inherit is treated the same as leaving the field unset from v2.1.196 onward, and any of these can be narrowed by an organization-level availableModels allowlist, with Claude Code falling back to inherit when a blocked value cannot be substituted.

Permission modes are the other lever that deserves deliberate thought. The default mode asks for approval the way Claude Code usually does, acceptEdits auto-approves file edits, auto is the higher-trust setting for unattended work, dontAsk skips the prompts entirely, bypassPermissions does the same, and plan is the read-only mode used while you are planning. The manual alias requires v2.1.200 and behaves like default. For a long-running exploration subagent, acceptEdits or default is the safe default. For a test-runner subagent that should not touch anything other than its own scratch space, plan is often the right choice.

Practical patterns the documentation spells out

The documentation names three patterns worth knowing. Isolate high-volume operations is the canonical reason to use a subagent at all: anything that produces a lot of output, like a repo-wide grep, a documentation crawl, or a dependency audit, stays in the subagent's context and the main conversation only sees a summary. Run parallel research fans out multiple subagents to investigate different parts of a question and waits for them, which is the practical way to use the concurrent subagent limit. Chain subagents lets a subagent call further subagents, with the depth limit set by the documentation and the Agent tool refusing to spawn past it.

Two operational notes round out the picture. The first is the concurrent subagent limit, which the documentation references but leaves tuning to the model configuration; a project that needs more parallelism than the default allows has to plan for it. The second is the context management section, which describes what loads at startup for every subagent. A custom subagent with the same name as a built-in will override the built-in within the scope where it lives, so defining one with model: haiku under .claude/agents/ is a documented way to keep exploration on a cheaper model than the main conversation.

Limits of this answer

Subagent support and exact behaviour change with Claude Code versions, and the documentation is explicit about which fields were added in which release. The figures quoted above are taken from the public documentation page for subagents; if a future release adds a new field or changes the resolution order, that change is documented against the same page rather than against this article. RepoRadar has not independently benchmarked subagent performance or cost, and no such measurement is implied.

Support for subagents also varies by the Claude Code surface. The CLI, the IDE integrations, and the Agent SDK all read the same frontmatter but expose different subsets of fields, and the documentation lists those differences in the relevant pages. Treat this article as a description of the documented contract, not as a guarantee that any specific product line honours every optional field.

A useful next action

Pick one task you have delegated to Claude Code more than twice. Open .claude/agents/ in your project, create a Markdown file with a clear name and a description that says both what the subagent does and when Claude should use it, and set the model and tools fields deliberately. If the subagent should follow a documented procedure, write a Skill and add its name to the subagent's skills: frontmatter.

Try the new subagent on a real task and compare the main conversation's context to the same task done without it. If the main conversation is meaningfully shorter and the result is at least as good, the subagent has earned its slot. If you also want to know when a Skill is the better primitive, RepoRadar's answer on what Agent Skills are and how they differ from MCP servers covers that decision in more depth.