← All guides

claude code skills vs subagents

Claude Code Skills vs Subagents: Which One to Use and When

By Neo Zino - builder of ClockedCode·October 24, 2026·14 min read

Skill or subagent? One test, three tie-breakers and the traps (fork mode, compaction, preloading) that decide where a Claude Code task belongs.

TL;DR: Claude Code skills vs subagents comes down to one question: do you want to read everything the task produces? Yes: write a skill, its instructions stay in your conversation. No, you only want the conclusion: write a subagent, it works in its own context window and returns a summary. Anything with side effects, such as a deploy, is a skill locked with disable-model-invocation: true.

The choice between Claude Code skills vs subagents comes down to one question: do you want to read everything the task produces? If you do, write it as a skill, and its instructions stay in your conversation. If the useful result is a short summary on top of a large pile of search output, write it as a subagent. A subagent works in its own context window and returns only its findings. If the task has side effects, such as a deploy, make it a skill with disable-model-invocation: true so only you can trigger it.

What actually separates a skill from a subagent?

The difference is where the work happens. A subagent runs in a separate context window, and a skill runs inside yours. Primeline's August 2026 breakdown treats that isolation as the core distinction, with every other difference following from it (primeline.cc).

Skillsmith's January 2026 framework uses a different frame: agents define behavior, skills define tools (skillsmith.app). That framing helps if you are designing a large multi-agent product. For a single repeatable task you want to write down once, use the context-window framing. It tells you where the tokens go, and token load decides whether Claude is still following your instructions an hour into a session.

One piece of older vocabulary no longer applies. Custom commands are now part of skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md produce the same /deploy command with identical behavior (primeline.cc). If you already have slash commands, you already have skills. That leaves two options: load instructions into your conversation, or send the work to a separate context that reports back.

What does a skill cost your context, and what does a subagent save?

A skill costs almost nothing until you use it. After you invoke it, it stays in your context. Skillsmith's January 2026 framework gives rough token figures for three levels of skill loading (skillsmith.app):

• Registry level: name and description, loaded into every context, about 50 tokens per skill.
• Header level: metadata and trigger conditions, loaded when a task appears relevant, about 500 tokens.
• Execution level: full instructions, scripts and templates, loaded only on invocation, about 5-15K tokens.

Most of the cost comes from the execution level. According to Primeline (2026), an invoked skill's rendered text becomes a message in your conversation and remains there, and Claude does not go back to the file on later turns (primeline.cc). Two things follow. Write skills as standing rules, not as one-time steps. And treat a long skill as a cost you carry until the session ends, even after you have finished the task it was for.

Total load matters because models get worse as context fills up. Skillsmith (2026) offers an illustration, not a measured study: a detailed agent file, a large skill file and accumulated history can together pass 100,000 tokens before any real work begins (skillsmith.app). The same source describes what happens next: instructions get ignored, output quality drops, and the model loses track of constraints you set early on (skillsmith.app).

A subagent avoids most of this. Its file reads, greps and dead ends stay in its own window, and only the conclusion comes back to yours. If the work is noisy, a subagent keeps all of that noise out of your context. If the work is short and you want to see every line anyway, a subagent saves nothing and adds a handoff.

Skill or subagent? Run the one-question test, then the three tie-breakers

Go through these in order and stop at the first one that gives you a clear answer.

1. Ask: do I want to read everything this produces? This is Primeline's test (2026). If the answer is yes, it's a skill. If the part you care about is one paragraph on top of a mountain of grep output, it's a subagent (primeline.cc). This question settles most tasks. A review routine where you read every comment is a skill. A sweep to find every call to the old payments API is a subagent.

2. Tie-breaker one: does the task need different permissions? Skillsmith (2026) lists separate permission scopes, such as read-only versus write, as a reason for a sub-agent (skillsmith.app). An auditor that should never edit files makes a good subagent, because you can restrict its tools without restricting your main session.

3. Tie-breaker two: could a cheaper or faster model do it? Skillsmith (2026) also lists handing specific subtasks to cheaper or faster models as a reason for a sub-agent (skillsmith.app). Bulk classification, log triage and file inventories don't need your main model. A skill runs on whatever model your session is using.

