In short
Use a skill when you want reusable instructions to run in your main conversation, such as a review checklist or a deploy procedure. Use a subagent when work should be isolated in its own context, such as running noisy tests, researching a codebase or enforcing restricted tools. Skills add knowledge; subagents add a separate worker. They combine well, since a skill can run in a subagent.
The simple version
A skill is a set of instructions. It tells the current agent how to do something. Think of a recipe card.
A subagent is a separate worker. It gets its own context, carries out a task and reports back. Think of asking a colleague to go and look into something, then bringing you the summary.
This article uses Claude Code's terminology and documentation, but the concepts increasingly appear in other tools, such as Codex. Check how your own tool implements them.
Side by side
| Skill | Subagent | |
|---|---|---|
| What it is | Reusable instructions | A separate agent instance |
| Context | Runs in your conversation by default | Fresh, isolated context |
| Sees your chat history? | Yes | No, only what it's told |
| Output | Stays in your conversation | Returns a summary |
| Tool restrictions | Can pre-approve some tools | Can be limited with allow and deny lists |
| Model | Your session's, usually | Can be set for each subagent |
| Stored as | .claude/skills/name/SKILL.md | .claude/agents/name.md |
When to use a skill
Use a skill when:
- You keep repeating the same instructions
- You want a checklist or a procedure applied in context
- The work needs back-and-forth with you
- The output should be visible in the main conversation
Example:
---
name: review-migration
description: Reviews database migrations for safety. Use when creating or changing a migration file.
---
Check this migration for:
1. Locks on large tables
2. Non-nullable columns added without defaults
3. A working way to roll back
List problems by severity.
Anthropic's docs explain that the body loads only when used, so long reference material costs little until it's needed.
When to use a subagent
The documentation's guidance is to use a subagent when:
- The task produces verbose output that you don't need in your main context
- You want to enforce tool restrictions or permissions
- The work is self-contained, and can return a summary
Example:
---
name: test-runner
description: Runs the test suite and reports failures. Use after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---
Run the tests. Report only failing tests, each with
the error message and the file and line number.
Do not change any code.
The output from thousands of lines of test logs stays within that subagent's context, and your main conversation only receives the failures. It runs on a cheaper model too, and it can't edit files, because Write and Edit aren't in its tools list.
… now part of every later request
cart.test.ts:17, tax.test.ts:9
A quick decision guide
| You want to... | Use |
|---|---|
| Apply your team's PR checklist to the current change | Skill |
| Search a big codebase, without filling your context | Subagent |
| Follow a release procedure with your approval at each step | Skill |
| Run a noisy test suite and get a summary | Subagent |
| Teach the agent your writing style | Skill |
| Get an independent code review with no earlier bias | Subagent |
| Limit an agent to read-only tools | Subagent |
| Save a set of always-true project facts | Neither; use CLAUDE.md |
How they combine
They aren't competing options.
- A skill can run in a subagent. In Claude Code, setting
context: forkin a skill's frontmatter runs it in an isolated subagent. You get a reusable procedure along with isolated context. - A subagent can load skills. Its configuration can give it a set of skills to use, so a “reviewer” subagent can follow your review skill.
- Parallel work. Several subagents can each handle a separate part of a task. Review the output carefully, since quality and cost both need watching.
Why independence matters
A subagent doesn't see the discussion that led to the code. That's a real advantage for reviews: a reviewer that hasn't been part of your reasoning is less likely to accept the same mistaken assumptions. It's a disadvantage for tasks that depend on nuance from your conversation, unless you pass that context on explicitly. So write the delegation message as you would a brief for a new colleague.
Cost
Neither is free. Skills add their content to your conversation once loaded. Subagents draw on your usage, with their own requests on top of your main conversation. Using subagents to contain verbose output can save context overall, particularly with a cheaper model. Spawning many of them for small jobs is wasteful. Anthropic reports that agent teams can use around 7x more tokens than standard sessions. See Claude Code pricing explained.
Common mistakes
- A subagent for a quick edit. The overhead isn't worth it. Do small changes in the main conversation.
- A skill that dumps huge output into your context, when it should be a subagent.
- Vague descriptions. Both are selected partly through their description, so make that specific.
- Expecting a subagent to remember your chat. It starts fresh, so tell it what it needs.
- Too many of either. Start with two or three that you actually use, then add more when you notice repeated work.
- Treating them as security boundaries without checking. Tool restrictions help, but review what access is really granted. Don't give an agent production credentials.
Start small: make one skill for your most repeated procedure, and one read-only subagent for test runs. If you'd like help setting up a workflow like this for your team, book a call.
Common questions
What is the difference between a skill and a subagent?
A skill is a set of reusable instructions that usually runs in your current conversation. A subagent is a separate agent, with its own fresh context and permissions, that carries out a task and returns a summary to the main conversation.
When should I use a subagent rather than a skill?
Use a subagent when work produces a lot of output, is self-contained, or needs restricted tools, such as running tests or researching a codebase. Use a skill for procedures you want applied in context, particularly with your input along the way.
Can a skill run as a subagent?
In Claude Code, yes. Setting context: fork in a skill's frontmatter runs it in a subagent, and an agent field can choose the type. Subagents can also be configured to load particular skills, so the two combine well.
Do subagents use more tokens?
They make their own requests, which count towards your usage. But they can save context in your main conversation by keeping verbose work separate, particularly when using a cheaper model. Running many in parallel can get expensive, so use them deliberately.