Skills vs subagents in Claude Code: what each does and when to use which

What is the difference between skills and subagents?

In Claude Code, a skill is reusable content you load into a conversation, and a subagent is an isolated worker that runs in its own context and returns a summary. Anthropic's features overview puts it in two lines: "Skills are reusable content you can load into any context" and "Subagents are isolated workers that run separately from your main conversation."

So the question to ask is not which is more powerful, but what problem you have. If you keep re-explaining the same procedure, you need a skill. If a task floods your conversation with output you won't look at again, you need a subagent. Often you want both, and Claude Code lets you combine them.

What is a skill?

A skill is a folder with a SKILL.md file. Claude Code's skills docs say: "Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name."

Skills live in .claude/skills/<name>/SKILL.md for a project or ~/.claude/skills/<name>/SKILL.md for all your projects, and they follow the Agent Skills open standard. Only the name and description load at the start of a session. The full content loads when you or Claude invoke the skill, and it runs inside your current conversation, with your history and files already in view.

The docs describe two flavors. Reference skills give Claude knowledge it uses throughout a session, such as an API style guide. Action skills tell Claude to do something specific, such as a /deploy checklist. The Claude Code skills guide covers the format and frontmatter.

What is a subagent?

A subagent is a Markdown file with frontmatter in .claude/agents/ or ~/.claude/agents/. The subagents docs say "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions."

When Claude delegates to a subagent, it writes a task message, and the subagent starts fresh. It "doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read." It does its work and sends back a summary, so the dozens of files it read never enter your main conversation.

Claude Code ships built-in subagents, including Explore, a fast read-only agent for searching codebases, Plan, used during plan mode, and general-purpose for multi-step tasks. You can define your own with fields such as tools, model, permissionMode and skills. Claude delegates to a subagent when a task matches its description, or you can name it in your prompt ("Use the code-reviewer subagent to...") or @-mention it to make sure it runs. The Claude Code subagents guide walks through creating one.

How do skills and subagents compare side by side?

The first rows follow Anthropic's own comparison table. The key line from it: a skill "Adds to your main window," while a subagent "Uses a separate window with its own input and output tokens."

When should you use a skill?

Use a skill when the value is in the instructions themselves and you want them applied in your current conversation. The features overview gives the triggers: "You keep typing the same prompt to start a task," or "You paste the same playbook or multi-step procedure into chat for the third time."

Good fits:

• A release checklist you run with /release.
• Your team's API conventions, loaded whenever Claude writes an endpoint.
• A commit message format or code review rubric.
• A debugging playbook for one part of your stack.

For skills with side effects, such as deploys, the docs recommend disable-model-invocation: true, so the skill runs only when you name it and its description stays out of context.

When should you use a subagent?

Use a subagent when the problem is context or control, not knowledge. The subagents docs list three signals:

• "The task produces verbose output you don't need in your main context"
• "You want to enforce specific tool restrictions or permissions"
• "The work is self-contained and can return a summary"

Good fits:

• Searching a large codebase for every place a function is called.
• A read-only code reviewer limited to Read, Glob and Grep.
• Running a test suite and reporting only the failures.
• Several independent research tasks run in parallel.

The docs also say when to stay in the main conversation: when the task needs back and forth, when several phases share a lot of context, for quick targeted changes, and when latency matters, because a fresh subagent "may need time to gather context."

How do skills and subagents work together?

They are not either/or. Claude Code has two ways to combine them, plus a common pattern.

A subagent that preloads skills. List skills in the subagent's skills field and "The full skill content is injected, not only the description." Use this when a specialist worker always needs the same reference material:

---
name: api-builder
description: Builds new API endpoints that follow team conventions
tools: Read, Edit, Write, Bash
skills:
  - api-conventions
---

You build API endpoints. Follow the preloaded api-conventions skill
exactly, add tests for every endpoint, and report the files you changed.

A skill that runs in a subagent. Add context: fork and Claude Code starts a subagent of the type named in agent, with the skill content as its prompt. This example is from the skills docs:

---
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

Because the forked subagent doesn't see your conversation, the docs warn that "the skill's instructions have to stand on their own."

The skills docs sum up the difference between the two:

A skill that spawns subagents. The features overview gives the example of an /audit skill that "kicks off security, performance, and style subagents that work in isolated context." The skill holds the plan; the subagents do the noisy work.

Which should you pick?

Answer three questions in order:

1. Is this something Claude should know or follow? Make it a skill. Checklists, conventions and procedures belong here.
2. Will the work fill your context with output you won't reuse, or need tight tool limits? Make it a subagent.
3. Both? Write the knowledge as a skill, then preload it into a subagent with skills, or give the skill context: fork.

Two practical notes. Skills travel: a SKILL.md folder also works in Codex, Cursor and Gemini CLI, so it is the better home for anything you want to reuse across tools. And neither is enforced configuration. If a rule must hold every time, such as never editing .env, the docs point you to a hook instead. For the skills versus MCP question, see skills vs MCP.

Keep your skills and agent prompts in one place

The skills you write and the system prompts you give subagents are reusable work, worth keeping outside any single project. Kipt stores your prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Claude Code or Codex with one npx skills add command. If you have a subagent prompt you would rather run inline, the free SKILL.md generator turns it into a skill folder in your browser.