What is the difference between Claude Code skills and subagents?
TL;DR
A skill (`SKILL.md`) loads reusable domain instructions into the active context window when triggered. A subagent runs inside its own isolated context window with dedicated tool permissions and returns a summary.
Claude Code provides two distinct primitives for scaling complex work: skills and subagents. Choosing the right one protects your context window and keeps token spend predictable.
How a skill works (SKILL.md)
A skill is a folder at .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (personal). At startup, Claude reads only the YAML name and description. When your task matches that description, Claude loads the full markdown instructions and optional helper scripts into the current conversation context.
Use a skill when the main agent needs domain standards while editing files directly:
- Next.js App Router conventions and Server Component rules
- Brand editorial rules and accessibility checklists
- Deterministic local verification scripts in
scripts/
How a subagent works (.claude/agents/)
A subagent spawns a separate context window with its own system prompt, model choice, and restricted tool list. It performs bounded work—such as scanning 40 files or running an independent security review—and returns only the final report to your main session.
Use a subagent when the intermediate tool output would pollute your primary context:
- Codebase-wide exploration and dependency mapping
- Independent code or editorial verification (dual-reviewer gates)
- Parallel test debugging across separate packages
Decision rule
Keep instructions in a skill when they guide how the active maker writes code. Delegate to a subagent when the task requires heavy reading, parallel execution, or an independent reviewer.