Claude Skills vs Subagents in 2026: Which One To Reach For (7 Decision Rules)

Anthropic shipped Claude Skills and Subagents in the same season, wrote docs for each in isolation, and then let engineers argue on Discord about which one to reach for. I’ve spent the last two months rewiring my own harness around both, and I’ve watched myself pick wrong enough times to have opinions.

Here is the shortest version I can give you: Skills are procedures, Subagents are workers. A Skill is knowledge Claude reads when a task looks like it needs it. A Subagent is a separate Claude you dispatch, hand the work to, and get one summary back from. The two words sound similar, but they don’t produce the same monthly bill.

I built a small internal spreadsheet of 7 recurring tasks I actually do and forced myself to pick one tool for each. This post is that spreadsheet, with the reasoning.

The 7 rules, up front (SEO people, this is your snippet)

Task	Reach for	Why
Enforce a house code review checklist across every session	Skill	Passive knowledge — Claude reads it when a review is asked for
Investigate a 40-file blast radius before a refactor	Subagent	Returns one summary, doesn’t pollute your main context
Generate a JIRA ticket from a bug report using your team’s template	Skill	Deterministic procedure, no long-running exploration
Run three parallel design options and compare	Subagent	Genuine parallelism, each with its own context
Add a repeatable “make PR description from diff” flow	Skill	Same procedure every time, cheap to load
Deep-audit a legacy module for security issues	Subagent	Long, isolated read that would otherwise flood the main window
Standardize how Claude names commits across your monorepo	Skill	Applied on every commit, no exploration needed

If you are only here for the rules, you can leave now. I won’t be offended.

Why the naming is confusing

Every Claude Code user I’ve talked to had the same first reaction: “wait, isn’t a Subagent just a Skill that runs?” No.

Anthropic’s own explainer draws the line this way: Skills are folders of instructions Claude discovers on demand, Subagents are separate AI assistants with their own context windows. The comparison I found most useful comes from a phrase in the Verdent guide: a Skill is what a worker knows, a Subagent is a temporary specialist you hire. Let me unpack that.

A Skill is a SKILL.md file (plus optional resources) that sits in your project. Its name and one-line description load into the session at start. When Claude is deciding what to do next and sees a task that matches the description, it reads the full file. That is the entire lifecycle. No new process gets spawned, and you don’t pay for a fresh context window.

A Subagent is also declared at session start, with a name, description, and tool list. But when Claude decides to use it, it calls the Agent tool with a prompt string. That launches a separate Claude with its own context window, tools, and token budget. You get back its final message.

The asymmetry to keep in mind is what each one costs you just to have around. A Skill sits at about 100 tokens of metadata until something matches it, then loads under 5k. A Subagent is a separate API call with its own context — you pay to stand up a fresh Claude, system prompt and tool definitions included, before it reads one line of your code.

Distrust anyone who quotes you a flat per-spawn token number for that. The tool list is most of the fixed cost, and mine isn’t yours.

That asymmetry is what the rest of this post is about.

The one question that decides it

Before I built the 7-row table, I tried to find the one question that made the choice obvious. Here it is:

Does this task need its own context window?

• Yes → Subagent. The whole point is isolation: a long read, a parallel branch, a task whose intermediate reasoning you don’t want in your main history.
• No → Skill. You just want Claude to follow a procedure you’ve written down.

If your instinct says “Skill” but you also thought “…and Claude will keep 40 files in mind while it does this,” you probably want a Subagent. Those 40 files give it away.

Going the other direction: if you reached for “Subagent” but the whole task is “apply this template,” you probably want a Skill instead. Templates don’t need a fresh worker.

Where I’ve picked wrong

Two failure modes I’ve hit personally, so I know they’re easy to fall into.

Failure 1: Skill-as-workflow

I built a “release-notes” Skill that was supposed to (a) diff two tags, (b) group commits by scope, (c) draft release notes, (d) check them against the previous release’s tone, and (e) post to Slack. It worked, but it also filled my main context with 30k tokens of commit metadata every time I invoked it, which meant my next question came out dumber.

