Claude Code Skills vs Subagents vs Hooks vs CLAUDE.md: Which One Fits Which Job

Use CLAUDE.md for rules Claude should always know, a skill for reference material or a repeatable workflow, a subagent when a side task would flood your main conversation, and a hook when something must happen every time. The short version of the skills vs subagents question is where the work runs. A skill loads into your conversation. A subagent runs in a separate context window and sends back a summary.

The rest of this page is the decision table, a sequence for picking, and one job done the wrong way and the right way. Every product fact comes from Anthropic’s Claude Code docs, read 09/29/2026. Where behavior may change, I say so.

The one-screen decision table

I am comparing five mechanisms: CLAUDE.md (and AGENTS.md), skills, slash commands, subagents and hooks.

Mechanism	When it loads	Whose context it uses	Guaranteed trigger or model-decided	Best for	Not for
CLAUDE.md or AGENTS.md	Every session, at start	Your main context, every request	Model-decided. Claude treats it as context, not enforced configuration	“Always do X” rules, build commands, conventions	Long reference material, anything that must be guaranteed
Skill	Description at session start, full content when used	Your main context, when it loads	Model-decided. Claude interprets the steps	Reference material, repeatable workflows	Guarantees, and heavy side work you want kept out of view
Slash command	Same as a skill. A command file is the older format	Your main context	Same as a skill	Existing command files that still work	New work, where a skill is preferred
Subagent	When you or Claude spawn it	Its own separate window	Model-decided inside, and Claude decides when to spawn it	Context isolation, parallel tasks, specialized workers	Tasks that need your full conversation history
Hook	On a lifecycle event	None, unless the hook returns output	Guaranteed trigger. It always fires on its event	Linting after edits, blocking unsafe commands, logging	Work that needs Claude to reason about what to do

The “when it loads” and “context cost” columns come from Anthropic’s context-cost table. The determinism column comes from its hook versus skill comparison, and the memory page confirms that CLAUDE.md is context, not enforcement.

Skills vs subagents: where the work happens

Anthropic frames the two this way. Skills are reusable content you can load into any context. Subagents are isolated workers that run separately from your main conversation.

That gives one practical difference. A skill adds to your main context window. A subagent uses a separate window with its own input and output tokens, and only a summary comes back to you.

So the question is not which is smarter. The question is whether you want the intermediate work visible in your conversation.

• If you want Claude to follow a checklist while you watch, use a skill.
• If the job reads dozens of files or runs long searches and you only need the conclusion, use a subagent.

Anthropic also lists a trigger for this: a side task floods your conversation with output you will not reference again. That is the moment to route it through a subagent.

Two details keep this from being too tidy. A subagent starts with fresh context. It gets its own system prompt, not the Claude Code system prompt, plus whatever the lead agent passes in the prompt. Most subagents also load CLAUDE.md and git status, although the built-in Explore and Plan agents omit both. So a subagent does not remember what you and Claude discussed unless you pass it along. If the job depends on that history, the docs describe forking the conversation instead, which hands the subagent everything discussed so far.

Can subagents use skills?

Yes, in two directions, and this is the most common confusion in the search results.

Direction one: a subagent that preloads skills. A subagent definition can list skills in a skills field. The full content of each listed skill is injected into the subagent at startup, not only the description. Without that field, a subagent can still discover and invoke project, user and plugin skills through the Skill tool. One limit: you cannot preload a skill that sets disable-model-invocation: true.

Direction two: a skill that runs inside a subagent. Add context: fork to a skill and Claude Code starts a new subagent, using the type in the skill’s agent field, and gives it the skill content as its prompt. The subagent does not see your conversation history, so the skill has to stand on its own. Despite the name, this is not a fork of your conversation.

The docs describe the difference as inverse control. With skills in a subagent, the subagent controls the system prompt and loads skill content. With context: fork in a skill, the skill content is injected into the agent you name. In both cases the subagent starts without your conversation history.

If you want the skill side in depth, including how to write the description that decides whether Claude loads it, I cover that in how to write a Claude Code skill.

CLAUDE.md vs skills

Both store instructions. They differ in when they load.

CLAUDE.md loads every session, automatically. A skill loads on demand: its description is visible at the start, and the full content loads when it is invoked or when Claude judges it relevant. CLAUDE.md cannot trigger a workflow. A skill can, with /<name>.

The docs give a rule of thumb: put it in CLAUDE.md if Claude should always know it, such as coding conventions, build commands and “never do X” rules. Put it in a skill if Claude needs it only sometimes, such as API docs or a release checklist. Keep CLAUDE.md under 200 lines and move reference content out when it grows.

If your repository uses AGENTS.md, Claude Code can read it directly as project instructions. When both files exist, Claude reads the CLAUDE.md files only, unless CLAUDE.md imports AGENTS.md. Reading AGENTS.md directly needs a recent Claude Code version (v2.1.277 or later, as of 09/29/2026). The details are in Claude Code and AGENTS.md.

Skills vs slash commands

This one got simpler. Anthropic’s skills page says custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing command files keep working.

Skills add three things: a directory for supporting files, frontmatter that controls whether you or Claude can invoke them, and the ability for Claude to load them automatically when relevant. The docs say to prefer a skill for new work. So “skills vs commands” is mostly a question about a legacy file format, not a design choice. Claude Code also ships bundled skills, such as /code-review, that work without setup.

