Subagents vs Skills, fully explained

When to use which, at a glance.

They look alike, but behave differently

Both are "frontmatter + Markdown body" files, but a subagent runs in an isolated context once delegated, while a skill loads directly into the current conversation.

Frontmatter side by side

Subagents add `model`/`tools`; skills usually need just `name` and `description`.

# Subagent (.claude/agents/reviewer.md)
---
name: reviewer
description: Code-review specialist. Use for reviewing PR diffs.
model: sonnet
tools: Read, Grep, Glob, Bash
---

# Skill (.claude/skills/keihi-seisan/SKILL.md)
---
name: keihi-seisan
description: Expense workflow. Use when asked to reimburse.
---

A 3-question decision flow

1) Want it isolated from the main conversation? → subagent. 2) Just want a procedure run inline? → skill. 3) Is it a project-wide always-on policy? → CLAUDE.md.

Don't over-mix the two

Cramming a skill's whole procedure into a subagent's body wastes the isolation benefit; cramming multiple roles into one skill's description hurts trigger accuracy.

Converting one into the other

You can carve a skill's steps into a new subagent file (adding model/tools), or shrink an overgrown subagent into a skill — both can coexist while you test the switch.

FAQ

Do subagents and skills need the same frontmatter?

Both need name/description, but subagents commonly add model/tools while skills often run on just the two required fields.

How do I decide which to use?

Isolated context → subagent; inline procedure → skill; always-on policy → CLAUDE.md.

Should one subagent do everything?

No — splitting by role improves accuracy and repeatability.

Can I convert a skill into a subagent?

Yes, build a new file with the skill's steps plus name/description/model/tools.

Try reverse lookup →