Subagents vs Skills: When to Use Each

A subagent is a separate worker: it runs a task in its own context window with its own tools and returns only a summary. A skill is a set of instructions, in a SKILL.md file, that the current agent loads when relevant. Use a subagent when a side task would flood your conversation. Use a skill when you want the same job done the same way every time. They combine well. Checked 31 October 2026 against Claude Code's docs.

The short version

What each is

Subagents

Claude Code's docs say subagents are specialised AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access and independent permissions. When Claude meets a task that matches a subagent's description, it delegates, and the subagent works independently and returns results. The docs say to use one when a side task would flood your main conversation with search results, logs or file contents you will not reference again: the subagent does the work in its own context and returns only the summary. Define a custom subagent when you keep spawning the same kind of worker with the same instructions.

Built-in subagents exist. Explore searches and understands a codebase without making changes, with a thoroughness level of quick, medium or very thorough. A general-purpose subagent handles tasks that need both exploration and modification. Plan is another. A custom subagent is a markdown file with frontmatter, kept in ~/.claude/agents/ for all projects or .claude/agents/ for one. The docs' example has a name, a description, a tools list and a model:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

The body of the file is the subagent's system prompt. Our listings are subagents, the code reviewer subagent and the debugger subagent.

Skills

The docs say skills extend what Claude can do: create a SKILL.md file with instructions and Claude adds it to its toolkit. Claude uses a skill when relevant, or you invoke it with /skill-name. Skills follow the Agent Skills open standard, which works across multiple AI tools, and Claude Code extends it with invocation control, subagent execution and dynamic context injection.

Skills live in a folder per skill: ~/.claude/skills/<name>/SKILL.md for personal use, .claude/skills/<name>/SKILL.md for a project (commit it so your team gets it), plus enterprise and nested locations. A folder can hold supporting files beside SKILL.md. The docs note that custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Our listings are skills, commands and the skill creator.

The difference in a sentence: a subagent is who does the work; a skill is how the work is done.

Side-by-side facts

Context: the real difference

Both are about managing an agent's context window, in opposite ways.

A subagent keeps context out. Its research, file reads and logs stay in its own window, and only the summary comes back. That keeps your main conversation clean and your main model focused. The docs' context window visualisation shows a session where a subagent handles research in its own window.

A skill brings context in, on demand. It adds instructions to the conversation only when relevant. Claude Code's docs list unused skills, MCP servers and plugins in the extensions that cost context, and recommend keeping them lean. A skill's description is part of what Claude sees to decide whether to use it, so keep descriptions short and specific. The docs warn that when the combined descriptions of your custom subagents exceed 15,000 tokens, Claude Code shows a warning at startup.

So: if your problem is too much information, reach for a subagent. If your problem is inconsistent behaviour, reach for a skill.

Cost and limits

Subagents are not free. The docs say each one sends its own requests, which count toward the same usage limits as your main conversation. A research subagent that reads fifty files still spends those tokens. What you save is the clutter in the main conversation, which means later turns carry less context.

Skills cost their text. A short skill is cheap. A long one adds its full text to the conversation every time it loads. Supporting files in the skill's folder are the way to keep the main file short: the instructions point to a reference file that is read only when needed.

You can control cost by model. A subagent definition can set model: haiku or another model, so routine work runs on a cheaper one. The docs say a subagent named Explore overrides the built-in and keeps its own model field, so you can run exploration on a lower-cost model. See Claude Opus vs Sonnet for the model trade.

Combining them

The docs describe running skills in a subagent. In a skill's frontmatter, context: fork makes it run in a forked subagent context, and disable-model-invocation: true stops Claude from calling it on its own, so only you can trigger it with a slash command. That gives you a procedure (the skill) running in an isolated worker (the subagent). Useful for a heavy task such as a code review: the review steps live in the skill, and the file reads happen in the subagent's context.

A pattern that works:

1. Write the procedure as a skill, with checks and an output format.
2. Run it in a forked context if it reads a lot of files.
3. Let the main conversation receive only the summary.

Subagents can also preload skills,, so a specialist worker starts with the procedures it needs.

Parallel work and other options

Subagents work within a single session. The docs point to background agents for running many independent sessions in parallel and monitoring them from one place, and to cross-session messaging for separate sessions that pass messages to each other. If your goal is parallelism rather than isolation, those are the features to read.

Other tools have equivalents. Many agents support the Agent Skills standard or a similar instruction file, and some have their own worker concepts. See skills vs MCP for how skills differ from tool servers, and MCP vs API for the tool side.

A worked setup: a review workflow

Say your team wants every change reviewed the same way before merge.

