CLAUDE.md, Skills, Subagents, Hooks: When to Use Which

CLAUDE.md, skills, subagents, and hooks in Claude Code each answer a different question, so they are not interchangeable. CLAUDE.md is what Claude always knows, a skill is a procedure Claude runs on demand, a hook is a rule the harness enforces no matter what Claude decides, and a subagent is a clean side-room where Claude thinks in isolation. Pick the wrong layer and you waste tokens, break repeatability, or fail to enforce a rule you thought was locked in.

---

---

The 10-second answer

Match the primitive to the job:

• Use CLAUDE.md for facts Claude needs every single time (repo layout, naming rules, hard constraints).
• Use a skill for a step-by-step playbook Claude pulls in only when a task matches it.
• Use a hook for something that must happen at a fixed moment, even if Claude would rather skip it.
• Use a subagent when a task needs its own clean context, a limited tool set, or needs to run beside other work.

Why this matters to you

The wrong layer is not a style choice. It shows up on your bill and in your reliability. CLAUDE.md is reloaded into context on every turn, so anything you put there is paid for constantly. A skill costs almost nothing until it fires. A subagent carries heavy fixed overhead each time it spawns. A hook costs zero model tokens because the harness runs it outside Claude entirely. Knowing this lets you spend tokens where they earn their keep.

The four primitives, plainly

CLAUDE.md is a markdown file at the root of your repo. Claude reads it at the start of every session and keeps it in working memory the whole time. Think of it as the orientation packet a new hire reads on day one: "here is how this codebase is laid out, here is what we never do." It is advisory. Claude can still drift from it. Keep it short. If it balloons, every turn gets more expensive.

Skills are folders with a SKILL.md file inside. At startup Claude only reads the skill's name and one-line description, which costs about 100 tokens. The full instructions load only when your task matches the trigger. A skill is a recipe card: "to deploy, run these six steps in this order." Skills follow the Agent Skills open standard that Anthropic published in December 2025, which makes a SKILL.md file the most portable AI artifact you can write. Reported support spans roughly 40 tools as of June 2026, including OpenAI Codex CLI, Gemini CLI, and GitHub Copilot, so the same file runs unchanged across them.

Hooks are small programs the harness runs at named moments in a session. They fire at lifecycle events like PreToolUse (just before Claude uses a tool), PostToolUse, SessionStart, and PreCompact. Anthropic's docs list dozens of such events. Hooks support several handler types (a shell command, an HTTP call, an MCP tool, a prompt, or a sub-agent). The important part: a hook runs outside Claude's context and Claude cannot override it. A hook is the building's fire door that locks on a schedule whether or not anyone wants it open.

Subagents are separate Claude instances spawned for one job. Each carries its own system prompt, its own tool allowlist, and optionally its own model. They give you context isolation (the side-room does not clutter your main chat), parallelism (several can run at once), and safety (a read-only subagent simply has no write tools). They can nest a few levels deep and run several at a time. A subagent is a contractor you hand one sealed task, who reports back a result without dumping their whole scratchpad on your desk. Our deeper write-up on Claude Code subagents covers patterns in detail.

Comparison table

Token figures for subagents and skills are reported community and Anthropic guidance, not guarantees. Treat them as planning numbers.

A worked example

Say you run a Next.js app with row-level security on every table.

1. Put "every table needs an RLS policy; never use the service role key in client code" in CLAUDE.md. It is a fact Claude must hold at all times.
2. Write a skill called add-table that walks through creating a migration, writing the policy, and adding a test. It loads only when you ask for a new table.
3. Add a hook on PreToolUse that blocks any write to a migrations folder that lacks an RLS policy. Now the rule holds even if Claude forgets the CLAUDE.md note.
4. Spawn a read-only subagent to audit existing policies in parallel while the main agent keeps building. It has no write tools, so it cannot change anything by accident.

When primitives collide

What if a hook blocks all file writes and a skill tells Claude to write a config file? The hook wins, every time, because it runs outside the model and cannot be overridden. Write that hierarchy down in CLAUDE.md so future-you is not confused when a skill "silently fails." The rule of thumb: hooks are law, CLAUDE.md and skills are guidance, subagents are scoped workers.

One more simplification worth knowing: in Claude Code, custom slash commands are now part of skills. A file at .claude/commands/deploy.md and one at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. That means one primitive to learn, not two.

If wiring these four layers together sounds like a lot of plumbing, the Build This Now $29 Code Kit ships them pre-configured as a Claude Code build system: agents, skills, hooks, and a production SaaS skeleton (auth, Stripe payments, PostgreSQL) already set up so Claude Code ships working apps instead of snippets. It runs on Claude Code, which needs its own subscription.

FAQ

What is the difference between CLAUDE.md and a skill in Claude Code?

CLAUDE.md loads automatically at session start and stays in context the whole session, so it is for facts Claude always needs. A skill loads only its name and description (about 100 tokens) at startup and pulls in the full instructions only when a matching task fires, which makes it the right home for step-by-step procedures you invoke on demand.

When should I use hooks vs skills in Claude Code?

Use hooks when something must happen at a lifecycle event no matter what Claude decides, since hooks run outside the model's context and cannot be overridden. Use skills when you want Claude to follow a procedure it chooses to invoke based on the task in front of it.

How much do Claude Code subagents cost in tokens?

Each subagent spawn carries roughly 20,000 tokens of fixed overhead before any real work starts, and multi-agent sessions are reported to use 3 to 4 times more tokens than single-threaded ones. Reach for subagents when you genuinely need context isolation or parallel work, not as a default.

Are Claude Code skills compatible with other AI tools?

Yes. Skills follow the Agent Skills open standard Anthropic published in December 2025. As of June 2026 it is reportedly supported by around 40 products, including OpenAI Codex CLI, Gemini CLI, and GitHub Copilot, so a SKILL.md you write for Claude Code runs unchanged in those tools.