Hooks vs skills, and why guardrails belong in hooks

A hook runs at a lifecycle event, and a skill loads into context for Claude to apply. The docs put the difference in one row: a hook always fires on its event and the trigger is guaranteed, while with a skill Claude interprets the instructions and the outcome can vary.

A hook can run a shell command, an HTTP request, an MCP tool call, a prompt or a subagent. Its context cost is zero unless it returns output.

The docs state the consequence plainly. An instruction like “never edit .env” in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook. A hook that exits with code 2 blocks the action, and what it writes to stderr becomes the reason Claude sees. Not every event can be blocked, so check the per-event table before you rely on it. My walkthrough is in the Claude Code hooks tutorial.

The two work together. A PostToolUse hook that runs your linter feeds the results back as text Claude reads, and a /fix-lint skill tells Claude how to resolve them.

Which one should I use: a decision sequence

Walk these in order and stop at the first yes.

1. Must it happen every time, with no judgment involved? Write a hook. Linting after an edit, blocking a dangerous command, logging.
2. Is it a rule or fact Claude should know in every session? Put it in CLAUDE.md (or AGENTS.md). Keep it short.
3. Will the work produce a lot of output or file reading you do not need to see again? Use a subagent, so only the summary reaches your conversation.
4. Is it reference material or a procedure Claude needs only sometimes? Write a skill. If you keep typing the same prompt to start a task, make it a user-invocable skill.
5. Do you need one of the above but with another’s strength? Combine them. A subagent can preload skills, and a skill can run in a subagent with context: fork.

Anthropic also lists triggers for when to add each one. Claude gets a convention wrong twice: add it to CLAUDE.md. You paste the same playbook for the third time: capture it as a skill. You want something to happen every time without asking: write a hook. You do not need to configure everything up front.

The same job, wrong way and right way

Take a job I do often: run the test suite and tell me what failed.

The wrong way. Ask Claude in the main conversation to run the whole suite. Every line of test output lands in your context window. If the suite is large, that output crowds out the conversation you actually wanted to keep. Then add “always run the tests before committing” to CLAUDE.md and assume it will happen. Claude treats that line as context, so it usually will, and sometimes it will not. Both halves use a real tool for the wrong property. The first spends your main context on work you only need summarized. The second asks for a guarantee from a mechanism that does not offer one.

The right way. Split the job by what each half needs.

• The running and summarizing goes to a subagent. Define one whose prompt says to run the suite, then return only the failing tests, the error for each and the file involved. The raw output stays in the subagent’s window, and your main conversation receives a summary. This is the case Anthropic names for subagents: a task that reads a lot and returns only key findings.
• The project-specific knowledge goes in a skill. How tests are run in this repo, which flags matter, which failures are known flaky. Preload that skill into the subagent with the skills field, so the worker starts with the procedure already in its context.
• The must-happen rule goes in a hook. If tests must pass before a commit goes through, a PreToolUse hook on the commit command can check and block. That is the enforcement the CLAUDE.md line could not give.
• The one-line convention stays in CLAUDE.md. “Tests run with this command” costs almost nothing and helps every session.

That is four mechanisms for one job, each doing the part it is built for. I have not measured how much context this saves, and it depends on your suite, so I will not claim a number. The reasoning is the docs’ own: isolation keeps the intermediate work out of your main window.

What I actually run, and where each job went

I run all five mechanisms in my own ~/.claude/ directory. As of 09/29/2026 I counted them with ls: 152 skill folders, 24 agent definition files and 141 entries in the hooks directory. Those are file counts, not usage counts. Three placements taught me more than the counts.

A safety rule that became a hook. For a class of actions I never want an agent to take, the rule first lived in CLAUDE.md as prose. Prose is the request the docs describe, and it can lose to a long task. I moved the rule to a PreToolUse hook that denies those tool calls and gives Claude the reason. A hook removes the choice. The CLAUDE.md line remains, because it tells Claude why the block exists.

A research job sent to a subagent. Research reads a lot and needs a short answer. That matches the docs’ example of a subagent that reads many files and returns key findings. My agents directory holds the specialists I hand that kind of work to, so the main session stays focused on the task at hand.

A workflow that stayed a skill. Anything that needs judgment each time, such as a review checklist where the steps depend on what the code looks like, stayed a skill. A hook cannot reason about what to do, and a subagent would hide steps I want to see.

One more habit came from the docs’ size guidance. When CLAUDE.md grew, I moved reference content into skills, since the docs say to keep it under 200 lines and treat skills as the place for material Claude needs only sometimes.

Are subagents worth it?

They are worth it for one problem and often not for others.

Worth it: a side task that floods your conversation, parallel work, and specialized workers with their own instructions. The docs give context isolation as the key benefit.

Not worth it: short tasks, and tasks that depend on the conversation so far. A subagent starts without your history, so you pay to explain the task again. If you need the history, the docs point to forking the conversation instead.

What this comparison cannot tell you

The docs describe how each mechanism loads, not a benchmark of speed or cost on your codebase. If savings matter to you, measure them on your own repository.

For the wider map of Claude Code features, start with the Claude Code complete guide.