Claude Code agents vs skills: which one to use

Claude Code agents vs skills is one of the first questions people hit once a setup grows past a single CLAUDE.md file. Both live in .claude/, both are Markdown with a few lines of YAML on top, and both can be triggered automatically. They solve different problems, though, and mixing them up is how a setup becomes slow and hard to predict.

The short version: a skill adds know-how to the conversation you are in; a subagent does a job in a separate context and brings back only the result. Everything below follows the official subagents and skills documentation. We use both every day in our own studio, and the rule at the end comes from that work.

What a subagent is

A subagent is a specialised assistant that runs in its own context window, with its own system prompt, its own tool access and its own permissions. It does not see your conversation history. Claude writes it a task, the subagent works, and only a summary comes back.

That is the whole point: a side task that would flood the main conversation with search results, logs or file contents stays inside the subagent.

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

Save it as .claude/agents/code-reviewer.md for one project or ~/.claude/agents/code-reviewer.md for all of them. Only name and description are required. tools is an allowlist: leave it out and the subagent gets every tool available to subagents.

Claude delegates on its own when a task matches the description. You can also ask by name, or mention it as @"code-reviewer (agent)" to make sure it runs. Claude Code also ships built-in subagents, such as Explore for fast read-only searches and Plan for research in plan mode.

What a skill is

A skill is a folder with a SKILL.md file: instructions plus optional supporting files such as reference notes or scripts. It runs in the main conversation, not in a separate context.

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

Summarize the uncommitted changes in two or three bullet points,
then list anything risky: deleted files, changed permissions, new dependencies.

Save it as .claude/skills/summarize-changes/SKILL.md. By default both you and Claude can use it: you type /summarize-changes, or Claude loads it when your request matches the description.

The detail that matters for cost: in a normal session only the skill descriptions sit in context. The full body loads when the skill is used. Long reference material in a skill costs almost nothing until it is needed, unlike text in CLAUDE.md, which is always there.

Custom slash commands are now part of skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy.

Claude Code agents vs skills, side by side

	Subagent	Skill
Where it runs	its own context window	the main conversation
Sees your conversation	no	yes
What comes back	a summary	the work happens in place
File	.claude/agents/name.md	.claude/skills/name/SKILL.md
Typical trigger	Claude delegates a task	Claude or you with /name
Good for	searches, reviews, long side jobs	procedures, house rules, reference

They also combine. A subagent can preload skills through its skills field, so a reviewer starts with your checklist. And a skill with context: fork runs in a subagent: the skill text becomes the task, and your main context stays clean.

A simple rule for choosing

Ask one question: do I need the details of this work in the conversation afterwards?

• No, only the result. Use a subagent. Searching a large codebase, reviewing a diff, reading long logs: you want the conclusion, not every file it opened.
• Yes, it is part of what I am doing now. Use a skill. A release checklist, your commit message format, how your project names things: knowledge the conversation should follow.

Two warning signs from practice. If a CLAUDE.md section has grown into a step-by-step procedure, it wants to be a skill. If a skill keeps pulling dozens of files into the conversation, it wants context: fork or a subagent.

Mistakes that make a setup unpredictable

1. Vague descriptions. Both are chosen by their description. “Helps with code” matches everything and nothing. Say what it does and when to use it.
2. Too many long descriptions. Descriptions are loaded at the start of every session. Keep them short and put the detail in the body.
3. A subagent with every tool by default. If a reviewer only needs to read, give it Read, Glob, Grep and nothing else.
4. Rules that must hold, written as a skill. A skill guides; it does not enforce. For “never do this”, use permission rules and hooks, as in our Claude Code hooks article.

When to hand it over

If your .claude/ folder grew fast and nobody is sure which agent or skill does what, we map the setup, clean up agents and skills, and add tested rules. You can see how our own system is put together on the work page.

Questions

Is a skill just a saved prompt?

Close, but more than that. A skill is a folder with a SKILL.md file and optional supporting files. Claude sees only its description until the skill is used, can load it on its own when the task matches, and you can also call it as /skill-name.

Do subagents see my conversation?

No. Each subagent starts with a fresh context window: its own system prompt, the task Claude writes for it, CLAUDE.md and any skills you preload. It returns a summary to the main conversation.

What happened to custom slash commands?

They were merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working.

Can I use both at once?

Yes, in both directions. A subagent can preload skills through its skills field, and a skill with context: fork runs inside a subagent instead of the main conversation.