Claude Code has five customization layers. CLAUDE.md, Skills, subagents, hooks, and MCP servers. Pick the wrong one and you get a Skill that never fires, a hook doing subagent work, or a CLAUDE.md so bloated it eats half your context before you type.

Here's where each one belongs.

CLAUDE.md

Loads into every conversation. Use it for rules you never want skipped, like "TypeScript strict mode" or "never touch the database schema."

If a rule only matters sometimes, it doesn't belong here. You'll pay tokens for it on every prompt.

Anthropic's published rule of thumb is to keep CLAUDE.md under 200 lines. For every line, ask whether removing it would actually cause Claude to make mistakes. If not, cut it. A bloated CLAUDE.md doesn't make Claude obey more rules, it makes Claude ignore half of them because the important ones get lost in the noise.

If it does grow past 200 lines, the official guidance is to move reference content to Skills or split into .claude/rules/ files that only load when Claude works on matching paths.

Skills

Markdown files Claude auto-loads when a request matches the description in their frontmatter. The right home for PR review checklists, release procedures, library-specific conventions, anything task-specific.

The description has to cover two things, what the skill does and when to use it. Skip the when and Claude never loads the skill, no matter how good the body is. Put the key use case first, since the description is capped at 1,536 characters in the skill listing.

The body has its own limit. Anthropic recommends keeping SKILL.md under 500 lines and moving long reference material into separate files the skill links to. Once a skill loads, its content stays in context for the rest of the session, so every line is a recurring token cost.

Subagents

Run in their own context window. You hand one a task, it works independently with its own token budget, and you get the result back.

Best for parallel research, isolating noisy work, or tasks needing tools you don't want in your main session. Coordinating several at once takes some care, since they don't share state.

Subagents can use Skills too, but you have to wire them in explicitly with the skills frontmatter field. Unlike the main session, skill descriptions aren't auto-loaded into the subagent, so triggering by description match doesn't happen on its own.

Hooks

CLAUDE.md instructions are advisory, Claude decides whether to follow them. Hooks are deterministic. The event fires, the hook runs, no judgment involved. They're the only one of the five that bypasses the model entirely.

The events most people hook into are PreToolUse (validate or block a tool call before it runs), PostToolUse (react after a tool call, like linting files Claude just edited), UserPromptSubmit (intercept what gets sent to Claude), and SessionStart (load context once per session).

This is why hooks are the right place for guardrails. "Never edit .env" in CLAUDE.md or a Skill is a request. A PreToolUse hook that blocks the edit is enforcement.

If your rule is "run X every time Claude does Y," that's a hook. Linters, formatters, validators, audit logging.

MCP servers

The other four shape how Claude thinks. MCP gives Claude new things to do, like talking to APIs, databases, or internal systems. Sometimes a CLI is enough, sometimes you actually need an MCP server.

How they combine

CLAUDE.md for hard rules
Skills for procedures and domain knowledge
Subagents for delegated work
Hooks for automatic side effects
MCP servers for the outside world

The trap is dumping everything into Skills. A constraint that always applies still belongs in CLAUDE.md. A side effect on file save still belongs in a hook.

For the long version, Anthropic's free Introduction to Agent Skills course on Skilljar walks the whole rubric, and the three-minute video covers it in the time it takes to brew coffee.

#agent-skills

Skills, CLAUDE.md, subagents, hooks, or MCP, when to use which

Stay Updated