domain-modeling

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 1,299 words, so you can see where the weight sits before reading.

1. 1What it produces40 words
2. 2Where things live162 words
3. 3During the conversation231 words
4. 4Glossary rules192 words
5. 5ADRs: offer them sparingly185 words
6. 6Writing safely102 words
7. 7Not every change belongs here66 words
8. 8Done when51 words
9. 9Mistakes to avoid129 words

The skill itself

Read it before you install it

---
name: domain-modeling
description: Build and sharpen a project's shared domain language while a design is being made - challenge vague or overloaded terms, break them with edge-case scenarios, check them against the code, and write resolved terms into a glossary and hard-to-reverse decisions into ADRs as they settle. Use when the user is pinning down terminology or a "ubiquitous language", asks "what should we call this", says two words mean the same thing or one word means two things, or wants a glossary, CONTEXT or GLOSSARY file, or an ADR written or updated. Not for designing entities, schemas or aggregates (see domain-model-design), not for merely reading an existing glossary, and not for documenting how code works.
license: MIT
---

# Domain modeling: sharpen the project's language

Two words for one concept, or one word for two concepts, is how a codebase and the people working on it drift apart. This skill is the active discipline of fixing that while a design is being made: challenge vague terms, break them with edge cases, check them against the code, and write the result down the moment it settles.

Reading an existing glossary to learn the vocabulary is not this skill; any task can do that in one line. Use this skill when the model itself is changing: a term is being defined, renamed, split, or disputed.

## What it produces

- A **glossary**: the project's own terms, one canonical word per concept.
- **ADRs** (architecture decision records), but only for the few decisions that deserve one.
- A short list of **open ambiguities** that were found and not yet resolved.

## Where things live

Follow the project's existing convention for glossary and decision records if it has one. If it has none, use:

- `GLOSSARY.md` at the repository root.
- `docs/adr/0001-short-title.md`, numbered in order, for decisions.

Many projects call the glossary `CONTEXT.md`. If the repository already does, keep that name. For a new file, a name like `GLOSSARY.md` avoids confusion with any files that give an AI agent instructions or background.

If the repository has several real contexts (separate teams or deployable parts whose words differ), keep a root `GLOSSARY-MAP.md` that lists each context, where its glossary lives, and how the contexts relate. Each context keeps its glossary and its own ADRs beside its code; system-wide ADRs stay in `docs/adr/`. Work out which context the current topic belongs to, and ask if it is unclear.

**Create files lazily.** No glossary until the first term is resolved, no ADR folder until the first ADR is needed. An empty glossary is worse than none, because it looks maintained.

## During the conversation

1. **Challenge against the glossary.** When the user uses a term in a way that conflicts with its written definition, say so at once: "The glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
2. **Sharpen fuzzy language.** When one word is doing several jobs, propose a separate canonical term for each concept: "You said 'account'. Do you mean the Customer or the User? Those are different things."
3. **Stress-test with scenarios.** Invent concrete edge cases that force a precise boundary between two concepts: "A customer returns one item from a three-item order. Is the order cancelled, partly cancelled, or something else?" A definition that cannot classify the edge case is still fuzzy.
4. **Check the code.** When the user says how something works, look at whether the code agrees, and raise any contradiction: "The code cancels whole orders, but you just said partial cancellation is possible. Which is right?" The code shows current behavior, not intended behavior. Do not assume it is correct, and do not assume the user's memory is.
5. **Write it down as it settles.** Update the glossary when a term is resolved, one term at a time. Batched updates tend never to happen.

When a term cannot be resolved yet, do not guess. Record it under **Open questions** with the question stated, so it is parked on purpose rather than forgotten.

## Glossary rules

- Only terms specific to this domain. General programming concepts do not belong, however heavily the project uses them.
- One or two sentences saying what the thing **is**. No implementation detail, no plans, no specs, no progress notes. The glossary is not a scratch pad or a place for design decisions.
- An **Avoid** line listing rejected synonyms, so the concept never travels under two names.
- When one word meant two things, split it into two named terms and retire the overloaded word, listing it under Avoid for both.
- Add a one-line domain example or a distinction from a neighboring term only when it prevents a likely misreading.

Entry shape:

```
**Order**: a customer's request to buy, from placement until it is fulfilled or cancelled. Holds one or more line items.
_Avoid_: purchase, basket (a basket is not yet an order).

**Cancellation**: the withdrawal of an entire order before it ships. Removing one line item is a *line removal*, not a cancellation.
_Avoid_: void, abort.

## Open questions
- Is a return after shipping a cancellation, a refund, or its own thing? (raised with the user, not decided)
```

## ADRs: offer them sparingly

Offer an ADR only when **all three** are true:

1. **Hard to reverse.** Changing your mind later costs something real.
2. **Surprising without context.** A future reader will wonder why it was done this way.
3. **The result of a real trade-off.** There were genuine alternatives and one was picked for specific reasons.

If any one is missing, skip it. An easy decision will simply be reversed, an unsurprising one needs no explanation, and a choice with no alternative records only that the obvious thing was done.