4. Tie-breaker three: is it a standing rule or a one-off job? A skill's content stays in the conversation and Claude does not re-read the file on later turns (primeline.cc). That makes skills a good fit for rules that should apply to every later turn, such as "lint before committing" or "use our error-handling pattern". One-off research, where you want the answer and then never think about it again, belongs in a subagent.

5. If it's a skill with side effects, lock it. Set disable-model-invocation: true. Primeline (2026) recommends this for anything with side effects, so that Claude can't decide by itself that your code is ready to deploy (primeline.cc).

6. Don't split a skill early. Skillsmith (2026) cites a practitioner guideline of decomposing a parent skill into sub-skills once it becomes unwieldy, above roughly 500 lines, and calls splitting before that point premature decomposition that adds complexity without benefit (skillsmith.app). Until a skill reaches that size, keep it in one file.

If you still can't decide, start with a skill. Skillsmith (2026) recommends beginning with one agent and one skill, then adding sub-agents when context overflows. You'll know it has overflowed when outputs degrade and instructions get ignored (skillsmith.app). A skill is faster to write and easier to debug, and turning it into a subagent later is a small change.

Skills and subagents side by side

Verdict by reader:

• You run one main session all day and add rules as you go: use skills for standing rules and team conventions. Keep each one short, because you carry it all day.
• You do codebase-wide audits, migrations or research: use subagents. The grep output stays in their windows and you get the summary.
• You have anything that deploys, publishes, migrates a database or sends messages: use a skill with disable-model-invocation: true. Manual-only triggering matters more than context savings.
• You want strict tool limits or a cheaper model for bulk work: use a subagent. A skill can't do either.

When a skill is the wrong choice: the task produces a lot of intermediate output you will never read, or you run many skills in one long session and compaction keeps dropping the early ones.

When a subagent is the wrong choice: you need to see every step (code review, working through a tricky refactor together), the task is short enough that the handoff costs more than it saves, or the instructions need to shape your main conversation for the rest of the day. A subagent's instructions never stay in your context.

A worked example: the same audit task built both ways

Take a common request: "audit the codebase for every use of the deprecated logger and tell me what to migrate."

Built as a skill. You type /audit-logger. The skill's full text enters your conversation and stays there (primeline.cc). Claude greps, opens files and reads call sites, and all of that output lands in your context too. What you actually need is a short file list and a migration note. To get it, you have taken on the skill text plus a long trail of search results. The test-convention rule you gave earlier is now buried far back in the context, which is where Skillsmith (2026) says models start losing early constraints (skillsmith.app).

Built as a subagent. The same instructions live in a subagent definition with read-only tools. Claude delegates, the subagent does the grepping in its own window, and you get back one paragraph and a file list. The task fails the read-everything test, since you never wanted the grep output, only the conclusion (primeline.cc), so a subagent is the right fit.

Skillsmith's January 2026 illustration shows the scale of the difference. In their naive setup, a React agent that also loads a Linear skill during implementation reaches 80K+ tokens, with diluted attention (skillsmith.app). In the delegation pattern, an orchestrator spawns each specialist with only the scope it needs (skillsmith.app), and the React sub-agent's context drops to about 15K tokens, covering agent behavior, the React skill and the specific component (skillsmith.app). These are illustrative figures, not benchmarks. What matters is the ratio: scoping each specialist cut its context to a fraction of the combined load.

Now take the deploy checklist for the same project. It passes the test: you want to see every step, every check result and every confirmation prompt. It also has side effects. So it is a skill, with disable-model-invocation: true, so that Claude can't decide by itself that your branch is ready to ship (primeline.cc). The same project produces two tasks with two different answers, and one question decides both.

Where do skills and subagents overlap on purpose?

Skills and subagents are designed to work together. A subagent can preload skills, so your audit subagent can start with your team's code-style skill already in its context. You get a specialist that knows your conventions, and those conventions don't take up space in your main session.

