domain-modeling builds and sharpens a project's domain model: the shared words for the things your project is about, like Booking, Customer or Invoice on a booking site, and the big decisions behind them. It's the active discipline: challenging terms, inventing edge cases, and writing the glossary and decisions down the moment they settle. Just reading the glossary for the right words is not this Skill; any Skill does that.
When to use it
When a term is fuzzy or does several jobs: does "account" mean the Customer or the User?
When you're writing or editing a GLOSSARY.md, or recording an ADR.
When the words themselves are the problem.
Mostly you won't call it yourself. grill-with-docs runs it alongside grilling, and triage, wayfinder and improve-codebase-architecture pull it in too. Agents can also load it on their own.
When not to use it
To be interviewed about a whole plan or feature, use grill-with-docs. It runs grilling and domain-modeling together, so the glossary still gets updated.
For the shape of code (modules, interfaces, seams), use codebase-design. domain-modeling is about the domain's words, not the code's structure.
What it needs to start
A conversation where terms or decisions are changing. It reads GLOSSARY.md at the repo root (or GLOSSARY-MAP.md, if the repo has several separate areas, each with its own glossary) and the ADRs in docs/adr/. If they don't exist yet, that's fine: it creates them lazily, only when there's something to write.
What it creates
GLOSSARY.md, updated the moment a term is settled, never batched up for later. Each term gets a one or two sentence definition and an Avoid line: the other words for it that you shouldn't use. It holds only terms specific to this project: no implementation details, no scratch notes, and it's never a Spec. This repo's own GLOSSARY.md is an example.
ADRs, short for architecture decision records: short notes in docs/adr/, numbered 0001, 0002 and so on, each saying what was decided and why. One paragraph is enough. It offers one only when all three hold: the decision is hard to reverse, surprising without context, and the result of a real trade-off.
GLOSSARY.md
ADRs
at the repo root
in docs/adr/
updated the moment a term is settled, never batched up for later
It offers one only when all three hold
It holds only terms specific to this project
the decision is hard to reverse, surprising without context, and the result of a real trade-off
a one or two sentence definition and an Avoid line
each saying what was decided and why. One paragraph is enough.
a project's domain model
Along the way it challenges you. If you use a term that clashes with the glossary, or describe something the code contradicts, it calls it out at once.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt's README (at the pin commit, 2026-10-29) names the problem under the heading "The Agent Is Way Too Verbose". At the start of a project, developers and domain experts "are usually speaking different languages". Agents are dropped into a project and have to work out the jargon as they go, "So they use 20 words where 1 will do." His fix is a shared language: "a document that helps agents decode the jargon used in the project."
In a video from 2026-05-14 he tells how it started. In grilling sessions he kept re-explaining the domain, so he asked "what is the thinnest layer of documentation I could use to just give the AI a bit more of a leg up". His answer was the ubiquitous language skill. He ran it alongside grill-me, then merged the two into grill-with-docs, announced in his changelog of 2026-04-30.
Today that job lives in domain-modeling: "Sharpen the words a project uses, and write them down." Matt's sources disagree on one detail. The 2026-04-30 changelog says the old skill was "deprecated and merged". His newer domain-modeling page (updated 2026-08-24) says it "was removed, and it was not deprecated". The newer page wins.
How it works underneath
The idea is Eric Evans's ubiquitous language, from his book Domain-Driven Design (DDD). Martin Fowler's 2006 summary calls it "a common, rigorous language between developers and users". It must be rigorous "since software doesn't cope well with ambiguity". You test it by using it in conversations with domain experts. Evans gives each side a job. Experts "should object to terms or structures that are awkward or inadequate", and developers "should watch for ambiguity or inconsistency that will trip up design". domain-modeling gives the agent the developer's job: "When the user uses vague or overloaded terms, propose a precise canonical term."
Citations (99)
From snapshot/skills/domain-modeling/SKILL.md, line 8: “Actively build and sharpen the project's domain model as you design. This is the active discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise.”
The same idea works in Python. In Architecture Patterns with Python, Harry Percival and Bob Gregory write their rules in the business jargon, and take the names of their classes, variables and even exceptions from it, like OutOfStock. The result: "We could show this code to our nontechnical coworkers".
Bounded context. In Matt's words, "a part of the app in which you speak a shared language". So a big repo gets a GLOSSARY-MAP.md with one glossary per context. Until 1.3 the file was named CONTEXT.md, after this idea. Matt's v1.3 changelog (updated 2026-10-05) explains the rename: CONTEXT.md "was too vague. It did not make the agent pull the file in at the right moments".
The ADR. Michael Nygard proposed it in 2011. Without a past decision's reasons, a newcomer can only "Blindly accept the decision" or "Blindly change it". Nygard's ADR has a Title, Context, Decision, Status and Consequences, and runs one or two pages long. Matt's ADR-FORMAT.md is much shorter: a title and 1-3 sentences. An ADR can be a single paragraph. Status and Consequences appear only as optional sections: "Only include these when they add genuine value. Most ADRs won't need them." Matt's reason for ADRs: they prevent "the AI from suggesting the same bad idea repeatedly".
Nygard's ADR
Matt's ADR-FORMAT.md
a Title, Context, Decision, Status and Consequences
a title and 1-3 sentences
one or two pages long
An ADR can be a single paragraph.
Status and Consequences
optional sections
Matt's ADR-FORMAT.md is much shorter
A real example
Matt's README shows the payoff with his own course-video-manager repo, as a before and after:
Before: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
After: "There's a problem with the materialization cascade"
Its glossary, still named CONTEXT.md there, defines Materialization Cascade as "The chain reaction when materializing a lesson inside a ghost course". Its neighbour Materialize gives up two words: Avoid: Create on disk, Realize. Matt's verdict: "This concision pays off session after session."
Where it goes wrong
It never loads. Agents can load it on their own: the current SKILL.md's front matter has only a name and a description. But Matt's page (updated 2026-08-24) calls automatic invocation "the weakest part of the skill". When grill-with-docs or wayfinder say to load it, models "often load grilling and skip this one". Version 1.3 (changelog updated 2026-10-05) changed how skills call each other, because "A skill that names another skill in prose does not reliably load it." Matt says "This was the cause of the most-reported problem with /grill-with-docs." grill-with-docs now says "Call the Skill tool twice". Matt's page still carries the warning, so if GLOSSARY.md is unchanged at the end, invoke it by name.
The glossary turns into a running spec. Left unchecked, models treat "write to GLOSSARY.md" as permission to save every answer, "and the file turns into a running spec". Matt calls this "the most-reported problem with the skill". Readers ask what to do when it reaches 500, 1,000, even 3,000 lines. The fix is one instruction: /grill-with-docs make my GLOSSARY.md more concise and remove any implementation details from it. Split it with a GLOSSARY-MAP.md only once it's lean: "Splitting a bloated file gives you several bloated files."
It reopens settled debates. It cross-references code, GLOSSARY.md and the ADRs, and nothing else. Issue #717 (opened 2026-08-01, still open) is a real run on a Django codebase. It found two unrelated things both called "Tool", which looked like a new clash, but a closed issue had settled it "months earlier". Matt's page and the issue give one workaround: put the instruction in your own docs/agents/domain.md.
Nobody reviews it. "an unreviewed, agent-authored glossary is worse than none: it fills with confident claims that later sessions treat as true." And on a small job: "On a one-day build, skip it."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), sharpen one overloaded word in the yoga-studio booking site: "class". Is it a kind of class, like Vinyasa, or one class on Tuesday at 6pm that people book?
In docs/agents/domain.md (setup-matt-pocock-skills created it), add the issue #717 workaround: before treating a term as unresolved, search the repo's GitHub Issues for it.
Start a session in the repo and type /domain-modeling by name. Describe how booking works in your own words, using "class" loosely.
Keep GLOSSARY.md open. It should change during the conversation, with an Avoid line for the word you gave up.
At the end, run the page's fix command: /grill-with-docs make my GLOSSARY.md more concise and remove any implementation details from it.
From snapshot/skills/ask-matt/SKILL.md, line 67: “/codebase-design is the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's shape”
From snapshot/skills/domain-modeling/SKILL.md, line 64: “GLOSSARY.md should be totally devoid of implementation details. Do not treat GLOSSARY.md as a spec, a scratch pad, or a repository for implementation decisions.”
From snapshot/skills/domain-modeling/SKILL.md, lines 68–72: “Only offer to create an ADR when all three are true: 1. Hard to reverse: the cost of changing your mind later is meaningful 2. Surprising without context: a future reader will wonder "why did they do it this way?" 3. The result of a real trade-off”
From snapshot/web/youtube.com/watch-v-6bb6exr8zd8.md, lines 69–70: “So, I had grill me and I had ubiquitous language, and I was using them both at the same time, and I realized, "Wouldn't it be great if I just combine the two into a new skill?" [04:41] And here is that new skill. It is grill with docs.”
From snapshot/web/aihero.dev/skills-domain-modeling.md, line 94: “often load grilling and skip this one. If a grilling session runs and GLOSSARY.md is unchanged at the end, that is what happened. Invoke it by name alongside the other skill.”
From snapshot/web/aihero.dev/skills-domain-modeling.md, line 133: “Left unchecked, models treat "write to GLOSSARY.md" as permission to persist every answer you give, and the file turns into a running spec. This is the most-reported problem with the skill”