Subagents vs Skills

What it takes off your plate: moving "read forty files" out of the main thread

The contract: one markdown file, two required fields

A subagent is a .md file under .claude/agents/ (project) or ~/.claude/agents/ (global) — both are scanned recursively. Only name and description are required; the body is its system prompt. From the official subagents docs, these optional fields are the ones worth memorizing:

# .claude/agents/api-developer.md
---
name: api-developer
description: Implement API endpoints following team conventions
tools: Read, Grep, Edit, Write, Bash   # omit = inherit all; a tool left out isn't in its session at all
model: sonnet                          # sonnet/opus/haiku/fable/inherit
skills: [api-conventions, error-handling-patterns]  # * preloaded at startup
memory: project                        # user/project/local persistent memory
isolation: worktree                    # * give it its own git worktree
omitClaudeMd: true                     # skip CLAUDE.md files (saves tokens)
maxTurns: 10                           # output at the cap is marked partial; resumable
---
You are an API development specialist...

That skills: line kills the false dichotomy on its own: a subagent can run with skills loaded. It works the other way too — a skill whose frontmatter sets context: fork runs in an isolated context, and agent: picks which subagent type it forks into (see the official skills docs).

The first thing you can run: nothing to install

Claude Code ships three built-in subagents. Zero installs, available right now:

# (1) Explore -- read-only tools (Write/Edit denied), three thoroughness levels
Use the Explore subagent, very thorough, to map every place we validate JWTs

# (2) Plan -- the one that researches during plan mode, also read-only
# (3) general-purpose -- every tool available to subagents; can modify code

# After writing your own agent file, check its frontmatter before a session
claude plugin validate .claude/agents

# No file needed: a one-off JSON definition
claude --agents '{"code-reviewer":{"description":"Expert code reviewer.",
  "prompt":"You are a senior code reviewer.","tools":["Read","Grep","Glob"],"model":"sonnet"}}'

# Or run the whole session as that agent
claude --agent code-reviewer

What Explore takes off your plate is very concrete: the output of forty greps never enters your conversation. When not to use it: the answer is one line anyway ("which file holds this function"). Dispatching an agent to ask costs you a cold start plus a round trip, and the context you save isn't worth that.

Mechanism: one inheritance table explains nine tenths of "why does it know nothing"

What that single pipe actually costs you

The SDK docs put it plainly: The only content you pass from parent to subagent is the Agent tool's prompt string, so include any file paths, error messages, or decisions the subagent needs directly in that prompt. That is the entire explanation for "but I just told it" — you told the main conversation, not the subagent.

The third state: forks, which don't belong in either column

/subtask <description> in an interactive session starts a fork: its own context window, but full inheritance of the parent's history, system prompt, output style, model, and the parent's exact tool pool (skipping the filter that trims tools from background subagents). A fork is the answer for "I need isolation but I cannot afford amnesia." The cost: it inherits every token of the parent, so the only noise isolation saves is what comes after.

Why a skill travels the other road

A skill's mechanism is instruction injection: the description sits in context permanently (cheap), the body expands only when invoked, and once expanded it stays in the thread across turns. So skills fit "a rule every following step must honor," subagents fit "this stretch I don't want to watch." disable-model-invocation: true makes a skill user-only; user-invocable: false makes it model-only. Those two fields together are a skill's real invocation contract.

Real usage and limits: five installable or readable entries, with commands

(1) obra/superpowers · subagent-driven-development

# one command from the official marketplace
/plugin install superpowers@claude-plugins-official

This skill has a one-line description: Use when executing implementation plans with independent tasks in the current session. It opens an isolated git worktree, verifies the plan, scans for conflicts and creates a ledger; then per task it runs dispatch implementer → handle report → task-specific review → fix loop, up to five rounds, with rounds 1–3 resuming the original implementer and rounds 4–5 escalating to a more capable model; finally a whole-branch review on the most capable model. What it takes off your plate: by task seven of a long plan, the noise from tasks one through six has already filled the window. When not to use it — it says so itself: no implementation plan exists, the tasks are tightly coupled rather than independent, or your platform has no subagents at all (then run inline).

(2) Same repo · dispatching-parallel-agents

Its trigger reads 2+ independent tasks that can be worked on without shared state or sequential dependencies, while the body sets a higher bar: three or more distinct root causes before parallelism pays. The line worth memorizing is the mechanism: Multiple dispatch calls in one response = parallel execution. One per response = sequential. Parallelism is not a switch — it is how many calls you put in one reply. When not to: the failures are related (fixing one may fix the others), understanding requires full system context, agents would interfere with each other's edits, or the root cause is unknown and you're still exploring. It also has a line worth taping to a wall: Do NOT just increase timeouts—find the real issue.

(3) isolation: worktree: the only sane way to write files in parallel

