Skills Are the New Dotfiles

For about a year I tried to make Claude Code “know me” by stuffing things into CLAUDE.md: how I name branches, how I write commit messages, where I keep my notes, what shell I use, how I like docstrings. It worked, sort of. The file got long. The instructions started contradicting each other. Half of them only mattered for one specific repo, but they leaked into every conversation.

Then skills shipped, and the model unlocked something I should have seen coming: my CLAUDE.md wasn’t a profile. It was a pile of ten different skills shoved into the same file because I didn’t have a better container.

The reframe is simple. A skill is a small, named, opt-in module of behavior. Claude only loads it when its description matches what you’re actually doing. That changes the math:

• A 200-line CLAUDE.md is always in context, even when you’re asking about CSS specificity. Nothing in it about Joplin should be loaded for that query, but it is.
• A 200-line skill called joplin-mcp-conventions only loads when the conversation involves Joplin. The other 1,400 tokens stay free.

Once I started thinking about it that way, the layout question dissolved. Personal preferences live as bare-name skills symlinked from a single ~/.claude/skills/ directory — weekmac, joplin, reply-drafting, xhs-export, etc. Each one auto-loads on its own intent triggers and otherwise stays out of the way.

Per-repo conventions live as plugin-namespaced skills installed via the plugin marketplace into the repo’s .claude/skills/. Those get their own prefix (my-team:lint-rules) so my personal lint-rules doesn’t shadow them.

The Real Shift: Source-of-Truth

The interesting consequence is the inversion of “the source of truth.” It used to be one big file. Now it’s a directory of files, each named after what they do, and the model is in charge of deciding which to read.

That’s exactly how a developer reads their own dotfiles repo too — .zshrc for shell stuff, init.lua for editor, gitconfig for git. Nobody puts all three into one ~/dotfiles.txt and greps through it on every shell startup.

Skills are the new dotfiles. The patterns we already know — tiny, named, composable, opt-in — apply.