· 2 min read
Briefing Claude Code: Guides, Skills and Gates
On Solo Scores I split what Claude Code needs to know into general principles in CLAUDE.md, task-specific instructions in skills that load on demand, and deterministic gates for the rules that can't be left to chance.
Context is the budget
I build Solo Scores on my own across several repositories, and Claude Code now does a lot of the typing. The real work is deciding what to tell it, and when.
Everything you give an agent competes for its attention. The more that's loaded, the more each instruction gets diluted. So the question isn't just what it needs to know, but when. I ended up with three layers: general principles, task-specific instructions, and the rules that can't be left to the agent at all.
General principles: CLAUDE.md
A CLAUDE.md is loaded into every session, whatever the task. That makes it the most expensive place to put anything, so it holds only principles: things that are true whatever the agent is doing.
For Solo Scores that's which repository a change belongs to, which copy of the data model is the source of truth, and the few rules that cut across everything. If a line only matters for one kind of task, it doesn't belong here, however important it is. Neither do descriptions of the code: the agent can read the code, and descriptions go stale.
Task-specific instructions: skills
Instructions for a particular job go into skills. A skill sits in the background as a one-line description, and its full instructions only load when the task calls for it. Releasing the app and adding analytics are both skills.
Because a skill costs nothing until it's used, it can afford to be long and specific: the steps in order, the checks along the way, and the gotchas learned the hard way. Put the same detail in CLAUDE.md and it would crowd every unrelated task.
My rule of thumb: the second time I do something by hand, it becomes a skill.
Rules that must hold: gates
Both layers are still advice. The agent follows them most of the time, which isn't good enough for the rules that must always hold.
Those get a deterministic gate as well: a test, a script, a hook that runs whether the agent remembers or not. The written rule explains what matters and why. The gate makes sure it happened. If breaking a rule would really hurt, it shouldn't depend on the agent reading carefully.
Takeaways
- Treat context as a budget. Load what's always needed, and nothing else.
- Principles in
CLAUDE.md, task instructions in skills that only load when needed. - Back the rules that matter with a gate. Writing it down is the brief, not the guarantee.