It is no accident that both skills above start by opening a worktree: several subagents editing one working tree are overwriting each other. One frontmatter line, isolation: worktree, gives an agent its own; superpowers also ships a dedicated using-git-worktrees skill for that path. When not to: read-only work (anything Explore-shaped) — a worktree is pure IO there.

(4) wshobson/agents: an off-the-shelf agent library

/plugin marketplace add wshobson/agents
/plugin install python-development

Self-described as 94 plugins, 202 agents, 183 skills, 105 commands (per that repo's README, read 2026-09; MIT), generating harness-native artifacts from one markdown source. The real value is reading how other people write descriptions — whether a subagent ever gets dispatched automatically depends entirely on that field. When not to install: taking the whole marketplace means paying a description tax (see the 15,000-token warning in 04); install only the plugin you actually use.

(5) The Agent SDK: writing all this into code

In the SDK, subagents are the agents parameter of query(), and AgentDefinition maps almost field for field onto the file version (description and prompt required; tools, disallowedTools, model, skills, maxTurns, background, effort optional). Two traps: in the Python SDK, disallowedTools and mcpServers keep their camelCase spelling; and to detect a real dispatch you must match both "Agent" and the older name "Task". Past a certain scale subagents are the wrong tool — the docs point at the Workflow tool and dynamic workflows, which move orchestration into a script outside the conversation. When not to reach for Workflow: two or three agents in a turn, where plain subagents are enough.

Three criteria, to choose between the entries above

1. Do you still need to watch the middle? Following it step by step → skill (it stays in the thread). Only the conclusion → subagent. This settles eighty percent of the cases.
2. Does it need what you said earlier? Needs the whole history → a fork via /subtask. Needs a few paths and one stack trace → a normal subagent, with those written into the prompt string.
3. Is it genuinely independent? Three or more distinct root causes, no shared state, no overlapping files → dispatch in parallel. Otherwise go sequential, or let one agent finish it.

Cost and alternatives: 15x tokens, and a new problem called "the stronger it gets, the more it delegates"

The hardest number in this piece

In How we built our multi-agent research system (2025-06-13) Anthropic gives three figures: agents use about 4x the tokens of chat, and multi-agent systems about 15x; on their internal research eval the multi-agent system beat single-agent Claude Opus 4 by 90.2%; and token usage alone explains 80% of the variance in browsing ability. The same piece lists where it does not fit: tasks where all agents need the same context, domains with many inter-agent dependencies, and most coding tasks — their wording is that coding has fewer parallelizable components than research. Read the three together: 15x for 90.2% is worth it or not depending on whether your task looks like research or like editing code.

The extra line item Opus 5 adds

Prompting Claude Opus 5 says it outright: Claude Opus 5 delegates to subagents more readily than prior models. The official remedy comes in two layers — a prompt layer and a hard cap:

# (1) the prompt layer (official example, copy it verbatim)
Delegate to a subagent only for large tasks that are genuinely independent and
parallelizable, such as a wide multi-file investigation. Do not delegate work you
can finish yourself in a handful of tool calls, and do not use subagents to verify
or double-check your own work. If one subagent can complete the task, use one
rather than several, and keep spawn counts low.

# (2) the hard caps (env in .claude/settings.json; defaults: depth 3 / 20 concurrent)
"env": { "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1",
         "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5" }
# The SDK adds a third: maxBudgetUsd / max_budget_usd -> error_max_budget_usd at the cap

The same document has a counterintuitive instruction: Opus 5 verifies its own work unprompted, so old lines like "use a subagent to double-check" should be removed — keeping them only causes over-verification and burns tokens. Note those two environment variables need Claude Code 2.1.217 or later.

Three costs that are easy to miss

• Descriptions are taxed too. Straight from the docs: when the combined descriptions of your custom subagents exceed 15,000 tokens, Claude Code warns you at startup. Detail belongs in the body, which loads only when that agent actually runs.
• A subagent cannot ask you anything. AskUserQuestion is unavailable inside subagents (so are EnterPlanMode, ScheduleWakeup and Workflow). Stuck, it guesses, and you see the guess in the report. Background subagents lose most built-in tools on top of that.
• Coordination is human work. The expensive part of that superpowers pipeline is not the implementers — it is the ledger, the conflict scan, the five-round cap, the final whole-branch review. Dispatching agents is one command; collecting them is an institution.

What to do instead of a subagent

1. Write a skill. If you want "a rule every step honors" rather than "this stretch I don't want to see" — cheaper, and you can watch it work.
2. Use a fork. /subtask when you need isolation without amnesia; the cost is inheriting every parent token.
3. Pin it as a hook. Don't dispatch an agent to do something deterministic (Skill 27 covers this).
4. Move up to Workflow. Orchestrating dozens of agents belongs in a script, not in a conversation.
5. Just do it yourself. That is the second sentence of the official delegation instruction: don't delegate what a handful of tool calls would finish.