Claude agents vs skills
Claude agents vs skills is about where the work happens. A subagent does a job in a separate context window, while a skill gives Claude instructions inside the chat you are already in.
TL;DR: Write a skill to teach Claude how to do something. Create a subagent to hand off a noisy side task and get back only a summary. The two work best together.
What is a Claude agent?
In Claude Code, "agent" usually means a subagent. It is a helper with its own context window, its own system prompt, and its own tool access.
Claude hands a task to a subagent when the task matches that subagent's description. The helper works alone, then returns its result. All the search output, logs and file dumps stay in its window, not yours.
Claude Code ships built-in subagents. Explore and Plan are read-only and research a codebase. General-purpose can both explore and edit. You can also write your own as a markdown file in .claude/agents/ or ~/.claude/agents/. Anthropic's subagent docs cover every field.
What is a Claude skill?
A skill is a folder with a SKILL.md file. It holds instructions, and sometimes scripts or reference files, for one kind of task.
Claude keeps each skill's short description in view. The full body loads only when a task calls for it, or when you type /skill-name. The skill then runs inside your current conversation, with your history in view.
What is the difference between agents and skills?
The core split is context. A skill shares your conversation. A subagent starts fresh and keeps its own.
| Question | Skill | Subagent |
|---|---|---|
| Where does it run? | In your current conversation | In a separate context window |
| What does it change? | What Claude knows how to do | Who does the work |
| Does it see your chat history? | Yes | No, it starts fresh |
| Can it limit tools? | It can pre-approve or remove tools for its turn | Yes, with a tools allowlist or disallowedTools |
| Where does the file live? | .claude/skills/name/SKILL.md | .claude/agents/name.md |
Think of a skill as a recipe card and a subagent as a second cook. The recipe makes any cook better. The second cook keeps your kitchen clear.
When should I use a skill instead of an agent?
Use a skill when you want Claude to follow the same steps each time, in front of you. Good fits are a commit message style, a release checklist, or how your team writes tests.
A skill is light. It needs no new window, so the result appears right in your chat. You can step in and steer as it goes.
Our step-by-step skill guide shows the folder format. For a deeper look at how to write good ones, read the writing-skills skill by obra.
When is a subagent the better choice?
Pick a subagent when a side task would flood your main chat. Think large code searches, long test logs, or reviews of many files.
Subagents also help you enforce limits. A review agent can be read-only, so it can never edit code. You can even route simple jobs to a faster, lower-cost model.
If you want to set one up, our Claude Code subagents guide walks through the file and the frontmatter.
Can a subagent use skills?
Yes, in two ways. A subagent can load skills on its own through the Skill tool, the same way your main chat does.
You can also preload skills. Add a skills field to the subagent's frontmatter, and the full text of each listed skill is injected when it starts. That gives a fresh helper your team's know-how from the first turn.
It works the other way too. A skill with context: fork in its frontmatter runs inside a subagent. The skill text becomes the subagent's task, and the agent field picks which type runs it.
What does a skill that drives subagents look like?
Obra's Superpowers set has real examples. The dispatching-parallel-agents skill tells Claude to split two or more independent tasks across separate agents.
Its sibling goes further. It sends a fresh implementer subagent to each task in a plan, then reviews each result before moving on. The skill holds the method, and the subagents do the work. The source for both lives in the obra/superpowers repo.
This pattern is the clearest answer to the agents vs skills debate. You rarely choose one. You use a skill to describe the process and let it call agents for the heavy lifting.
View the subagent-driven-development skill
FAQ
Are Claude agents and skills the same thing?
No. A skill is a set of instructions Claude loads into your current chat. An agent, or subagent, is a separate helper with its own context window, prompt and tools. A skill changes what Claude knows how to do, while a subagent changes who does the work and where.
Do subagents use more tokens than skills?
Usually, yes. A subagent sends its own requests, and they count toward the same usage limits as your main chat. The upside is that your main context stays small, since only the summary comes back. A skill adds its full text to your chat only when it runs.
Can I turn a skill into a subagent?
You can run a skill inside one. Add context: fork to the skill's frontmatter and pick an agent type with the agent field, such as Explore or a custom agent. The skill body becomes the task, and the subagent starts without your chat history.
Should I use skills, agents or commands?
Use a skill for a reusable process, and a subagent for isolated side work. Custom commands have been merged into skills, so a file in .claude/commands/ and a skill both make a /name you can type. New work should use skills, since they support extra files and auto-loading.