Blog
Published: September 23, 2026
Put a team rule where its cost matches its reach. CLAUDE.md holds the few facts every session needs. Path-scoped rules hold what applies to one part of the tree. Skills hold procedures and reference loaded on demand. Hooks and permissions hold what must never happen. Subagents hold side work, not rules.
The mechanics below come from Anthropic's extension overview, the memory docs, and the June 2026 post Steering Claude Code, checked 2026-09-23 against Claude Code 2.1.280. That post puts the whole trade in one line: “Each method trades context cost against authority.”
CLAUDE.md vs rules vs skills vs hooks vs subagents, side by side #
| Mechanism | When it loads | Enforced? | Context cost | Known failure mode |
|---|---|---|---|---|
| CLAUDE.md | Session start, full text; nested files when Claude reads in that directory | No. Delivered as a user message after the system prompt | Every request | Contradictions, stale lines, adherence drops as it grows past about 200 lines |
| .claude/rules/ (no paths) | Session start, same priority as .claude/CLAUDE.md | No | Every request | Same as CLAUDE.md; easy to grow unnoticed |
| .claude/rules/ (paths:) | When Claude reads a matching file | No | Only after a match | Does not trigger on every tool use; Bash reads reported not to load it (#95083) |
| Skill | Name and description every turn; body on invoke or auto match | No | Low until used | Vague or overlapping descriptions mean the skill is missed |
| Subagent | When spawned, in its own context window | No | Isolated from the main session | Sees none of the parent conversation; rules must be in its prompt or CLAUDE.md |
| Hook | On lifecycle events (PreToolUse, PostToolUse, SessionStart and others) | Yes. Runs as code; exit 2 on PreToolUse blocks the call | Zero unless it returns output | Pattern matching in your script can miss a variant of the command |
| Permission rule | Checked by the client on every tool call | Yes | Zero | Only covers tools and paths, not judgment |
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.”
---
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.mdso 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.mdor your user files, not the repo. - Is it no longer true? Delete it. Seestale 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.
| Claude Code | Cursor |
|---|---|
| CLAUDE.md | AGENTS.md, or a rule set to Always Apply |
| Path-scoped rule | Rule set to Apply to Specific Files (globs) |
| Skill, auto matched | Rule set to Apply Intelligently, or a skill in .cursor/skills |
| Skill, invoked by name | Rule set to Apply Manually (@-mention) |
| Hook | hooks.json; exit code 2 blocks, like Claude Code |
| Subagent | .cursor/agents, each with its own context window |
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.
Questions #
When should I use a skill instead of CLAUDE.md?
Use a skill for procedures and reference material you need sometimes, like a release checklist. Only its name and description load every turn; the body loads when invoked or matched. Facts every session needs stay in CLAUDE.md.
What is the difference between hooks and skills in Claude Code?
A skill is text Claude reads and interprets, so the outcome can vary. A hook is code Claude Code runs on a lifecycle event, and a PreToolUse hook that exits with code 2 blocks the tool call. Guardrails belong in hooks or permission rules.
What is the difference between .claude/rules and CLAUDE.md?
A rule without paths frontmatter loads at launch like CLAUDE.md. A rule with paths loads only when Claude reads a matching file, which saves context but means it may not load if the work happens only through Bash.
Do subagents read CLAUDE.md?
Custom subagents load the same CLAUDE.md hierarchy as the main session, but not its conversation or the skills it invoked. The built-in Explore and Plan agents skip CLAUDE.md.
What are the Cursor equivalents of CLAUDE.md, skills and hooks?
AGENTS.md or an Always Apply rule for CLAUDE.md, Apply to Specific Files rules for path-scoped rules, skills in .cursor/skills or Apply Intelligently rules for skills, hooks.json for hooks, and .cursor/agents for subagents.