Offer first, then write it once the user agrees. Keep it short:

```
# 0007: Event-source the order write model
Status: accepted
Context and decision: one short paragraph. The forces, what was chosen, and why.
Alternatives and consequences: only where they carry information a future reader needs.
Reconsider if: the condition that would reopen this decision.
```

An accepted ADR is history. If the decision changes, write a new ADR that supersedes it and mark both; do not rewrite the old one. Link to the ADR from the spec or design note instead of copying its reasoning there.

## Writing safely

- The glossary and ADR folder are this skill's output, so write them as terms settle. Tell the user each time what you changed: "Added 'Cancellation' to GLOSSARY.md."
- Do not change or delete a definition the user or team has already settled without agreement on that specific change.
- Do not edit an accepted ADR.
- If the user only asked what a term means here, or whether it is used consistently, answer the question and do not create files.
- If the project keeps its docs somewhere unusual and you cannot tell where, ask. Do not invent a new layout.

## Not every change belongs here

Use this skill when the work introduces, renames, splits or disputes a domain term, or records a decision that meets the ADR bar. Ordinary code complexity, a new module that reuses existing vocabulary, and read-only use of an established glossary do not need it. If the work is deciding which entities exist, what they own, and which states are forbidden, that is structural modeling: use domain-model-design.

## Done when

- Every term resolved in the session is in the glossary with a definition and an Avoid list.
- Every ambiguity found is either resolved or listed under Open questions.
- Every decision that met the ADR bar was offered as one.
- The user has been told which files changed.

## Mistakes to avoid

| Mistake | Instead |
|---|---|
| Accepting a vague word because the meaning is "obvious" | Ask for the edge case and see whether the user and the code agree |
| Putting plans, field lists or how-it-works notes in the glossary | Keep it to what each term means; put the rest in specs or code comments |
| Writing an ADR for every choice | Apply the three tests; most choices fail one |
| Trusting the code over the user, or the user over the code | Surface the conflict and ask which is intended |
| Saving updates for the end | Write each term as it settles |
| Rewriting an old definition quietly | Propose the change and get agreement first |

The second audit

What we found in the sources

It keeps the shape of the version the other glossary-and-ADR skills copy (mattpocock/skills): challenge terms against the glossary, sharpen fuzzy words, stress-test with scenarios, check the code, write each term down as it settles, and offer an ADR only when three tests all pass. It adds an Avoid list per term, a place to park unresolved ambiguities, and a rule about what may be written without asking. The other two same-named skills in the bundle are a different job (structure of a data model) and are in domain-model-design. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• mattpocock/skills ↗ · Primary basis · MIT

  The split between actively changing the model and merely reading a glossary; lazy file creation; single-context versus multi-context layout with a map file; the four in-session behaviours (challenge a term against the glossary, sharpen fuzzy language, stress-test with concrete scenarios, cross-reference the code); update the glossary inline instead of batching; keep the glossary free of implementation detail; and the three-part test for offering an ADR (hard to reverse, surprising without context, a real trade-off).

• helderberto/agent-skills ↗ · Added ideas · MIT

  An Avoid list of rejected synonyms for every term, splitting a word that means two things into two named terms and retiring the overloaded one, and the completion condition that every flagged ambiguity is resolved or explicitly parked.

• dougborg/harness-kit ↗ · Added ideas · Apache-2.0

  Follow the repository's existing convention for glossary and ADR locations before using defaults; the GLOSSARY.md and GLOSSARY-MAP.md names; the framing as one precise word per concept used the same way in conversation, docs and code; and a closing 'done when' check. Its description, which lists the situations that should trigger the skill, informed the new description.

• CapitalCantrip/quality-gates ↗ · Added ideas · MIT

  The GLOSSARY.md / GLOSSARY-MAP.md file names as the default (its text is otherwise the mattpocock text with CONTEXT renamed and dashes replaced).

• mascah/skills ↗ · Added ideas · MIT

  Do not silently treat current code as the intended design (ask when a stated definition conflicts with what the code does); the fields of a useful ADR (context, decision, alternatives, rationale, consequences, a condition for reconsidering); link to an ADR from the spec instead of copying its reasoning; routine reversible choices need no ADR.

• xu91102/claude-everything-Workflow ↗ · Added ideas · MIT

  The idea that the skill should fire only when terms, entities, invariants, lifecycle or context boundaries actually change, not for ordinary code complexity; the default of not modifying tracked docs merely because the skill triggered (turned into: answer a question about terms without creating files); a glossary entry as one or two sentences with a canonical term and an Avoid list; an ADR that leads with one short paragraph and adds other sections only when they carry information.

• marinvch/Cortex ↗ · Added ideas · MIT

  'an empty glossary is worse than none: it looks maintained' as the reason for lazy creation; the rule that only terms specific to this domain belong in the glossary, however heavily the project uses general programming concepts; infer which context a topic belongs to in a multi-context repository and ask if unclear; the explanation of why each of the three ADR tests matters.

