Skills and the context architecture
By now the pieces are familiar individually. This part is about seeing them as one system. A skill does not exist on its own — it lives inside a context window alongside CLAUDE.md, the project, and the work itself. Designing skills well is really about designing what occupies that window and when.
Where a skill ends and CLAUDE.md begins
The cleanest architectural decision you make repeatedly is this: does a given piece of information belong in CLAUDE.md or in a skill?
The rule is about always-true versus conditional. CLAUDE.md holds what is always true about the project — the architecture, the conventions, the file layout, the standing facts — and it loads from the start. A skill holds a procedure you reach for when a particular task arises. If you find yourself restating the same project facts inside several skills, those facts belong in CLAUDE.md, and the skills should rely on them being present.
This is not theory; it is how production skill libraries are organised. The skills supply generic, reusable procedure. CLAUDE.md remains the single source of truth for the local facts. Keep that separation and both stay lean and neither drifts out of sync with the other.
How the context budget actually behaves
Three things are worth knowing precisely, because they drive the design:
Discovery is cheap; the body is not. Every skill's short description is loaded from the start so Claude knows the skill exists — that costs very little. The body is different: it loads only when the skill is triggered, but once it does, it persists in context for the rest of the session. It is not re-read each turn, and it is more than just metadata once active.
A persistent body occupies the budget. Because the body stays once loaded, a long skill takes up room the entire time — room the actual work needs. This is the architectural reason to keep skills lean: not tidiness, but reserving context for the task.
Detail belongs in referenced files. Bulky material — long checklists, large examples, lookup tables — should live in separate files the skill loads only when it needs them. They come in on demand and leave the rest of the time. A lean skill that points to good references is the design the context budget rewards.
A practical note: after a long session compacts, recently used skills are re-attached within a shared budget, most-recent first — so if a large skill stops shaping behaviour mid-session, re-invoke it rather than assuming it is still fully present.
Why clearing context still matters
Skills do not remove the work-loop habit of clearing context between phases — they make it more important. When you move from planning to building, you want the planning noise gone and the right skill plus the relevant code loaded cleanly. A skill is a reusable input to that fresh context, not a reason to let one long, muddy thread run forever. Read the project, load the skill you need, do the phase, clear, repeat.
What comes next
The final part of this series makes all of this concrete: a walkthrough of a real production skill library, what makes its skills production-grade, and the defensive patterns worth copying.
Next in this series: Part 4 — Production skills: a real library