That was a Subagent’s job. The clue I missed was that the task ended by handing me back a summary, and anything that ends “here is a summary you’ll use” wants its own window.

Failure 2: Subagent-as-lookup

I built a “how-do-we-name-things” Subagent because I liked the idea of a specialist worker. Every time it fired, I stood up a fresh Claude — system prompt, tool definitions, the lot — to get back a two-sentence rule that lived in a 300-token file. My monthly bill noticed.

That was a Skill. The clue I missed was that I already had the answer written down. If you already know what Claude is going to say, you don’t need a fresh Claude to say it.

The seven, with the reasoning

Same rows as the table at the top, with the “why” opened up.

1. House code review checklist → Skill

The checklist doesn’t change per task; Claude reads it, applies it, moves on. There’s no exploration and no branching, and 400 lines of Skill is usually enough. Loading cost is basically zero until Claude decides to invoke it.

2. Blast radius before a refactor → Subagent

This is exactly what Subagents were built for. You want Claude to read 30-50 files, trace dependencies, and hand you a shortlist. You do not want those 30-50 files in your main context, because your next turn is “OK, refactor auth.py given that list.” Keeping the reading in a separate window is the whole point.

3. JIRA ticket from bug report → Skill

A template with slots to fill in. The template is the same every time, and Claude only needs to know that it exists. This is a Skill’s home turf: exactly the kind of procedural instruction Anthropic’s own steering guide says belongs in a Skill.

4. Parallel design options → Subagent, three of them

If you want three independent takes on a problem, you need three separate contexts. Otherwise the second option gets anchored to the first before it has a chance. Fan them out, collect the answers, and let the main Claude pick from them.

The cost is real — three fresh contexts instead of one — but the alternative is a single Claude anchoring on its first idea. For design work I’ll pay that.

5. PR description from diff → Skill

Same shape every time: read the diff, apply the house template, print. There is no exploration and no summary handoff, because the description is the output.

6. Legacy module security audit → Subagent

A long read (potentially thousands of lines) that ends in a single summary. This one fits Subagents almost by definition. If you try to do it in the main window, your next 20 turns will be worse.

7. Commit naming convention → Skill

This one is barely even a procedure; it’s more of a rule, and rules are exactly what Skills are for. The Skill description says “when writing commit messages, apply this convention,” and Claude reads it when writing commits.

When it’s ambiguous

Two categories where I don’t have a firm rule.

Migrations across a codebase. A one-file migration should stay as a Skill. Once you’re touching a hundred files, spawn a Subagent instead. The break point is roughly where the intermediate state gets bigger than you want in main context, which for me is around 15-20 files (though it depends on file size).

Research-then-write. When the research is deep and the write-up is short, use a Subagent for the research and let the main Claude write. Shallow reading (a couple of doc pages) with a long write-up is the opposite case: keep everything in main and use Skills for tone and structure.

The connection to Codex

I wrote a longer post a while back on how Claude Code and ChatGPT Codex compare as official agents, and the Skills-vs-Subagents question is where that comparison starts to bite. Codex doesn’t have this split at the same conceptual level. It has custom instructions and Agent Mode, but the two aren’t cleanly separated the way Anthropic’s Skills and Subagents are. If you’re picking a stack today and you want the split-brain model, Claude ships with it in the box; if you’d rather have one big fuzzy pool, Codex sits closer to that.

Neither is a wrong choice. The practical consequence, though, is that a team that has internalized the Skills-vs-Subagents distinction gets more out of Claude Code, while a team that hasn’t tends to burn tokens on Subagents that should have been Skills.

The one-second habit

I’ve started asking myself, before every custom capability I add: is this a fact or a job?

Facts are Skills. Jobs are Subagents.

That’s the whole post. The seven examples above are just the receipts.

If you want to keep going on the “how do I actually run Claude Code without lighting my bill on fire” thread, my book Practical Claude Code has a chapter on this exact split, plus the CLAUDE.md patterns I’ve settled on after a year of daily use.

Practical Claude Code: the field guide for engineers who use Claude Code every day.