Claude Code Skills vs Commands vs Subagents: What Each One Is For

In Claude Code a skill is a SKILL.md file Claude can load on its own when a task matches its description. A slash command is the older, single-file version of the same idea, and Anthropic has merged the two: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. A subagent is a separate agent with its own context window that returns a summary. The first two shape what Claude knows; the third shapes where the work runs.

SWARECO maintains 22 skills of its own. On 16 October 2026 we counted a week of their use, and the article ends with the decision rule that count gave us.

Key Takeaways

• A skill is a directory with SKILL.md, optional supporting files and scripts. Claude reads every skill's description at startup and loads the body only when the task matches or when you type /skill-name.
• Slash command files are not a separate mechanism any more. They keep working, accept the same front matter as skills except name and paths, and lose to a skill of the same name. Anthropic's documentation says to prefer a skill for new work.
• A subagent runs in a fresh context window with its own system prompt, tools and permissions and returns only a summary. A skill with context: fork runs inside one.
• In one week on one SWARECO machine (9 to 16 October 2026) there were 57 skill invocations; 9 of our 22 skills ran, the top three were two thirds of own-skill use, and the most-used one was the smallest shared formatting skill.
• We have zero custom subagents. Every bounded task we isolate is a skill with context: fork, which gives the isolation without a second definition file.

The three mechanisms in one paragraph each

A skill is a directory containing SKILL.md: YAML front matter followed by Markdown instructions. Claude reads every skill's description at startup and loads the full file only when the task matches or when you type /skill-name. The directory can carry supporting files, which load when referenced, and scripts, which run.

A slash command is a single Markdown file under .claude/commands/ that creates /name. Anthropic's documentation, read on 16 October 2026, says these files have been merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy and work the same way, and existing files keep working. Command files accept the same front matter as skills except name and paths; if a skill and a command file share a name, the skill wins; and the documentation says to prefer a skill for new work.

A subagent is a separate AI agent the main agent spawns for one bounded task. It runs in its own context window with its own system prompt, tools and permissions and returns only a summary. It is defined as a Markdown file under .claude/agents/ with name and description required. We published a separate explainer on subagents two days ago; this article is about choosing between the three.

Skills: a SKILL.md directory Claude can load on its own

The front matter can carry name (defaults to the directory name), description (what it does and when to use it; combined with when_to_use it is truncated at 1,536 characters in the skill listing), argument-hint, arguments, disable-model-invocation (true stops Claude loading it on its own), user-invocable (false hides it from the / menu so only Claude invokes it), allowed-tools, disallowed-tools, model, effort, context (set to fork to run as a subagent), agent (the subagent type when context is fork; defaults to general-purpose), background, hooks, paths (glob patterns that limit automatic activation to matching files) and shell. Unrecognised fields are dropped silently.

Skills live in five places: enterprise managed settings; personal, at ~/.claude/skills/; project, at .claude/skills/ in the repository, including nested subdirectories; a directory passed with --add-dir; and a plugin's skills/ directory, invoked as /plugin-name:skill-name. When names collide, enterprise overrides personal and personal overrides project; plugin skills are namespaced.

The context behaviour is what makes skills cheap to keep and expensive to ignore. Descriptions are always in context; the body loads only when invoked. Once loaded, the content enters the conversation once and stays across turns. After compaction, the most recent invocation of each skill is re-attached, keeping the first 5,000 tokens of each within a combined 25,000-token budget. The documentation says to keep SKILL.md under 500 lines and move reference material to separate files, which is what the directory is for: supporting files load when referenced, scripts execute rather than load, $ARGUMENTS and named arguments substitute into the text, and a shell snippet can inject its output before Claude reads the skill, with a two-minute default timeout and the whole invocation aborting if it fails.

Slash commands: the older single-file format, now part of skills

There is no longer a separate mechanism. A single Markdown file under .claude/commands/ creates the same / entry a skill does, with the same front matter minus name and paths. A nested file such as frontend/component.md becomes /frontend:component.

What a skill adds over the single file is a directory for supporting files and scripts, the front-matter fields that control who may invoke it, and automatic loading when Claude judges the task relevant.

