Skills vs Subagents in Claude Code

A skill is instructions loaded into the context you’re already in. A subagent is a separate context that does the work and hands back a summary. Skills change how your agent works. Subagents change where the work happens.

People mix these up because they look identical from the outside. Both are markdown files with YAML frontmatter. Both live under .claude/. Both are things you write once and reuse. The similarity ends at the file format.

the difference is context

When a skill loads, its body goes into the conversation you’re having. Your agent reads the instructions and everything it does next is shaped by them. Same context window, same history, same files it already has open. You watch every step.

When a subagent starts, it gets a fresh context window. Anthropic’s subagent docs put it plainly: it “doesn’t see your conversation history, the skills you’ve already invoked, or the files Claude has already read.” Claude writes a delegation message summarizing the task, the subagent works from that, and only its final summary comes back. Everything in between stays in a window you never see.

A skill is a new set of instructions in the same head. A subagent is a second head that only tells you its conclusion.

what a skill looks like

Skills live at ~/.claude/skills/<name>/SKILL.md for everything you do, or .claude/skills/<name>/SKILL.md to scope one to a project:

---
description: Use when finalizing prose drafts. Strips cliché phrasing
  and flags patterns to add to the catalog.
---

# scrub-ai-tells

1. Read the draft.
2. Match against the catalog in `tells.md`.
3. Propose replacements inline, never rewrite silently.

Every frontmatter field is optional. description is the one that matters, because that’s the line the model reads when deciding whether to pull the skill in. The body stays out of context until the skill is actually used, so long reference material is close to free until you need it.

You invoke a skill by typing /name, or the agent loads it on its own when the description matches what you’re doing. Skills follow the Agent Skills open standard, so the same file works in more than one tool. Codex and other agents read the same shape.

Frontmatter is the part that isn’t free: it loads every turn so the model knows the skill exists. Twenty installed skills is twenty descriptions on every API call, which is why scoping skills per project starts to matter once you have a pile of them.

what a subagent looks like

Subagents live at .claude/agents/<name>.md or ~/.claude/agents/<name>.md:

---
name: silent-failure-hunter
description: Use after writing error handling, catch blocks, or
  fallback logic. Finds swallowed errors and inadequate reporting.
tools: Read, Grep, Glob
model: haiku
---

You audit error handling. For each catch block in the diff, report
whether the error is logged, surfaced to the user, and actionable.
Return a list of findings with file:line. No fixes, no rewrites.

Only name and description are required. tools restricts what the subagent can touch and inherits everything if you leave it off. model accepts sonnet, opus, haiku, fable, a full model ID, or inherit, which is the default. There’s also disallowedTools, maxTurns, and permissionMode if you want tighter limits.

The description is a routing instruction, not a job title. It’s the text Claude reads to decide whether to hand off, so write it as “use this when X happens,” not “an agent that does X.”

when a skill is the right call

• A procedure you want followed in the work you’re already doing. Deploy steps, a review checklist, a release process.
• A constraint on output you’re going to read. House style, naming conventions, a banned-words list.
• Reference material too long to sit in CLAUDE.md permanently.
• Anything where you want to see each step as it happens, because a skill’s work is your work.

when a subagent is the right call

• Output volume you don’t want in your window. Test runs, log processing, fetching docs. The verbose part stays over there and you get the failures.
• One bounded question with a small answer. “Which files call this function” is perfect. The subagent reads forty files, you get five paths.
• Work that should have less access than you do. A read-only auditor with tools: Read, Grep, Glob cannot edit anything, no matter what it decides.
• Grunt work a cheaper model handles fine. model: haiku on a search agent costs a fraction of the same search in your main session.
• Several independent investigations at once. Three subagents on three modules finish in the time one would take, because none of them needs the others’ answers.

using both together

They compose in two directions, and both are documented behavior rather than a trick.

A subagent can preload skills. The skills frontmatter field injects the full skill content into the subagent’s context at startup, not just the description:

---
name: copy-reviewer
description: Use when reviewing marketing or docs copy before it ships.
skills: scrub-ai-tells
---

Now the reviewer starts already knowing your style rules, in a context that doesn’t cost you anything. This is the pattern worth reaching for: the skill carries the standard, the subagent carries the isolation.

The other direction, a skill can run itself in a subagent. Add context: fork to a skill’s frontmatter and the skill body becomes the prompt driving a forked subagent instead of instructions for your current session. Useful for a long checklist whose intermediate output you don’t want. Note the tradeoff: a forked skill running in the background gets the narrower tool set that applies to background subagents, and background: false is how you keep the full set.

the two mistakes

Reaching for a subagent when a skill would do. The symptom is that you keep re-explaining. If the task only makes sense in light of the last twenty minutes of conversation, a subagent starts blind: it gets your CLAUDE.md files, a git status snapshot, and a delegation message that Claude wrote by summarizing something it might have summarized badly. You didn’t save context, you spent it writing a briefing.

Reaching for a skill when a subagent would do. The symptom is a context window full of output you’ll never read again. Forty files of grep results are still in there, still being sent on every turn, twenty turns after they stopped being relevant. That’s exactly the thing subagents exist to prevent.

quick comparison

	Skill	Subagent
Where it runs	Your current context	A fresh, isolated context
Sees your conversation	Yes	No
What comes back	Everything, live	A final summary
File location	.claude/skills/<name>/SKILL.md	.claude/agents/<name>.md
Required frontmatter	None (description recommended)	name, description
Can restrict tools	For the current turn	For its whole run
Can use a different model	For the current turn	Yes, per definition
Good for	Changing how work is done	Keeping work out of your window

what neither of them fixes

A subagent’s context is invisible by design, and that’s the whole point right up until it isn’t. You get the conclusion without the reasoning. For one lookup that’s fine. For five subagents whose findings you’re about to act on, you’re accepting summaries from processes you can’t inspect, and a subagent that misread something reports its misreading with the same confidence as a correct answer.

The fix isn’t a better subagent definition. It’s noticing when a piece of work has outgrown the format. If you’d want to watch it, read its reasoning, or interrupt it halfway, it shouldn’t be a subagent at all. It should be its own session, running where you can see it.

That’s the level crystl works at. Each shard is a full agent session with a visible transcript, so conversation history and the agent activity panel show what a worker actually did rather than what it chose to tell you, and big independent tasks get isolated shards with their own git worktree. Skills and subagents stay what they are, good tools for the two problems above. Everything larger goes to orchestration and parallel sessions.

Related reading: Claude Code subagents explained for the mechanics in depth, subagent best practices for how to scope one well, and Claude Code agents if you’re still untangling which of the four things people mean by “agent.”