The Customisation Hierarchy

Layer 1: CLAUDE.md — permanent project memory

CLAUDE.md is the foundation. It loads at the start of every session, in full, regardless of what task you are about to do. This makes it the most powerful layer — and the most expensive.

Every line in your CLAUDE.md costs tokens on every conversation. A 200-line file is loaded 200 lines every time. This means CLAUDE.md should contain only information that is relevant to every possible task: build commands, project architecture, universal coding standards, and team conventions that always apply.

CLAUDE.md files live in multiple locations with a strict precedence:

1. Project root — ./CLAUDE.md or ./.claude/CLAUDE.md
2. User home — ~/.claude/CLAUDE.md (your personal defaults)
3. Managed policy — system-level, set by organisation admins

All three load and accumulate. Project-level instructions take precedence over user-level instructions which take precedence over managed policy.

Key rule: If you would not put it in a new hire's onboarding doc, it does not belong in CLAUDE.md.

Layer 2: Rules — modular, scopeable extensions

Rules live in .claude/rules/*.md. They extend CLAUDE.md without bloating it. The critical feature: rules can be path-specific.

A rule file with a paths field in its frontmatter loads only when Claude is working with files that match those patterns. Your React component conventions load when Claude touches src/components/**/*.tsx. Your API design rules load when Claude touches src/api/**/*.ts. Your database migration rules load when Claude touches migrations/**/*.sql.

Rules without a paths field load at startup, just like CLAUDE.md. Use these for standards that apply broadly but are detailed enough to warrant their own file rather than cluttering CLAUDE.md.

When to use rules vs CLAUDE.md: If the instruction applies to every session and is under 200 lines total, keep it in CLAUDE.md. If it applies to specific file types or is detailed enough to warrant its own document, make it a rule.

Layer 3: Skills — on-demand recipes

Skills are where the hierarchy shifts from always-loaded context to on-demand knowledge. A skill is a markdown file in .claude/skills/<skill-name>/SKILL.md with frontmatter that tells Claude when to load it and a body that provides instructions for a specific task.

The mental model: a skill is a recipe. It tells Claude the ingredients, the steps, the techniques for a specific job. But the recipe does not cook itself. It loads into your current conversation, and Claude follows the instructions using the tools and context already available.

Skills trigger in two ways. Claude can auto-detect relevance based on the skill's description field and load it automatically. Or you can invoke a skill explicitly by typing /skill-name as a slash command. Either way, the skill's full content injects into your current conversation context.

The critical distinction from agents: skills share your conversation. The knowledge loads into the same context window you are working in. This is efficient for lightweight tasks but means the skill content competes for context space with everything else in your session.

Three scenarios for skills:

1. Reusable conventions. Your PR review checklist, commit message format, API design patterns. Knowledge Claude needs sometimes, but not always. If it were always needed, it would be in CLAUDE.md.
2. Quick workflows. Generating a changelog, running a specific check, formatting a response. Fast, in-line operations that do not require isolation.
3. Team knowledge. Testing strategies, error handling patterns, deployment procedures. Portable across conversations, shareable across the team via version control.

Layer 4: Agents — isolated specialists

Here is where the hierarchy makes its most important leap. Everything so far — CLAUDE.md, rules, skills — operates within your conversation. Agents operate outside of it.

An agent is a separate Claude instance. It has its own context window, its own system prompt (the markdown body of the agent file), its own set of available tools, and optionally its own copy of the repository via worktree isolation. When Claude delegates a task to an agent, that agent works independently and returns a result. Your main conversation never sees the intermediate work.

The mental model: an agent is a chef. You hire a chef, give them a brief, and they go into their own kitchen to cook. They use their own tools, make their own decisions, and bring back a finished dish. You do not stand over their shoulder. You do not lend them your kitchen.

Agents live in .claude/agents/<agent-name>/AGENT.md. The frontmatter defines their capabilities — which tools they can use, which model they run on, what permission level they operate at. The markdown body becomes their system prompt.

Three scenarios for agents:

1. Heavy exploration. Reading 50 files, grepping through thousands of lines, mapping an unfamiliar codebase. If this happens in your main conversation, your context window gets destroyed. An agent does it in its own context and returns a clean summary.
2. Restricted access. A code reviewer that can only read files, not edit them. A database query agent that can only use bash. Agents let you enforce tool boundaries that skills cannot.
3. Parallel work. Spawn three agents in separate worktrees. One builds the API, one writes tests, one updates docs. They work simultaneously, each on their own branch, without interfering with each other or your working directory.

Layer 5: Hooks — deterministic guardrails

Every layer so far depends on Claude interpreting instructions and choosing to follow them. Claude is very good at this, but it is not deterministic. A 300-line CLAUDE.md might get partially ignored. A skill might not trigger when you expect it to. An agent might deviate from its system prompt on edge cases.

Hooks are different. Hooks are shell commands, HTTP calls, or LLM prompts that execute automatically at specific lifecycle points in Claude Code. They do not depend on Claude's judgement. They fire deterministically, every time.

Hooks are configured in .claude/settings.json and can respond to events like:

• PreToolUse — before Claude runs any tool (can block dangerous operations)
• PostToolUse — after a tool completes (can run linting after every file edit)
• UserPromptSubmit — when you send a message (can inject context)
• SessionStart — when a session begins (can set up environment)

The critical feature: hooks can block actions. A PreToolUse hook that returns exit code 2 prevents Claude from executing that tool call entirely. This means you can enforce rules that Claude literally cannot violate — no deleting production files, no committing without tests passing, no pushing to main without review.

When to use hooks vs skills: If Claude should know about a standard, use a skill. If Claude must comply with a standard, use a hook.

Layer 6: MCP — extended capabilities

The first five layers define what Claude should do. MCP defines what Claude can do.

Model Context Protocol servers add new tools to Claude's toolkit. A GitHub MCP server gives Claude the ability to create pull requests, read issues, and search repositories. A PostgreSQL MCP server lets Claude query databases. A Slack MCP server lets Claude send messages.

MCP is configured in .claude/.mcp.json and loads at session startup. Each server provides a set of tools that Claude can choose to use, just like the built-in Read, Write, and Bash tools.

MCP is orthogonal to the other layers. It extends capabilities; the other layers shape behaviour. A skill might instruct Claude to "check the GitHub issue for requirements before starting" — MCP is what makes that possible by providing the GitHub tools.

For this course, MCP is mentioned for completeness but is not the focus. The five layers above — CLAUDE.md, rules, skills, agents, and hooks — are where most configuration value lives.

The composition model

The power of the hierarchy is not in any single layer — it is in how they compose.

Skills inside agents. An agent can preload skills using the skills field in its frontmatter. This means the agent starts with domain knowledge already in its context. A code review agent that preloads your code-review-checklist skill and your security-standards skill produces reviews against your actual standards from the first file it reads.

Hooks enforcing agent output. A hook can validate that an agent's output meets quality standards before it returns to your main conversation. The agent writes code in a worktree, the hook runs linting, and only clean code comes back.

Rules scoping skill relevance. Path-specific rules can set context that makes skills more effective. When Claude is working in your API directory, the API design rules load, and skills for API testing become more relevant.

The mental model for the full system:

• CLAUDE.md is the onboarding document — what every session needs to know
• Rules are the departmental guidelines — what specific domains need to know
• Skills are the standard operating procedures — how to do specific jobs
• Agents are the specialists — people you hire for specific tasks
• Hooks are the compliance checks — rules that execute automatically, no exceptions
• MCP is the equipment — tools that extend what anyone in the system can do