The short answer
A skill is a folder of instructions that Claude reads into your current conversation. A subagent is a separate worker with its own context window, system prompt and tool list that returns only a summary. In the Claude skills vs agents question, the deciding factor is isolation: if the task would flood your conversation with output, or must run with fewer permissions, use a subagent. If you just want Claude to follow a procedure, use a skill.
Anthropic’s Claude Code documentation frames it the same way: skills are reusable content you can load into any context, while subagents are isolated workers that run separately from your main conversation. The two also combine, which is where most of the confusion starts.
Claude skills vs agents at a glance
| Skill | Subagent | |
|---|---|---|
| What it is | A directory with SKILL.md | A Markdown file with YAML frontmatter |
| Where it lives | .claude/skills/<name>/ or ~/.claude/skills/<name>/ | .claude/agents/ or ~/.claude/agents/ |
| Required fields | None; description is recommended | name and description |
| Where it runs | Your main conversation, unless context: fork | Its own context window |
| Context impact | Description every turn, body when used | Separate window; summary returns to you |
| Own system prompt | No, it adds instructions to the session | Yes, replaces the Claude Code system prompt |
| Tool control | allowed-tools pre-approves, never restricts | tools allowlist and disallowedTools denylist |
| Who triggers it | You with /name, or Claude by matching the description | Claude by matching the description, you by @-mention or --agent |
| Can bundle scripts | Yes, in the skill folder | No, it is a single Markdown file |
| Works in other agents | Yes, it is an open format | The file format here is Claude Code’s |
What a skill is
A skill is a directory with a SKILL.md. The Claude Code skills docs say Claude uses one when it is relevant, or you can run it directly with /skill-name. Only description is recommended; every frontmatter field is optional, and unknown fields are ignored without an error.
Descriptions sit in context so Claude knows what exists, and the body loads when the skill is used. The docs suggest keeping SKILL.md under 500 lines and moving detail into separate files. Because the format is the open Agent Skills standard, the same folder works in other agents too. Codex, for example, reads skills from .agents/skills. Our platform pages list the paths for each agent.
A skill can be reference material, like an API style guide, or an action, like a /deploy checklist. Either way it runs inside your conversation, so everything it reads and writes stays in your context window.
What a subagent is
A subagent is a specialized assistant that Claude hands a task to. It runs in its own context window with a custom system prompt, its own tool access and its own permissions. It does not see your conversation history or skills you invoked earlier, and when it finishes, only its result comes back.
Only name and description are required in the frontmatter. Optional fields include tools, disallowedTools, model, skills, mcpServers and memory. Claude Code ships built-in subagents:
- Explore, a read-only agent for searching code, with Write and Edit denied;
- Plan, a read-only research agent used in plan mode;
- general-purpose, which has every tool a subagent can use.
You can run one by asking Claude, by typing @ and picking it, or by starting a whole session as that agent with claude --agent <name>. Subagents can spawn further subagents, up to three layers below the main conversation by default.
How they differ
Context
A skill adds to the context you already have. A subagent starts clean. That is its main benefit: a subagent can read dozens of files or run a long search, and your main conversation only receives the summary. It is also its main cost. The subagent knows only what Claude puts in the delegation message, plus its system prompt, CLAUDE.md and any skills in its skills field.
Subagent requests also count toward the same usage limits as your main conversation, so isolation does not make the work free.
Tools and permissions
A skill’s allowed-tools field lists tools Claude can use without asking during that skill’s turn. The docs state that it does not restrict tools: anything not listed still follows your normal permission settings.
A subagent’s tools field is a real allowlist. Leave it out and the subagent inherits every tool available to subagents; set it and the agent gets only those. disallowedTools works as a denylist. Subagents also inherit the parent’s permission rules by default, and a permissionMode field can adjust that, though the main conversation’s mode can override it.
If you want a reviewer that cannot edit files, a subagent with tools: Read, Grep, Glob does that. A skill cannot.
Triggering
Both rely on descriptions, and both fail the same way: vague or overlapping descriptions mean the wrong one loads or none does. For a skill you can bypass guessing with /name, and you can set disable-model-invocation: true so it runs only when you ask. For a subagent, an @-mention guarantees it runs for that task, though Claude still writes the task prompt from your message.
How skills and subagents combine
Two patterns connect them, and they run in opposite directions.
A skill can run inside a subagent. Set context: fork in the skill’s frontmatter and the skill runs in a forked subagent context. The optional agent field picks the type, such as Explore. The docs warn that this subagent does not see your conversation history, so the skill must stand on its own.
A subagent can load skills. The skills field preloads the full content of the named skills at startup. Without it, the subagent can still discover and invoke project, user and plugin skills through the Skill tool, and skills marked disable-model-invocation: true cannot be preloaded.
One uses a skill as the job description, the other uses it as reference material. Pick the first when the procedure is the task, the second when the worker needs domain knowledge.
Skills vs commands vs plugins
Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. The docs recommend skills for new work because they add a directory for supporting files and frontmatter that controls who invokes them.
A plugin is not a different kind of instruction. It is a packaging layer: a directory of skills, agents, hooks and MCP servers that installs as one unit, with a manifest at .claude-plugin/plugin.json. Plugin skills are namespaced, so a skill named review in my-plugin runs as /my-plugin:review. Use a plugin to share a setup across repositories or with a team. Browse what is available on our plugins page.
Plugin subagents carry a restriction: for security reasons, hooks, mcpServers and permissionMode are ignored in subagents that come from a plugin. To use those fields, copy the agent file into .claude/agents/.
What to check before you install either
Both are text files that steer a model with real tools, so read them the way you would read a script.
For a skill, check allowed-tools for broad entries such as bare Bash, look at the scripts/ folder, and note whether it installs packages or edits your config. Our security notes explain the statuses we assign. In our index of 195 repositories, 34 pre-approve broad shell access and 12 install hooks.
For a subagent, check its tools line. An agent with no tools field inherits everything, including shell and file writes. Check whether it declares mcpServers or preloads skills, since those widen what it can reach.
Two examples from our data show the overlap. AgriciDaniel/claude-seo ships 26 sub-skills and 19 sub-agents for SEO work, with Python helpers; we rate it “Review before installing” and could not check how its installers write API keys into your Claude settings. nrwl/nx-ai-agents-config bundles Nx skills and subagents, and its CI-monitoring skill pre-approves unrestricted Bash and by default commits and pushes to your branch in a loop, so we rate it “Broad access.” The methodology page explains how we score these.
When to use which
Use a skill for a repeatable procedure, a style guide, a checklist or reference docs, when you want a /name command, or when the output should stay visible in the conversation.
Use a subagent for side tasks that produce bulky output you will not reference again, for parallel research, and for any worker that needs a restricted tool list or its own system prompt.
Use CLAUDE.md for rules Claude should always know. Use a hook for anything that must happen every time. Use MCP when the agent needs access to an outside service.
Most real setups use several. A skill that defines a review checklist, run through a forked subagent, keeps the file reads out of your main window.
Frequently asked questions
Agents vs skills in Claude: is an agent just a subagent?
In Claude Code, “agent” usually means a subagent defined in .claude/agents/. You can also run an entire session as one with claude --agent. Skills are never agents; they are instructions an agent follows.
Can a subagent use my skills?
Yes. It can discover and invoke project, user and plugin skills through the Skill tool, or you can preload specific ones with the skills field. To block skills entirely, leave Skill out of an explicit tools list or add it to disallowedTools.
Should I convert my slash commands to skills?
You do not have to, since command files keep working. Move one over when you want supporting files or control over whether Claude can trigger it on its own.