You and your agents use the same words for the same things. Each word has one meaning. In most repos it's written down in one place: the glossary, a file called GLOSSARY.md at the root of the repo.
Why it matters
An agent writes a lot of words for you: Issue titles, test names, code. Say it calls something an "account" in one place and a "user" in another. Now you can't tell whether it means one thing or two. Matt's own example asks exactly that: by "account", do you mean the Customer or the User? Those are different things.
So the Skills that work on your code are all told the same thing. When an agent names a concept, it uses the glossary's term. It doesn't drift to a synonym the glossary says to avoid.
A missing word is a signal too. Either the agent is making up language the project doesn't use, or the glossary has a real gap that should be filled.
Where it shows up
setup-matt-pocock-skills writes the instructions that tell the other Skills to read the glossary and use its words. That's why this Principle comes first: setup runs before your first Flow.
grill-with-docs builds the glossary while it interviews you. When you use a word that clashes with the glossary, it calls it out at once.
wait-what re-explains a message that didn't land, using the glossary's words. Matt says grilling with docs is the upfront cure: a shared language agreed early is what stops the jargon arriving at all.
What the glossary is not
The glossary holds words and what they mean, and nothing else. It isn't a Spec, a scratch pad, or a place to record how the code is built.
In this project
This site's own GLOSSARY.md is the reason the Course says Ticket and never "task", and Spec and never "PRD". Each entry gives the word, what it means, and the words to avoid.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt files this problem under "The Agent Is Way Too Verbose" in his repo's README (at the pin commit, 2026-10-29). In his words: "Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do."
He starts from a gap between people: developers and the people they build for "are usually speaking different languages". He "felt the same tension" with his agents. His fix is "a shared language", a document "that helps agents decode the jargon used in the project". He calls it possibly "the single coolest technique in this repo".
He claims three gains beyond fewer words:
variables, functions and files get named the same way;
the codebase is easier for the agent to find its way around;
the agent spends fewer tokens on thinking.
He gives no numbers for any of them. His advice is "Try it, and see."
The idea started as its own Skill, /ubiquitous-language, and it went away in two steps. First, on 2026-04-28, Matt moved it into a deprecated folder of "Skills I no longer use". An undated changelog page, written when grill-with-docs was "a powerful new skill" (that name first appeared on 2026-04-28), says it "has been deprecated and merged" into grill-with-docs, which wrote a context.md file instead. Then, on 2026-08-05, he deleted it. His changelog lists it under version 1.2.0 as one of "Four retired skills", with its job moving to domain-modeling. His newer domain-modeling page (2026-08-24) puts it differently: it "was removed, and it was not deprecated". The repo's own commits show both steps. The file was called until version 1.3.0. Now it's , because "The file is a glossary and nothing else".
Citations (70)
From snapshot/skills/setup-matt-pocock-skills/domain.md, line 43: “When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in GLOSSARY.md. Don't drift to synonyms the glossary explicitly avoids.”
The idea comes from Eric Evans's book Domain-Driven Design. He called it the ubiquitous language. Martin Fowler summed it up in 2006 as "the practice of building up a common, rigorous language between developers and users". It must be rigorous because it's based on the model the software uses, and "software doesn't cope well with ambiguity".
Two more of Evans's points matter here. First, you test the language by using it when you talk with the people who know the business. Second, it should evolve as the team learns more. Evans splits the work between two sides. Domain experts "should object to terms or structures that are awkward or inadequate". Developers "should watch for ambiguity or inconsistency that will trip up design".
One language doesn't have to cover the whole system. Matt's changelog page lists "Different contexts for different parts of your system (e.g., ordering vs. billing)", each with its own shared language. Today's glossary format handles this with a GLOSSARY-MAP.md at the repo root that "lists the contexts, where they live, and how they relate to each other". Most repos need just one GLOSSARY.md.
The same format makes each entry take a side: "When multiple words exist for the same concept, pick the best one and list the others under _Avoid_."
A Python book shows the same habit. In Architecture Patterns with Python, Harry Percival and Bob Gregory write: "We make sure to express those rules in the business jargon". In their tests, "the names of the classes and variables that we use are taken from the business jargon". Even their exceptions are named "in the ubiquitous language", such as OutOfStock.
A real example
Matt's README points at a real glossary from his course-video-manager repo, at a commit from 2026-04-27. It asks which of two sentences is easier to read:
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"
The glossary defines the term in one line. A Materialization Cascade is "The chain reaction when materializing a lesson inside a ghost course: assigns file path to course, materializes section, then materializes lesson — all in one flow." Other entries list the words to avoid. Section, for example, avoids "Module, Chapter, Unit".
Where it goes wrong
The glossary turns into a plan. Issue #130 was opened on 2026-05-04. Its author saw GPT 5.5 in Codex "misuse the Context.md file as plan document", writing every answer into it. On 2026-05-06 another user wrote that their file was "already going over 500 lines". On 2026-05-12 Matt gave a fix: "/grill-with-docs make my CONTEXT.md more concise and remove any implementation details from it". He left the issue open to make the Skill's own rules firmer. His domain-modeling page now calls this "the most-reported problem with the skill, across several models".
The words can outrun the thinking. Matt warns that "The right nouns on top of the wrong concepts produce output that reads as correct and is not." A glossary the agent wrote and nobody reviewed is "worse than none": it "fills with confident claims that later sessions treat as true".
It isn't always worth it. The same page reports an objection: an agent may answer a plain-English description just as well as a domain term. Then the glossary's value is "keeping you and your reviewers aligned with what the agent is doing, not making the agent better". The page ends that answer with: "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), write a GLOSSARY.md at the root by hand. Give it three words the yoga studio uses, such as the thing a student books and the person who teaches it. Follow the glossary format: one or two sentences each, saying what the thing is, and an _Avoid_ line for the other words you might use. Then search api/ and web/ for those other words. Each hit is a place where the code and the glossary disagree. Keep the file to words only, with no plans or code details in it.
From snapshot/skills/ask-matt/SKILL.md, line 91: “the agent re-pitches what it just said with the context you were missing, in plain English, using the GLOSSARY.md vocabulary. It works after the fact; /grill-with-docs is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.”
From snapshot/web/martinfowler.com/bliki-ubiquitouslanguage-html.md, lines 25–28: “Evans makes clear that using the ubiquitous language in conversations with domain experts is an important part of testing it, and hence the domain model. He also stresses that the language (and model) should evolve as the team's understanding of the domain grows.”
From snapshot/web/github.com/mattpocock-skills-issues-130.md, line 47: “I had Codex with GPT 5.5 misuse the Context.md file as plan document. After each question it updated the CONTEXT.md file and used the format of term definitions to describe the decisions and answers that I provided.”
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, across several models.”
From snapshot/web/aihero.dev/skills-domain-modeling.md, line 159: “There is also an objection that domain terms compress communication between humans who already share them, and that an agent responds the same way to the plain-English description. On that reading, the glossary's value is keeping you and your reviewers aligned with what the agent is doing, not making the agent better. On a one-day build, skip it.”