1. Write the skill. A review-diff skill states the steps: read the diff, check for missing tests, look for changed function signatures, list risks in order of severity, and answer in a fixed format. Put the team's checklist in a supporting file next to SKILL.md, so the main file stays short.
2. Choose how it runs. If your diffs are big, set the skill to run in a forked context so the file reads happen in a subagent. Stop Claude from calling it on its own, so a review happens only when someone types the slash command.
3. Limit the worker. If you also want a standing reviewer, create a subagent with read-only tools. It can look but not edit, which is the right default for review.
4. Test on an old change. Run it on a pull request you already know well. If it misses the problem you remember, tighten the checklist.
5. Commit it. Put the skill and subagent in .claude/ in the repository, so the team shares them, and note in your contributing guide what they do.
6. Review the reviewer. After a month, read a few of its outputs against what human reviewers said.

This takes an hour and gives you a repeatable step. The same pattern works for release notes, migration checks and onboarding tasks.

When to use which: examples

Privacy and safety

Subagents have independent permissions. That is a feature: you can give a reviewer subagent only Read, Grep and Glob, so it cannot change files. Skills inherit the session's permissions unless run in a subagent, so a skill that runs shell commands should be reviewed like any script. Both are text files in your repository, which means they can carry prompt-injection risks if you copy them from strangers. Read a skill or subagent file before you install it, and prefer ones you wrote or can audit. Project files committed to a repository run for everyone who clones it.

For data, nothing in either changes where your prompts go: they still go to your model provider. See Claude Code for its data-use terms and Claude vs Claude Code for how the product relates to the model.

Limits and gotchas

• Subagents spend usage. They do not make a task free.
• Descriptions matter. A vague description means Claude picks the wrong worker or skill, or none.
• Too many descriptions cost context. The docs warn above 15,000 tokens for custom subagent descriptions.
• New directories need a restart. If ~/.claude/agents/ did not exist when the session began, the running session will not see a subagent you add.
• Nested skills load late. Skills below your starting directory load only when Claude touches files there.
• Skills are shared when committed. A project skill goes to your whole team.
• Do not duplicate `CLAUDE.md`. Put always-on rules in CLAUDE.md, and procedures that are used sometimes in skills.

Four questions that pick one

Ask these in order, and stop at the first yes.

1. Will the work read or produce a lot you do not want in this conversation? Searching a large repo, reading logs and scanning many files all qualify. Use a subagent, so the noise stays in its window and a summary comes back.
2. Do you want the same steps done the same way every time? A commit message format, a release checklist and a component scaffold all qualify. Use a skill.
3. Does the worker need fewer powers than the main session? A reviewer that should look but never edit qualifies. Use a subagent with a short tool list.
4. Do you need both a fixed procedure and isolation? A heavy review run qualifies. Use a skill that runs in a forked context, as in the combining section.

If none of the four applies, a few lines in CLAUDE.md are probably enough, and adding either feature is more setup than the job deserves.

Writing a description the agent will match

The agent picks a subagent or a skill from its description, so the description does most of the work. The same advice applies to both.

• Start with what it does, in one clause, and follow with when to use it, as in the code-improver example above: "Use after writing or modifying code."
• Use the words a user would type, not internal jargon. If your team says "release notes," do not write "changelog artefact generation."
• Say what it is not for, when two workers sit close together. One extra sentence prevents the wrong pick.
• Keep every description short. The docs warn above 15,000 tokens of custom subagent descriptions, so many long ones crowd out your actual work.
• Test by asking in plain words. If the agent does not choose it when you describe the task naturally, the description needs work, not the body.

Questions people ask

Can a subagent use a skill? The page above covers running skills inside a forked subagent context, and notes subagents can preload skills, with the exact frontmatter field still to confirm.

Do subagents make a task cheaper? No. Each sends its own requests, which count toward your usage. They protect your context, and you can lower the cost by giving routine workers a cheaper model.

Which should I write first? A skill, if you have a procedure you repeat. A subagent, if you have a task that floods your conversation. Many projects need one of each within a month.

Our take

Treat them as two tools for two problems. If a task produces output you do not want in your conversation, give it to a subagent. If a task needs to be done the same way every time, write a skill. Most mature setups end up with a few of each, and a skill or two that run in a subagent.

We did not measure token savings, and we make no claims about how much either saves. The descriptions here come from Claude Code's own docs on 31 October 2026, and the open points are marked. Start with one skill for something you type often and one subagent for something noisy, and check your usage screen before and after.

Related pages

• Skills vs MCP
• Subagents and skills
• Claude Code
• MCP vs API