CLAUDE.md vs Skills: What Goes Where

If your CLAUDE.md is over 200 lines, something has gone wrong. Not because long files are inherently bad — because CLAUDE.md serves a specific, narrow purpose, and every line that drifts outside that purpose is a line that degrades session quality.

The decision rule is simple: if the model could figure this out by reading your repo, it doesn't belong in CLAUDE.md.

What CLAUDE.md Actually Is

CLAUDE.md is a Claude Code primitive. It gets loaded automatically into every session launched from your working directory. You didn't have to invoke it. You didn't have to include it in a prompt. It's just there, injected into the context before you type your first message.

That automatic injection is the key constraint. Because it's always loaded, everything in it costs tokens on every session — including sessions where that content is completely irrelevant. A CLAUDE.md that describes how to run your deploy pipeline costs deploy-pipeline tokens every time you ask Claude to fix a typo in a README.

This is why the right mental model is session-level constitution, not manual. A constitution establishes facts about the environment — the topology, the constraints, the hard rules. It does not describe procedures. Procedures change. Topology changes rarely.

What Belongs in CLAUDE.md

Environmental topology. The facts about your setup that Claude cannot discover by reading code.

Concrete examples from production use:

Host detection — Which machine is this? What's the Tailscale IP? Does production route here or not? Claude cannot figure this out from your repo.
Homebrew PATH configuration — Non-interactive SSH sessions on macOS don't inherit Homebrew. Claude needs to know to prefix commands with the explicit path.
Launchd plist locations — Where do your service plists live? What's the naming convention? These are filesystem facts, not code.
Docker socket paths — Where does the Docker daemon listen on this machine?
Known service ports — What's running on 8001 vs 8002 vs 18789? Claude can't infer this from your codebase.
Hard behavioral rules — Never commit to main. Never use --force without explicit instruction. These are session-level constraints with no procedural content.

These facts are stable. Your Tailscale IP doesn't change. Your launchd path doesn't change. The Docker socket path doesn't change. You update this section when the topology changes — which happens rarely.

What Does NOT Belong in CLAUDE.md

Procedural knowledge. Anything that answers the question "how do I do X?"

How to run a deployment? That's a skill.
How to write a skill file? That's a skill.
How to format a commit message? That's a skill.
How to open a PR? That's a skill.
How to trigger a cron job manually? That's a skill.

The distinction matters because procedures evolve. The deploy process you wrote down in January breaks in March when you switch from Docker Compose v1 to v2. If that procedure lives in CLAUDE.md, you now have a stale instruction that loads into every session. If it lives in a skill file, it's isolated, versioned, and clearly invoked only when needed.

The Warning Signs

Your CLAUDE.md has drifted into skills territory when you see:

File length over 200 lines. Not a hard rule, but a reliable signal. If you need 200+ lines to describe your environment, you're describing more than your environment.

Numbered procedural steps. "1. Pull the latest changes. 2. Export the PATH. 3. Run docker compose build." That's a skill, not a topology fact.

Conditional blocks. "If you're on your laptop, do X. If you're on the production server, do Y." This one is nuanced — host-conditional behavior can legitimately live in CLAUDE.md. But if the conditional controls a procedure rather than a topology fact, it belongs in a skill.

Repeated "How To" sections. "How to deploy," "How to run tests," "How to write a commit." Multiple how-to sections in CLAUDE.md is a clear signal that procedures have migrated in.

Sections that only apply to certain tasks. If a section is only relevant when Claude is doing a specific kind of work, it's not a session-level fact — it's task-specific context. Move it to a skill.

The Correction

When you find drifted content, the fix is straightforward: move it to ~/.claude/skills/<name>/SKILL.md.

Each skill is a directory containing a SKILL.md file, with name and description YAML frontmatter at the top — the description is what registers at session start. The agent reads the description when it decides which skill to invoke, then loads the full content only when the skill is actually needed.

~/.claude/skills/
  deploy-mac-mini/SKILL.md       ← deploy procedure (was in CLAUDE.md)
  open-pr/SKILL.md               ← PR workflow (was in CLAUDE.md)
  run-cron-manual/SKILL.md       ← manual cron trigger (was in CLAUDE.md)
  commit-format/SKILL.md         ← commit message format (was in CLAUDE.md)

After the move, your CLAUDE.md is leaner, your skill library is richer, and the maintenance burden is split correctly: topology facts in one place, procedures in another, each updated on its own cadence.

Why This Matters at Scale

A single misclassified procedure is a minor inefficiency. At scale — 20 skills worth of procedures in CLAUDE.md, running a high-frequency agent 200 times a day — it becomes a real cost. Every session pays for procedures it will never use. The agent's effective context window shrinks because irrelevant instructions are consuming space that could hold working context.

The deeper problem is instruction fatigue. Claude holds a lot in active attention, but not infinitely. A CLAUDE.md that mixes topology facts with deploy procedures with PR format guidelines with test runner commands is asking Claude to hold everything at once, every time. Some of those instructions will be followed. Others will be quietly ignored. You won't know which ones until something goes wrong.

Keep CLAUDE.md lean. Move procedures to skills. Let progressive disclosure handle the rest — which is exactly what the next lesson covers.