All 5 AI packs for $39 →
← All posts
Claude Code · Agent Skills · Subagents · How-to

Claude Code skills vs subagents vs CLAUDE.md: which one to use for what

Published · Facts checked against official vendor pages on October 29, 2026 · Rankings are independent of sponsorships

Claude Code gives you three places to put reusable instructions: CLAUDE.md, skills and subagents. They overlap enough that most setups end up with the wrong thing in the wrong place, usually a CLAUDE.md that has grown into a manual. The difference that matters is when each one loads and whose context it fills. We read Anthropic's current Claude Code docs on October 29, 2026; here is how to choose, with free files for each.

Tools in this post

SClaude Code

The short version

CLAUDE.md is for facts Claude needs on every request: what the project is, the commands, the layout and the hard rules. It loads every session, so every line costs context every time.

A skill is for a procedure or reference you need sometimes. Only its description sits in context; the full SKILL.md loads when you type /skill-name or Claude decides it's relevant. Anthropic's docs suggest making one when you keep pasting the same checklist into chat, or when a section of CLAUDE.md has turned into a procedure.

A subagent is for side work that would flood your conversation, like running tests, searching a big codebase or reading logs. It works in its own context window with its own tools and prompt, and only its summary comes back.

Skills: SKILL.md files that load on demand

A skill is a folder with a SKILL.md file: YAML frontmatter, then Markdown instructions. Put it in .claude/skills/<name>/ to share it with the repo or ~/.claude/skills/<name>/ for all your projects, and the folder name becomes a slash command. Anthropic's docs say custom commands have been merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working.

All frontmatter fields are optional, but the description is the one that matters, because Claude uses it to decide when to load the skill. Put the main use case first: the docs say description plus when_to_use is cut off at 1,536 characters in the skill listing. Two fields control who can trigger it. disable-model-invocation: true means only you can run it, which the docs recommend for anything with side effects like /deploy or /commit; it also keeps the description out of context. user-invocable: false hides it from the / menu so only Claude uses it, for background knowledge.

Skills can also run shell commands before Claude reads them. A line like !`git diff HEAD` is replaced with the command's output, so the instructions arrive with live data. Our free /ship-check skill uses this to review your real diff before a commit. The docs suggest keeping SKILL.md under 500 lines and moving long reference material into supporting files in the same folder, which Claude reads only when needed.

Claude Code skills follow the open Agent Skills format, which Anthropic donated to the Linux Foundation's Agentic AI Foundation on October 22. Claude Code adds its own fields on top. If you upload a skill to claude.ai or the Skills API, only name, description, license, compatibility, metadata and allowed-tools are allowed, and any other field fails with an "Unexpected key(s)" error.

Subagents: separate workers with their own context

A subagent is a Markdown file with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (all your projects). Only name and description are required. The body becomes the subagent's system prompt, and it doesn't get Claude Code's own system prompt. It does still load your CLAUDE.md files and a git status snapshot, except for the built-in Explore and Plan agents, or a custom one with omitClaudeMd: true.

The useful controls are in the frontmatter: tools is an allowlist (a reviewer with Read, Grep, Glob and Bash can't edit files), disallowedTools removes tools, model can route cheap work to haiku, and permissionMode, maxTurns and isolation: worktree limit what it can do and where. Claude delegates based on the description; the docs suggest adding "use proactively" if you want it to happen without asking, or you can @-mention the subagent to make sure it runs.

Each subagent sends its own requests, which count toward the same usage limits as your main conversation, and its full result comes back into your context. So use one when the work is self-contained and noisy, not for quick back-and-forth edits. Free examples: our code-reviewer, planner and new test-runner subagents.

How they combine

The two features plug into each other in both directions. A skill with context: fork runs its instructions in a fresh subagent (general-purpose by default, or the one named in its agent field), which suits a long research or review task you trigger with a slash command. A subagent with a skills list gets those skills' full content injected at startup, so a specialist always has your team's conventions loaded.

Neither one sees your conversation history. If a task depends on what you've already discussed, Anthropic's docs point to forking the conversation (/subtask) instead, which hands a copy of the whole session to a background worker.

A simple way to decide

Ask three questions about the instruction you're about to write:

  • Does Claude need it on almost every request? Put it in CLAUDE.md (or AGENTS.md, imported from CLAUDE.md), and keep it short.
  • Is it a procedure, checklist or reference you need only sometimes? Make it a skill. Add disable-model-invocation: true if it does anything you'd want to trigger yourself.
  • Would doing it dump lots of output into your conversation, or does it need different tools or a cheaper model? Make it a subagent.
  • Is it a rule that must hold every single time, like never editing a migration? The docs suggest a hook, because hooks run on every matching event whether or not Claude follows the instructions.

Start with these files

For the always-on layer, use our free CLAUDE.md template and AGENTS.md starter; see which instruction file each coding agent reads if you also use Cursor, Codex or Copilot. For on-demand work, add the /ship-check skill. For side work, add the test-runner and code-reviewer subagents.

Want the full set? The Claude Code Agent Kit packages 12 subagents, 8 skills and 3 safety hooks as an installable plugin. Plans and limits are on our Claude Code page, and you can compare it with other agents in our Claude Code vs OpenAI Codex guide.

FAQ

What's the difference between a Claude Code skill and a subagent?
A skill is a set of instructions that loads into your current conversation when you or Claude invoke it. A subagent is a separate worker with its own context window, system prompt and tool access that does a task and returns a summary.
Are Claude Code slash commands the same as skills now?
Yes. Anthropic's docs say custom commands have been merged into skills: a file in .claude/commands/ and a skill in .claude/skills/ with the same name both create the same /command, and existing command files keep working.
Do skills use up context?
Only a little until they're used. By default each skill's description stays in context so Claude knows it exists, and the full SKILL.md loads only when invoked. With disable-model-invocation: true, even the description stays out until you run it.
Do subagents read CLAUDE.md?
Custom subagents load your CLAUDE.md files at startup unless their definition sets omitClaudeMd: true. The built-in Explore and Plan subagents skip CLAUDE.md to stay fast.

Free and paid rules for your agents

Related changelog

Sources

Prices change often. Always confirm on the vendor's site before buying. See the full tier lists and the changelog.

+ Your logo here