domain-modeling

Domain Modeling

Actively build and sharpen the project's domain model as you design — the active discipline of challenging terms, inventing edge-case scenarios, and writing the glossary down the moment it crystallises. Merely reading CONTEXT.md for vocabulary is not this skill (that's a one-line habit any skill can do); this skill is for when you're changing the model, not just consuming it.

Why it pays off: an opinionated CONTEXT.md is a persistent, shared language. Once the domain has canonical names, variables/functions/files get named consistently, the codebase is easier for an agent to navigate, and the agent spends fewer tokens on thinking because it has a more concise language. The cost is one glossary entry; the payoff compounds every session.

Adapted from mattpocock/skills (MIT) — the domain-modeling skill, with its ADR format left out.

File structure

Most repos have a single context — one CONTEXT.md at the repo root:

/
├── CONTEXT.md          ← the glossary
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts; the map points to where each CONTEXT.md lives (e.g. src/ordering/CONTEXT.md, src/billing/CONTEXT.md) and how they relate. See CONTEXT-FORMAT.md for both shapes.

Create files lazily — only when you have something to write. If no CONTEXT.md exists, create one when the first term is resolved.

Wire it in for future sessions. The payoff — consistent naming and fewer tokens every session — only lands if CONTEXT.md is loaded when future sessions start, not just when this skill fires. When you create CONTEXT.md (or update one and notice it is unreferenced), check the repo's CLAUDE.md: if it does not reference CONTEXT.md, ask the user once whether to wire it in — @CONTEXT.md for a small glossary, or a "consult CONTEXT.md for domain terms" line for a larger one — and add it on yes (don't re-ask on no). If there is no CLAUDE.md at all, mention the option rather than creating one uninvited.