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

Claude kept reaching for a native date input in my forms, even though the project has its own date picker. So I'd correct it, add a line to CLAUDE.md, and carry on. Same again for modals, icons and confirmation dialogs.

It worked, for a while. Then CLAUDE.md was several hundred lines long and I was still repeating myself. I wasn't sure why.

#Why the long file stopped working

CLAUDE.md is loaded at the start of every session. So every line in it is in context for every task, including the ones it has nothing to do with. The rule about date pickers sits there while Claude writes a database migration.

I think that's the problem. More lines doesn't mean more compliance. The important rules get buried under the ones that only matter now and then.

I'd already tried a half fix: short pointers in CLAUDE.md saying "read this document before touching dates". That helped. But I was deciding up front which rules mattered for which task, and writing instructions telling the agent to go and look.

#Let the agent decide

A skill is a folder with a short description at the top and the real content below it:

---
name: ui-conventions
description: Use when building or changing UI. Covers which shared
  components to use for modals, date inputs and confirmations.
---

Only that description is visible up front. The body loads when the agent decides the task matches. I moved the UI rules into one skill like this, and backend tasks stopped paying for them. UI tasks get them without me asking.

What stayed in CLAUDE.md is short and applies to nearly everything: how to run the checks, what never to do, where things live.

#Where it falls over

It worked for me, and I stopped repeating myself. But triggering is a judgement the model makes from the description. With a handful of skills that's reliable. In a large repo with hundreds of them, descriptions start to overlap and it gets patchy. And a skill that didn't fire looks exactly like a skill that doesn't exist.

My workaround is dull: if I know a task needs a skill, I name it in the prompt. Takes a few seconds. I also write descriptions that say when to use the skill, rather than only what it is.

#How I sort rules now

Short rules that apply to everything go in CLAUDE.md. Long rules, or ones for one kind of task, go in a skill. Anything that must happen every single time probably wants a hook or a check, because a sentence in a file is a request, not a guarantee.

Skills only fix half of it, though. They decide what an agent knows. The other half is who does the work, and how much of the reading ends up in your main session. That's subagents, and I'll write about those next.