Claude Code skills vs. subagents: when to use each

A skill is reusable content — instructions, knowledge, a workflow — that loads into whatever context is running. A subagent is an isolated worker with its own context window that does a job and returns a summary. Skills answer "what should Claude know here." Subagents answer "where should this work happen."

They are not alternatives competing for the same slot. The most useful setups combine them, and the combination runs in both directions.

The core difference

Aspect	Skill	Subagent
What it is	Reusable instructions, knowledge, or workflows	Isolated worker with its own context
Key benefit	Share content across contexts	Context isolation — only a summary returns
Context impact	Adds to your main window	Separate window, its own input and output tokens
Invoked by	You typing /<name>, or Claude matching the description	Claude delegating, or you naming it explicitly
Configuration	SKILL.md frontmatter and body	.claude/agents/*.md frontmatter and system prompt
Best for	Reference material, invocable workflows	Work that reads many files, parallel tasks, specialised workers

If skills themselves are new, start with what are AI agent skills.

Reach for a skill when the problem is knowledge

Skills come in two shapes. Reference skills provide knowledge Claude uses throughout a session — your API style guide, a database schema, a set of conventions. Action skills tell Claude to do something specific — a /deploy workflow, a /release checklist.

Both are cheap. By default a skill's description loads at session start so Claude can decide when it is relevant, and the body loads only when it is used. A long reference document costs a sentence until someone needs it.

Use a skill when:

• the content is the same every time and the context around it varies;
• you want to trigger it by name;
• more than one kind of session needs it;
• it is knowledge rather than a task.

Set disable-model-invocation: true for skills with side effects. That hides the skill from Claude entirely until you invoke it, which both prevents surprise execution and drops its context cost to zero.

Reach for a subagent when the problem is context

A subagent starts with a fresh, isolated context containing its own system prompt — not the Claude Code system prompt — plus CLAUDE.md, git status, the full content of any preloaded skills, and whatever the delegating message passes in. It does the work and returns a summary.

Use a subagent when:

• the task will read dozens of files whose contents you never need to see again;
• several independent investigations can run at once;
• the work needs a different model, tool set, or permission mode than your session;
• your main context is filling up with output that has served its purpose.

The canonical case is exploration. A research task that reads forty files and returns eight lines costs your main conversation eight lines.

Configuring a subagent

A subagent is a markdown file with YAML frontmatter; the body becomes its system prompt.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Only name and description are required. The fields that change behaviour most:

Field	What it does
tools	The tools available. Inherits everything if omitted.
disallowedTools	Removes tools from the inherited or specified list.
model	sonnet, opus, haiku, fable, a full model ID, or inherit.
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, or plan.
maxTurns	Stops the subagent after N agentic turns; output is marked partial and can be resumed.
skills	Skills preloaded in full at startup.
mcpServers	MCP servers available to this subagent only.
memory	user, project, or local — enables cross-session learning.
omitClaudeMd	Launches without user, project, and local CLAUDE.md files.
isolation	worktree gives the subagent its own git worktree copy of the repository.
background	Keeps the subagent in the background even when Claude asks to run it in the foreground.

Claude Code watches ~/.claude/agents/ and .claude/agents/, so edits apply within seconds with no restart. Three cases still need one: creating the first agent file in a directory that did not exist at session start, editing agents under a directory added with --add-dir, and sessions started with --disable-slash-commands.

A note on tools: to preload skills, use the skills field rather than listing Skill in tools. Those do different things — one injects content, the other grants the ability to go looking.

permissionMode is where the real decision is

tools narrows what a subagent can reach. permissionMode decides whether a person is asked before it acts. A subagent with a broad tool set and bypassPermissions is an agent acting unsupervised, and it should exist only when you have decided that deliberately.

A read-only investigator is the safe default shape:

---
name: dependency-auditor
description: Traces how a package is used across the repository
tools: Read, Glob, Grep
model: haiku
omitClaudeMd: true
---

omitClaudeMd is worth knowing about here. A subagent that takes everything it needs from the delegation prompt does not need your project conventions in its context, and leaving them out keeps it small and fast. Managed policy files still load.

Composing them, in both directions

The two mechanisms meet in two distinct patterns, and they are not interchangeable.

Approach	System prompt	Task	Also loads
Skill with context: fork	From the agent type	The SKILL.md content	CLAUDE.md, per the agent's startup context
Subagent with skills field	The subagent's markdown body	Claude's delegation message	Preloaded skills + CLAUDE.md

A skill that runs in a subagent. Add context: fork and name an agent. Claude Code starts a subagent of that type and hands it the skill content as its prompt.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Three details about this that catch people out:

• The subagent does not see your conversation. Despite the name, context: fork is not a fork of the current conversation. The skill's instructions have to stand on their own. When the task depends on what you have been discussing, fork the conversation instead.
• It only makes sense for skills with an actual task. A skill containing guidelines — "use these API conventions" — gives the subagent material and no prompt, and it returns nothing useful.
• It runs in the background by default, so you keep working and the result arrives when it completes. Set background: false to wait for it in the same turn. A backgrounded fork also runs with the narrower tool set that applies to background subagents, so set background: false if your steps need a tool outside that set.

One operational consequence: a forked skill running in the background applies its edits outside your session's checkpoints, so /rewind will not undo them. Use git.

A subagent that preloads skills. The inverse. The skills field injects full skill content into the subagent's context at startup, so a specialist worker arrives already knowing your conventions. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool.

---
name: api-reviewer
description: Reviews API changes against our conventions
tools: Read, Glob, Grep
skills: api-style-guide, error-format
---

Note that disable-model-invocation: true on a skill also prevents it from being preloaded into subagents — which is usually what you want for side-effecting skills, and occasionally a surprise.

Which one to choose

Work through these in order:

1. Is it knowledge that several sessions need? → Skill.
2. Will the work generate output you will never reference again? → Subagent.
3. Do you want to trigger it by name? → Skill. Add context: fork if it should also be isolated.
4. Does it need different tools, model, or permissions than your session? → Subagent.
5. Should several independent investigations run at once? → Subagents, in parallel.
6. Does a worker need your conventions? → Subagent with skills.

If a job outgrows a handful of subagents, or you want findings cross-checked before you see them, that is the point where a dynamic workflow — a script Claude writes that runs many subagents in the background — becomes the right tool instead.

Precedence, when names collide

Skills and subagents both override by name rather than merging, and the priority orders differ:

• Skills: managed > user > project. Plugin skills are namespaced as /plugin-name:skill-name, so they avoid the conflict entirely.
• Subagents: managed > CLI flag > project > user > plugin.

The practical consequence shows up after migrating configuration into a plugin: project and user .claude/agents/ definitions override same-named plugin agents, so the plugin version only takes effect once the originals are removed. Plugin skills behave differently — the original /name and the namespaced /plugin-name:name both remain available. If you are packaging either for distribution, Claude skills vs. connectors vs. plugins covers the packaging layer.

A setup that uses both well

A team working on a typed monorepo might land on:

• CLAUDE.md — build commands, layout, "use pnpm."
• A /release skill — the eleven-step checklist, disable-model-invocation: true so only a person starts it.
• An api-style reference skill — loaded when Claude touches the API, via paths frontmatter.
• An Explore-based research skill with context: fork — codebase questions answered without filling the main window.
• A code-reviewer subagent — Read, Glob, Grep only, preloading api-style, so review never edits anything.
• A migration-runner subagent with isolation: worktree — risky changes land in a throwaway copy of the repository first.

Each piece is doing the thing it is actually good at, which is the point.

Next step: Explore reusable Claude skills on LLM Mart before creating a separate worker for knowledge that could load on demand — and if you do need the worker, write the skill first and preload it.

Sources

• Claude Code: features overview
• Claude Code: subagents
• Claude Code: extend Claude with skills
• Claude Code: tools reference