Two things that look similar and are not. Built-in commands such as /help and /compact run fixed logic directly, while bundled skills such as /code-review and /loop are text that Claude follows using its tools. And a skill with context: fork does not run in a fork of the current conversation, despite the name: it starts a new subagent and hands it the skill text as its task.

Subagents: a separate context window, not a file format

A subagent is about where work runs, not how instructions are stored. It starts with a fresh context: no conversation history, no files already read, no skills already invoked, except the skills listed in its own skills field, which are preloaded. Only its summary comes back; the verbose middle stays in its own window.

It is defined as a Markdown file with YAML front matter under .claude/agents/ for the project or ~/.claude/agents/ for the user, with name and description required and optional tools, disallowedTools, model, permissionMode, maxTurns, skills, hooks, memory and background. The built-in types are Explore (read-only search), Plan (read-only, used in plan mode) and general-purpose.

The two connect in both directions: a skill can run inside a subagent with context: fork, and a subagent can preload skills.

Skills, slash commands and subagents side by side

Skills and command files shape what Claude knows. A subagent shapes where it works.

What a week of our own skill use looks like

On 16 October 2026 we ran a small script over the Claude Code transcripts on one SWARECO engineer's machine, covering 9 to 16 October. The count:

An earlier count on 25 August 2026 found 107 invocations across 213 transcripts and 18 project directories, so the pattern is stable: a handful of skills carry almost all the use.

Three readings. First, the most-used skill is the smallest shared one, a formatting standard that other skills include, so composition beats size. Second, a skill that never runs still costs its description in every session, which is why the listing truncates descriptions at 1,536 characters and why our 13 idle skills are a cleanup candidate. Third, we have zero custom subagents, because every bounded task we isolate is a skill with context: fork, which gives the isolation without a second definition file. The same skills, committed to the repository, are what our scheduled routines run.

Which one to build, by situation

• Claude should apply a house rule or a procedure whenever it is relevant, without being asked: a skill, with a precise description and user-invocable left at its default. (Rules that apply to every session belong in CLAUDE.md instead.)
• A step that only runs when a person asks for it, such as a release checklist: a skill with disable-model-invocation: true, or the older command file, which behaves the same.
• The procedure needs reference material, templates or a script: a skill, because only a skill has a directory.
• The task reads many files or produces noisy output the conversation does not need, or several such tasks should run at once: a subagent, or a skill with context: fork when the task text can stand alone.
• The task needs a narrower tool set than the main session, for example a read-only review: a subagent with a tools allowlist, or a skill with allowed-tools.
• You are migrating an old command file: leave it. It keeps working. Move it to a skill directory when it needs supporting files.

Conclusion

Skills and slash command files are the same mechanism and decide what Claude knows. Subagents decide where the work runs. On one SWARECO machine a week of use was 57 invocations, three skills did two thirds of the work, and no custom subagent existed at all. SWARECO builds and runs engineering teams that work with these tools daily.

FAQs

1. What is the difference between a Claude Code command and a skill?

None in mechanism any more. A command file under .claude/commands/ and a skill directory under .claude/skills/ both create /name. A skill adds a directory for supporting files and scripts, the front-matter fields that control who may invoke it, and automatic loading when the task matches its description.

2. When should I use a command instead of a skill?

Only when the file already exists. Anthropic's documentation says to prefer a skill for new work. For a step that should run only when a person asks, use a skill with disable-model-invocation: true.

3. What is the difference between a skill and a subagent?

A skill is instructions Claude loads into the current conversation. A subagent is a separate agent with its own context window, tools and permissions that returns a summary. A skill with context: fork runs inside a subagent.

4. How does Claude decide to invoke a skill on its own?

From the description. Every skill's description is in context at startup, and Claude loads the body when a task matches. Set disable-model-invocation: true to stop that, or user-invocable: false to let only Claude invoke it.

5. Do unused skills cost anything?

Yes. Each description is loaded in every session whether or not the skill runs, which is why the listing truncates descriptions at 1,536 characters. In our week, 13 of 22 skills never ran.

6. How do I keep a skill's context cost down?

Keep SKILL.md under 500 lines, move reference material to supporting files that load only when referenced, and put scripts in the directory so they execute rather than load. After compaction only the first 5,000 tokens of each recent invocation are re-attached, within a 25,000-token budget.