What goes in CLAUDE.md, what in a skill, what in a hook?

What goes where, when to add each, and how to keep CLAUDE.md short enough to be obeyed.

Three parts

You want Claude Code to follow your project's rules without you repeating them. Three parts do this. We think of all three as context engineering: the right information at the right time.

CLAUDE.md: a memory file Claude Code reads at the start of every session. It holds rules and pointers.
Skills: packaged instructions. You write a SKILL.md file, and Claude loads it when a task needs it.
Hooks: commands that run at set points, so certain actions always happen.

When to add each

You do not need all three on day one. Each has a trigger, so add it when the trigger shows up.

Claude gets a convention or command wrong twice: add it to CLAUDE.md.
You keep typing the same prompt to start a task: save it as a skill.
You want something to happen every time without asking: write a hook.
A side task floods your conversation with output you will not need again: use a subagent.

Keep CLAUDE.md short

The target is under 200 lines per file. Longer files use more context and may be followed less well. Keep only what Claude cannot work out from the code itself. Claude may ignore a file full of rules that do not apply to the task at hand. If two lines contradict each other, Claude may pick one at random.

Write rules you can verify

Concrete beats vague. “Use 2-space indentation” works. “Format code properly” does not. “Run npm test before committing” works. “Test your changes” does not.

What to leave out

Anything Claude can read from the code.
Code style rules. A linter does that job faster and cheaper.
Details that only one task needs. Put them in a separate note and point to it.
Copies of code or facts that change often. Point to the file instead, because copies go out of date.

A skill is a recipe card

This is our picture of a skill. It is a SKILL.md file with a name, a description that tells Claude when to use it, and the steps. Claude Code loads a list of skill names and descriptions, so it knows what is available. The full steps load only when the task needs them, so a skill costs little until then.

Test a skill

Collect a few realistic prompts. Run each in a fresh session with the skill and again with it turned off, then compare. We think a skill that does not improve the result is not earning its place.

Start here

We would start in this order:

Write down the rules you repeat most, in CLAUDE.md.
Turn one repeated task into a skill.
Turn one rule that must never be skipped into a hook, because a rule in CLAUDE.md is only context, not enforced.

Check

Run /doctor prompt-audit in a session. It flags lines that contradict each other or point at files that do not exist.
Run your skill on the same prompts with and without it, and compare the results.
Ask Claude to do the thing a hook guards against. The hook must stop it every time.