Two Claude Code primitives. Two very different jobs. Here's the rule I use to pick between them.
Most devs still confuse these
Almost every Claude Code setup I review has the same bug: subagents doing the work of skills, and skills being skipped where they'd actually help.
The two primitives look similar from the outside. They do very different jobs.
The rule
Skill = knowledge you reuse.
Subagent = capability you delegate.
Everything else is examples.
Skill: durable knowledge the model reads every time
A skill is a folder in ~/.claude/skills/<name>/ with a SKILL.md and any supporting files. When you invoke it, Claude reads the whole folder into your current context.
My post-generator skill holds:
- 12 reference posts I admire, annotated with voice notes
- 16 researched excerpts from engineers I respect
- 12 human-writing patterns
- 5 AI tells to avoid
- Per-platform output templates (LinkedIn, X, Medium, Dev.to, Hashnode)
None of that is a task. It's what I want applied every time I draft a post. Skill territory.
Subagent: a focused job with isolated context
A subagent is a specialist you dispatch. It runs in its own context window, does the work, and returns a summary.
This afternoon I ran a researcher subagent that did 10 web searches to find AI tip-guide angles trending this week. It came back with 900 words I could act on.
If I'd done that in my main session, I'd have flushed maybe 30K tokens of tool output into my context — search results, page fetches, HTML — none of which I actually needed once the summary was written.
Subagent territory.
The quick test
Ask yourself: is this what to know or a job to do?
- Coding style rules → skill
- A lint-fix runner for a specific repo → subagent
- Your team's API design principles → skill
- Scanning a repo for security issues → subagent
- Your post-writing voice → skill
- Researching a topic and returning findings → subagent
Rule of thumb: if it's going to be referenced across many tasks, it's a skill. If it's going to be invoked once to produce a specific output and then exit, it's a subagent.
Why people get it wrong
The most common mistake I see: turning a rulebook into a subagent.
Someone writes a "code review agent" that's 500 lines of "always check X, reject Y, prefer Z." That's a skill wearing a subagent costume. You could have just written those rules as a skill and invoked it in your main session — same behavior, fewer tokens, simpler mental model.
The flip side is worse: stuffing genuine capability work into your main context. Tool output drowns your working context. You wanted to delegate; you actually just inlined.
Close
Stop building subagents for things that are really knowledge.
Stop cramming subagent work into your main context.
Top comments (0)