CLAUDE.md vs skills vs hooks vs rules vs subagents

CLAUDE.md vs rules vs skills vs hooks vs subagents, side by side

What belongs in CLAUDE.md?

Facts Claude should hold in every session and cannot read off the code: the build and test commands, the one gotcha that bites every newcomer, a convention that differs from the tool's default. The docs say to keep it under 200 lines, and warn that longer files “consume more context and reduce adherence.”

The test is reach. If a line matters for one directory, one file type, or one workflow, it is paying rent on every request for a task that does not need it. Move it. And do not split a long file with @imports to shrink it: imported files still load at launch.

Claude Code rules vs CLAUDE.md

A rule in .claude/rules/ without frontmatter is CLAUDE.md in a separate file. It loads at launch with the same priority. The organisational win is real; the context win is nothing.

The context win comes from paths:. A rule scoped to payments/** reaches Claude when it reads a payments file, and not while it edits CSS. Two caveats. Path-scoped rules “trigger when Claude reads files matching the pattern, not on every tool use,” so a session that only greps and runs commands may never see the rule. And a rule a user wrote in ~/.claude/rules/ sits beside the project's; if they conflict, “Claude may follow either one.”

# .claude/rules/payments-webhooks.md
---
paths:
  - "payments/webhooks/**/*.ts"
---

- Webhook handlers are idempotent: dedupe on the provider event ID
  before any write. Decided in #eng-payments after the double refund.

When should I use a skill instead of CLAUDE.md?

When the content is a procedure or reference you need sometimes. The steering post says it directly: “Instructions that are procedural, like deploy workflows, release checklists, or review processes, belong in a skill.” Only the name and description ride along every turn. The body loads when you type /release or Claude matches the description to the task.

The failure mode is the matching. The overview warns that if descriptions are vague or overlap, Claude “may load the wrong skill or miss one that would help.” Vercel measured the size of that gap on their own Next.js evals in January: the skill was never invoked in 56 percent of cases, and an 8KB docs index placed in AGENTS.md scored 100 percent against 79 percent for the best skill setup (Vercel). One team's eval, on one framework, but the lesson carries: a skill is only as good as its trigger. Anything Claude must know before it knows to ask belongs in the always-on layer, stated short.

Hooks vs skills

A skill is text Claude reads and interprets. A hook is code the client runs. The overview table says it in two cells: a hook “always fires on its event; the trigger is guaranteed,” while with a skill “Claude interprets the instructions; outcome can vary.”

So guardrails go in hooks. The docs' own example: “never edit .env” in CLAUDE.md or a skill “is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement.” A PreToolUse deny holds even in bypassPermissions mode. For a plain allow or deny on a command, the hooks guide prefers permissions.deny in settings, because a hook's own pattern matching is best effort.

The two combine well. A PostToolUse hook runs the linter after every edit and feeds the output back as text; a /fix-lint skill tells Claude how your team resolves what it finds.

Where do subagents fit?

Subagents are not a place to store a rule. They are a place to run a side task (a dependency audit, a log trawl) in a separate context window so the main conversation gets a summary instead of the noise. Each one starts fresh: it “doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read.” It does load the same CLAUDE.md hierarchy, except the built-in Explore and Plan agents, which skip it.

That last clause is the one that bites. A team rule that only lives in the conversation, or in a skill the parent invoked, does not reach the subagent. Put rules a subagent needs in its own prompt, in its skills: list, or in CLAUDE.md.

A decision path for one team rule

• Would breaking it destroy something? Hook or permission rule. Keep a one-line note in CLAUDE.md so Claude knows why it was refused.
• Does it apply to every task in the repo? CLAUDE.md, one line, concrete enough to check.
• Does it apply to one part of the tree? A path-scoped rule. Unscope it if the work there often happens through Bash.
• Is it a procedure or a long reference? A skill with a description that names the task in the words people use.
• Is it only yours? CLAUDE.local.md or your user files, not the repo.
• Is it no longer true? Delete it. See stale rules.

Cursor rules vs skills: the equivalents

Cursor has converged on nearly the same set, per its rules, skills, hooks and subagents docs, checked 2026-09-23.

The same rule of reach applies. The difference that matters for teams is that the two tools read different files, which is the subject of AGENTS.md vs CLAUDE.md.

What none of these mechanisms do

Every mechanism above answers “how does this text reach the model?” None answers “is this still what we decided?” or “did anyone use it?” The webhook rule in the example came out of a thread in #eng-payments. Someone had to notice it, write it into the right file, keep it in sync with the Cursor copy, and remember to delete it when the team changes its mind.