There is a catch. Skills marked disable-model-invocation: true are left out when a subagent preloads its skills (primeline.cc). If you locked a skill so Claude can't fire it by itself, and then listed it in a subagent's skills, the subagent won't have it. Primeline (2026) notes that this is easy to trip over (primeline.cc). The fix is to split the skill in two. Keep the risky action (deploy, publish) in a locked skill you trigger by hand. Put the read-only knowledge (checklist, conventions) in a separate skill without that flag, which the subagent can preload.

Two more overlaps affect naming and delegation. Commands and skills are now the same mechanism (primeline.cc), so don't keep a .claude/commands/ version and a .claude/skills/ version of the same workflow, because both map to the same slash command. Skills packaged inside a plugin get a namespace prefix. A hello skill in a plugin named my-tool becomes /my-tool:hello, so installing a plugin can't quietly override a skill you already had (primeline.cc).

On the subagent side, always fill in the description field. Claude uses it to decide whether to delegate at all (primeline.cc). A subagent with a vague description won't get used, and nothing will tell you.

Which traps make a skill or subagent silently misbehave?

Go through this list whenever a skill "stops working" or a subagent seems to know things it shouldn't.

• Skill dropped after compaction. Per Primeline (2026), auto-compaction brings back only the latest invocation of each skill, keeps its first 5,000 tokens, and gives all returning skills a shared 25,000-token budget, filled newest-first (primeline.cc). Invoke enough skills in one session and the oldest disappear completely (primeline.cc). Fix: invoke the skill again. Prevent: put the critical rules in the first 5,000 tokens of the skill file.
• Subagent inherits your whole conversation. From v2.1.232, interactive sessions have fork mode enabled by default, and Claude can start a fork by itself by asking for the fork subagent type (primeline.cc). A fork carries your full context, which is the "Context Hoarder" anti-pattern Skillsmith (2026) warns about: sub-agents that inherit full parent context defeat the purpose of delegating (skillsmith.app).
• Same setup behaves differently in scripts. Fork mode defaults to off in -p and in the Agent SDK (primeline.cc), so a subagent that behaves one way interactively may behave differently in CI. Test it in the mode you will actually run it in.
• Fork mode fix: pick one. Setting CLAUDE_CODE_FORK_SUBAGENT=0 disables fork mode in every session (primeline.cc). Alternatively, add Agent(fork) to your permission denies. That keeps fork mode available but stops Claude from starting forks on its own, and Primeline (2026) considers it the option most people actually want (primeline.cc). I agree, because you keep manual forks for the occasional case where you want one.
• The God Agent. A single huge agent file holding every behavior, skill and piece of context breaks down as complexity grows (Skillsmith, 2026) (skillsmith.app). If your CLAUDE.md or main agent has become a dumping ground, move the task-specific parts into skills.
• Premature decomposition. Splitting into sub-skills before the parent reaches about 500 lines adds complexity without benefit (skillsmith.app). Several small skills that always run together should be one skill.
• Locked skill missing from a subagent. See the overlap section: skills with disable-model-invocation: true are skipped during preloading (primeline.cc).

What should you build or install first?

Start with one skill for the task you repeat most, following Skillsmith's (2026) "one agent, one skill" advice (skillsmith.app). Our Claude Code skills setup guide covers the file layout and frontmatter. Use the skill for a while. Add a subagent when you see the signal Skillsmith describes, which is degrading outputs and ignored instructions (skillsmith.app). Also add one when a task clearly fails Primeline's read-everything test (primeline.cc).

When you build that first subagent, How to Use Subagents in Claude Code walks through definition and delegation. The Claude Code Subagent Generator gives you a starting file with the description and tool scope filled in. That matters because the description field is what Claude reads to decide whether to delegate at all (primeline.cc). If you later run several agents in parallel, set up git isolation first. Parallel agents can collide on the same .git state, and git worktrees give each agent its own working directory while sharing repository history (Skillsmith, 2026) (skillsmith.app). The agent teams setup guide covers that setup.

Your next step: take the task you were about to write down and ask whether you want to read everything it produces. Then create either .claude/skills/<name>/SKILL.md or a subagent definition based on the answer.