The most common confusion after a week of using Claude Code
After a week using Claude Code, almost everyone lands on the same question: "if skills let me instruct the agent and subagents also do specialized work, why do both exist? When do I use each one?"
Short answer: skills and subagents solve different problems, even though both seem to teach the agent something. The long answer — this article — starts with architecture, goes through five real case studies, and ends with a criterion you can apply on the spot.
If you haven't seen each of them in isolation, read Slash Commands and Skills: customizing your Claude Code workflow and Subagents in Claude Code: orchestrating tasks in parallel first. From here on I assume you know the basics of both.
The difference nobody explains clearly
Skills and subagents live on completely different planes of Claude Code's architecture.
Skills are instructions + knowledge injected into the main agent's context. When a skill activates, the contents of SKILL.md (and its attached files) enter the current conversation window. The main Claude "reads" the skill as if you had pasted a manual, and starts following its guidance. There's no isolation: everything happens in the same process, in the same context window, with the same tools.
Subagents are separate processes with their own context. When you fire a subagent through Task, the main Claude pauses, a new agent is instantiated with its own context window, its own allowed tools, and its own system prompt. The subagent runs until it's done, returns a single message to the orchestrator, and dies. Nothing it read, thought or tried enters the orchestrator's context.
That asymmetry changes everything. Skills are knowledge sharing. Subagents are work delegation. They're different things. You may need one without needing the other.
The context-cost axis
Skills have a hidden cost: the description of each loaded skill stays permanently in the initial prompt, and if the skill activates, the whole body comes in too. In a long session with five active skills, you pay for all of them all the time. That's why the advice is to keep a few well-described skills — ideal is 5-10 well-focused ones, not 50 generic.
Subagents don't carry that continuous cost. They only consume tokens when fired, and the consumption stays inside the subagent's context — not in the orchestrator's. You can have 20 subagent types defined without penalizing any prompt that doesn't invoke them.
Practical rule: if the knowledge needs to be always available, use a skill; if it's an expensive process that only runs on demand, use a subagent.
The invocation axis
Skills activate by implicit semantic match. You don't invoke the skill; the model detects that your prompt matches the description of some installed skill and loads the content by itself. The trigger is linguistic: "I need to add a column to table X" activates a migrations skill, even if you never said "migration".
Subagents activate by explicit invocation from the orchestrator. The main Claude decides to call Task({subagent_type: "code-reviewer", ...}) and passes the full briefing. The subagent only exists because someone invoked it deliberately.
Practical rule: if the model decides from ambiguous context, it's a skill; if the orchestrator decides from a specific need (research, review, debug), it's a subagent.
Five case studies
Case 1: encoding the team's migration convention. You want any developer on the repo, when asking for a new migration, to get the right pattern (naming, RLS, rollback). Always-available knowledge, triggered by a natural linguistic cue. Skill.
Case 2: investigating where a feature lives in an unknown repo.
You need fast answers to exploratory questions, without filling the orchestrator's context with dozens of greps. Subagent (Explore).
Case 3: reviewing a sensitive diff with an independent eye.
You want a cold read, without the rationalizations the orchestrator has already absorbed. Subagent (code-reviewer).
Case 4: teaching the agent to write commits in the team's format. Every time the agent commits, it should follow conventional commits with the right scope. Skill — or, alternatively, a dedicated slash command if you prefer explicit invocation instead of automatic activation.
Case 5: running three parallel investigations before planning a big refactor.
Three different areas of the code, three angles, parallel work. Three subagents in parallel, all Explore or general-purpose. This pattern is the base of the fan-out orchestration described in Multi-agent orchestration patterns in Claude Code.
Where people get it wrong
Mistake 1: creating a subagent to replace a skill.
"I'll create a migration-writer subagent that knows how to write our migrations." Sounds reasonable, but it's bad: every migration now requires explicit invocation, you lose automatic activation, and the logic gets duplicated in a briefing for the subagent. Use a skill.
Mistake 2: creating a skill to replace a subagent.
"I'll create a critical-code-review skill with instructions on how to review diffs." Problem: the knowledge enters the orchestrator's context, which has already absorbed your perspective. You lose the cold read. And SKILL.md will compete for attention with every other task in the session. Use a subagent.
Mistake 3: skill with a bad description. "Supabase migrations" or "Test help" are useless descriptions. The model doesn't know when to activate. Descriptions must be explicit triggers: "Use when the user asks to create a migration, alter a table, or change an RLS policy." Without that, the skill will never activate at the right moment.
Mistake 4: creating a subagent instead of using one from the catalog.
Before creating your own type, look at the built-in catalog: code-reviewer, debugger, test-writer, security-auditor, Explore, Plan, refactorer, doc-writer. If one matches your case, use it — it comes with an optimized system prompt. Only create custom ones when the catalog really doesn't cover it, following the tutorial at Creating custom Subagents step by step.
Can they combine?
Yes — and that's where it gets elegant. A skill can instruct the orchestrator to fire specific subagents at specific moments. Example: a big-refactor-guard skill activates whenever the request involves "refactor" or "move X to Y", and its contents say "before starting, fire an Explore subagent to map the dependencies; then a Plan to draft the approach; only then implement". The skill encodes the process, the subagent does the heavy lifting. Both roles in harmony, not in competition.
The rule for combining them: skills teach when and how to delegate, subagents execute the delegation. If you keep that discipline, neither one runs over the other.
Next steps
Read the article on 10 essential skills for productivity if your next step is filling the skill arsenal. Read Creating custom Subagents if you want to write your first custom type. And once you have both in production, the article on multi-agent orchestration patterns shows how to combine them into fan-out/fan-in flows that scale to truly large tasks.