What changed

• The description now names what the skill does and lists the phrases a person would type ("what should we call this", two words that mean the same thing, one word that means two things, a glossary or ADR to write). The pinned upstream description is "Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model". The new one drops the clause about other skills and adds a not-for clause.
• The upstream links to CONTEXT-FORMAT.md and ADR-FORMAT.md are replaced by a short glossary entry shape and a short ADR shape written fresh. Those two companion files were not in the downloaded bundle and were not read.
• The default glossary name is GLOSSARY.md, with an existing convention such as CONTEXT.md winning if the repository has one. The upstream repository itself later changed its convention from CONTEXT.md to GLOSSARY.md (seen in its commit history by title; the title gives no reason). Naming it GLOSSARY.md also avoids confusion with agent-instruction files that mention context.
• Added a 'Writing safely' section: say what was written, do not change a settled definition or an accepted ADR without agreement, supersede an ADR instead of rewriting it, and do not create files when the user only asked a question. The supersede rule and the ask-first-for-changed-definitions rule are additions by the rewrite; none of the sources read states them as written here (xu91102's persistence gate is the nearest).
• Added an Open questions list for ambiguities that cannot yet be resolved (from helderberto's 'explicitly parked'), and an ADR rule to offer first and write only after the user agrees.
• Added a worked glossary entry (Order, Cancellation, an open question). The 'cancellation' and 'account' prompts follow the examples in the mattpocock text; the Order entry and the partial-return scenario are new.
• Replaced the two file-tree diagrams with prose; replaced 'the user' wording consistently; no references to other skills except one pointer to domain-model-design.

Problems found in the sources

• !mattpocock/skills: Appears to be the origin of this family. GitHub's history for skills/engineering/domain-modeling/SKILL.md lists its first commit on 2026-05-31, and later commits that change the description (2026-08-13), rename the CONTEXT.md convention to GLOSSARY.md (2026-08-15) and strip em dashes (2026-08-19). Marinvch/Cortex states 'Adapted from mattpocock/skills'. For repositories that state nothing, origin was judged from byte-identical or near-identical text only. The pinned file links to CONTEXT-FORMAT.md and ADR-FORMAT.md, neither of which is in the bundle. It does not say what to do when an inline update would change a definition the user already settled, or an accepted ADR (unclear whether that is deliberate). Its description ends with 'or when another skill needs to maintain the domain model', which presumes other skills.
• !helderberto/agent-skills: Condensed rewrite. Its frontmatter has an effort field, which is specific to one host. The not-for clause and the body route decisions to /create-adr and explaining code to /explain-code, neither of which is in the bundle, and it does not carry the three-part test for when an ADR is worth writing. Good additions: an Avoid list for each term and an explicit completion condition.
• !dougborg/harness-kit: Self-contained except that it links to GLOSSARY-FORMAT.md and ADR-FORMAT.md, which are not in the bundle. Its description lists the situations that should trigger it. It ends with a 'done when' check.
• !CapitalCantrip/quality-gates: Same text as Bossmann007/cursor-kit with CONTEXT.md renamed to GLOSSARY.md throughout (verified by diff). Links to GLOSSARY-FORMAT.md, not in the bundle.
• !mascah/skills: Very short. Points to references/discipline.md for how to write, which is not in the bundle. Its description is one 'Use when' sentence that names the job but not the phrases a person would type. It is the only source that warns against treating current code as the intended design.
• !xu91102/claude-everything-Workflow: Rewritten for its own workflow. Depends on docs/agent-workflow/project-context.md, a router and 'Spec Gate', and a grilling handoff, none of which are in the bundle. Its description is a single short sentence. Its default of not modifying tracked docs merely because the skill triggered is the most conservative treatment of file writes among the sources.
• !marinvch/Cortex: Expanded rewrite tied to its own project: it refers to a vault's context folder and decisions/log.md, /install-project, a [[codebase-design]] wiki link, and CONTEXT-FORMAT.md and ADR-FORMAT.md (which it says are vendored in its own repository but are not in the bundle). The description says it 'runs inside a target repo, not the vault'. Frontmatter includes a capability field.

What was dropped

• The two directory-tree diagrams (replaced by prose).
• From marinvch/Cortex: the vault firewall rules, the table separating the vault's context folder from a repository's CONTEXT.md, /install-project, the [[codebase-design]] wiki link and the capability frontmatter, all of which belong to that project.
• From xu91102/claude-everything-Workflow: its router, Spec Gate and grilling-handoff plumbing, the docs/agent-workflow/project-context.md dependency, and the 'do not interview or choose for the user' routing rule.
• From helderberto/agent-skills: the /create-adr and /explain-code routing and the effort frontmatter field. Its omission of the three-part ADR test was not followed; the mattpocock test is kept.
• From mascah/skills: the references/discipline.md pointer and wording tied to its spec and workflow documents.
• The description clause 'or when another skill needs to maintain the domain model'.

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/domain-modeling ~/.claude/skills/

Pairs with