CLAUDE.md or a skill? Where your rules should live

Every time Claude Code got something wrong in one of my projects, I added a line to CLAUDE.md. Use the shared modal component. Don't use a native date input. Use the existing icon wrapper. It's a natural reflex, and it works for a while.

Eventually the file was several hundred lines long, and I noticed two things. I was still reminding Claude about some of the rules. And the file was being loaded for every task, including ones that had nothing to do with most of it.

#Why a long CLAUDE.md backfires

CLAUDE.md is read at the start of every session, so everything in it competes for attention on every task. A rule about form components sits in context while the agent is writing a database migration. More text doesn't mean more compliance. Past a certain point, important rules get diluted by the unimportant ones.

I'd already tried a half-measure: short pointers in CLAUDE.md that said "read this document before touching dates". It helped, but it was manual. I was deciding, in advance, which rules mattered for which task, and writing instructions to the agent to go and look.

#Skills let the agent decide

A skill is a folder with a short description in its frontmatter and the real content in the body. Only the description is visible up front. The body is loaded when the agent decides the task matches.

That's the whole trick. I took the UI conventions out of CLAUDE.md (which components to use for modals, dates, uploads and confirmations) and put them in one skill with a description saying, roughly, "use when building or changing UI". Backend work never pays for those rules, and UI work gets them without me asking.

What stayed in CLAUDE.md is the small set of rules that apply to nearly everything: how to run the checks, what to never do, where things live.

#It worked, with caveats

For me it did what I wanted. I stopped repeating myself and the main file got a lot smaller.

The catch is that triggering depends on the description matching the task, and that's a judgement call the model makes. In a project with a few skills, it's reliable. In a large repo with hundreds of them, descriptions start to overlap and it gets less dependable. A skill that didn't fire looks exactly like a skill that doesn't exist.

The workaround is unglamorous: if you know a task needs a particular skill, name it in your prompt. It takes a few seconds and removes the guesswork. I'd also keep descriptions specific, and say what the skill is for and when, rather than what it is.

#A rough rule for sorting

Rules that apply to every task, and are short, belong in CLAUDE.md. Rules that apply to one kind of task, or are long, belong in a skill. Anything that has to happen every time without exception probably wants a hook or a check, not a sentence for the model to remember.

There's a second half to this problem, which is how work gets split between agents and not only how knowledge gets loaded. Skills decide what an agent knows. Subagents decide who does the work, and that's the next thing I want to write about.