Claude subagents are standalone configurations with their own context window that handle a task in isolation and hand back only a summary, while a skill loads inside your running conversation and never leaves it. An agent, the way I use the word for my workforce, is something else again: a full AI employee assembled from a role file, several skills, and, when needed, its own subagents. Mix the three up and you end up either building skills so heavy they clog your main conversation, or spinning up subagents for tasks a single slash command would have handled just fine.
I run my business with my own AI workforce on Claude, and every role has its own CLAUDE.md and its own skills, plus subagents for bounded single tasks. The rest of my Claude setup lives on the Claude overview page.
I see the difference most clearly in two hand-offs inside my own workforce: Conny passes a video job to Eddi, and Sebastian reviews what Ralf has built. The first hand-off works like a subagent, the second like a skill.
Skill, subagent, or agent: the problem in one sentence
All three terms solve the same underlying problem in different ways: how does Claude get extra abilities or extra roles without every single session paying the price for it. A skill keeps your main conversation lean because its content only loads once you call it. A subagent goes a step further and handles a task entirely apart, in its own context window, handing back only the result at the end, according to Anthropic's documentation on subagents (code.claude.com/docs/en/sub-agents). An agent, in my sense, is the lasting role wrapped around both tools, which is itself not a technical Claude building block but the sum of a CLAUDE.md, skills, and subagents assembled for one job in the business.
What a skill is and where it lives
A skill is a SKILL.md file in .claude/skills/<name>/ for a single project, or in ~/.claude/skills/<name>/ for all of your projects. Required frontmatter fields are name and description, with disable-model-invocation, user-invocable, allowed-tools, context: fork, agent, and paths available as optional ones (source: Anthropic documentation on skills, code.claude.com/docs/en/skills). You either call a skill directly with /name, or Claude decides on its own, based on the description, when it applies. The actual content of the file only loads once the skill is actually needed, not at the start of the session.
The simpler predecessor is slash commands in .claude/commands/, which the same documentation describes as the lighter option for cases where a single fixed command is enough and a full skill with frontmatter is not yet worth building. I walk through building a skill out of a task I already do repeatedly in Claude Skills: How to Create and Use Them.
What a Claude subagent is and where it lives
A subagent is a Markdown file with YAML frontmatter in .claude/agents/ for a project, or in ~/.claude/agents/ for all of your projects. Here too, name and description are required, with tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, memory, and isolation: worktree available as optional fields (source: code.claude.com/docs/en/sub-agents). Claude also ships three built-in subagents: Explore, Plan, and general-purpose.
A subagent gets invoked either automatically, when Claude judges the task a good fit, or directly with @agent-name. The /agents command, which used to open an assistant for creating new subagents, no longer does that according to the current documentation, which now recommends letting Claude write the file directly instead. Details like this change with versions, so check the documentation when it matters. That is exactly what I do in the example below.
Skill, subagent, and agent compared
| Trait |
Skill |
Subagent |
Agent (AI employee) |
| Storage location |
.claude/skills/<name>/ |
.claude/agents/ |
its own project folder with a CLAUDE.md, skills, and subagents |
| Context |
runs inside the main conversation |
its own, isolated context window |
spans multiple sessions over weeks and months |
| Return value |
result flows straight into the chat |
only the summary comes back |
result plus a lasting role history |
| Invocation |
/name or automatic via description |
automatic or with @agent-name |
you assign the role directly |
| Typical example |
a recurring routine step, say checking a quote |
a bounded single task, say researching a topic |
a lasting responsibility, say editorial content |
That third column is not an official Claude term, it is my own way of describing how I assemble skills and subagents into a complete role.
How my workforce splits this up: Conny hands work to Eddi, Sebastian reviews Ralf
In my workforce, Conny is the editorial lead for content, and Eddi handles video. When a post needs an edited video, Conny hands off exactly that one job to Eddi, waits for the finished result, and does not need to follow every step of the edit in between. On a small scale that is the same principle as a subagent: pass the task over, get the result back, the path in between stays separate.
The second hand-off looks more like a skill. When Ralf, who turns old websites into modern demos, delivers a result, Sebastian checks it against a fixed process, the same points every time, instead of working out from scratch what to look for. That process stays visible in the running work rather than disappearing into a separate session: a recurring check that never starts at zero. What goes out from there, I approve myself.
Every single role, whether Conny, Eddi, Ralf, or Sebastian, is its own agent with its own CLAUDE.md as a role description. I show what a file like that actually looks like using my office package Frieda as the example in CLAUDE.md: Claude Code's Memory, and how all eight roles relate to each other in My AI Workforce: Eight Employees.
Example frontmatter for a subagent of your own
Here is what a subagent would look like for a single, bounded task, using only fields the documentation actually lists:
---
name: source-research
description: Searches and checks external sources on a topic and returns a short, sourced summary instead of writing the post itself.
tools: WebSearch, WebFetch, Read
model: sonnet
isolation: worktree
---
name and description are the only required fields, everything else you add as needed. tools limits what the subagent is allowed to touch at all, model fixes which model it runs on, and isolation: worktree gives it an additionally isolated working copy according to the documentation, useful for tasks that change files without touching your main working tree.
There is also a bridge between both worlds: a skill can set context: fork in its frontmatter and then runs, similar to a subagent, in its own, separated context, without turning into a full subagent with its own file under .claude/agents/.
A decision rule: skill, subagent, or a new agent
Three questions are enough for me to decide which building block fits. First: is it a recurring routine step with fixed steps that I want to keep reusing inside the same conversation? Then a skill. Second: does the task need its own, isolated context window so it does not clog my main conversation with intermediate steps I do not actually care about? Then a subagent. Third: is it a lasting responsibility that works across many sessions and makes its own decisions within fixed boundaries? Then a dedicated agent with its own CLAUDE.md is worth it, the same way every single role in my workforce is set up.
Frequently asked questions
When is a slash command enough instead of a full skill or subagent?
When a task is a single, fixed command that does not need Claude to decide on its own when it applies. According to the documentation, slash commands under .claude/commands/ are exactly the simpler predecessor to a full skill with frontmatter.
Does a subagent automatically see my CLAUDE.md?
The documentation lists an optional frontmatter field called memory, but doesn't say at that point what reaches a subagent by default without it. When a rule from my CLAUDE.md really needs to land with a subagent, I put it directly into its description or into the task itself, just to be safe.
How many subagents make sense for a small workforce?
From my own practice: fewer, clearly bounded subagents for tasks that genuinely need to run in isolation, rather than a separate file for every small thing. The built-in Explore, Plan, and general-purpose subagents already cover a large share of my needs before I build a custom one.
What is the difference between an agent and a skill?
A skill is a single tool that loads inside a running conversation. An agent, the way I use the word, is a whole role with its own CLAUDE.md that draws on several skills and subagents and persists across many sessions, not just within one conversation.
Can I write a subagent myself, without a template?
Yes, and according to the documentation that is now the recommended path: instead of an assistant behind /agents, you write the Markdown file with frontmatter directly, or let Claude create it for you, the way I did in the example above.
Where to go from here
Do not start with a subagent. Start with a single skill for a task that genuinely keeps coming back for you. Only once you notice a task clogging your main conversation with intermediate steps you do not actually care about is a dedicated subagent worth building. I show how to turn that into a complete role with its own CLAUDE.md in Build an AI Agent With Claude: A Guide.
All eight ready-made packages are in my community.
