Guide · Agent skill
How to use the Domain Modeling agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Domain Modeling skill is an agent skill that helps an AI coding agent define and sharpen the core terms of your software project while you design. It is for developers and teams whose codebase vocabulary has drifted, and who want the agent to keep a GLOSSARY.md and a small set of Architecture Decision Records (ADRs) up to date as decisions are made. After this guide you will know what the skill changes about the agent's behaviour, how to install it, how to trigger it, and where its limits are.
Domain Modelingmattpocock/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the domain-modeling skill as a ZIP from this page.
- 2Unzip into a skills folder. Place the domain-modeling folder in ~/.claude/skills/ for personal use, or in your project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- 4Start a design discussion. Describe a terminology or design question in plain language, such as which term a concept should use.
- 5Let the agent challenge terms. Answer its questions about what you mean. It will flag conflicts and propose precise terms.
- 6Review GLOSSARY.md. Check the glossary entries the agent writes inline and correct any you disagree with.
- 7Decide on ADRs. When the agent offers an ADR, accept it only if the decision is hard to reverse and involved a real trade-off.
What is an agent skill, and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md file and any supporting files that an AI agent can load when a task matches the skill's description. This one is called domain-modeling and is described as building and sharpening a project's domain model, for use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
The skill's own wording distinguishes active modeling from passive reading. Simply reading GLOSSARY.md for vocabulary is described as a one-line habit that any skill can do. This skill is meant for when you are changing the model.
- Challenges terms that conflict with the existing language in GLOSSARY.md and asks which meaning you intend.
- Proposes a precise canonical term when you use a vague or overloaded word such as 'account'.
- Stress-tests relationships with invented edge-case scenarios.
- Cross-references what you say about the system with the code, and flags contradictions.
- Writes resolved terms into GLOSSARY.md inline, as they come up rather than in a batch.
- Offers an ADR only when a decision is hard to reverse, surprising without context, and the result of a real trade-off.
Install the Domain Modeling skill
Download the skill as a ZIP from this page and unzip it. You can install it for yourself across projects in ~/.claude/skills/, or for a single project in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: place the unzipped domain-modeling folder inside ~/.claude/skills/.
- Project install: place it inside the project's .claude/skills/ folder.
- Claude apps: Settings → Capabilities → Skills, then upload the skill.
Check what the skill includes
The skill folder contains four files. SKILL.md holds the main instructions. GLOSSARY-FORMAT.md and ADR-FORMAT.md define how glossary entries and decision records should be written. agents/openai.yaml is also included in the package.
- SKILL.md: main instructions and trigger description
- GLOSSARY-FORMAT.md: glossary structure and rules
- ADR-FORMAT.md: ADR template, numbering and when to offer one
- agents/openai.yaml: agent configuration file included in the package
Trigger the skill with natural requests
You do not need a special command. The skill is meant to be used when your request touches on terminology, the glossary, or decision records. Describe what you are doing in plain language, and the agent can match it to the skill's description.
Requests that match the skill's stated triggers include discussing what a term means in your codebase, asking the agent to create or edit GLOSSARY.md, and asking it to record or revise an ADR.
- "We use 'account' for both customers and staff. Help me pin down which one each means."
- "Let's design how partial cancellations work. Push me with edge cases."
- "Create a GLOSSARY.md for this repo from what we've just agreed."
- "Should we record the decision to store orders in Postgres as an ADR?"
Understand the file layout it creates
For a repo with one context, the skill uses a GLOSSARY.md at the root and ADRs in docs/adr/. If a GLOSSARY-MAP.md exists at the root, the repo is treated as having multiple contexts, each with its own GLOSSARY.md and, where needed, its own docs/adr/ folder.
Files are created lazily. A GLOSSARY.md appears when the first term is resolved, and docs/adr/ appears when the first ADR is needed. ADRs are numbered sequentially, for example 0001-slug.md, by scanning for the highest existing number and adding one.
/
├── GLOSSARY.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/Know what the skill will not do
The skill sets deliberate limits. GLOSSARY.md is meant to be free of implementation details, so it is a glossary and not a spec or a place for implementation decisions. ADR offers are rare by design, so you should not expect every decision to be recorded automatically.
Its guidance for glossary terms is to include only terms specific to your project's context, not general programming concepts such as timeouts or error types.
- Expect no automatic recording of every decision; ADRs are offered only when all three criteria are met.
- Expect general programming terms to be left out of the glossary.
Safety notes: scripts and network access
According to the listing, this skill requires nothing beyond itself, does not run scripts, and does not use the network. Its instructions are about reading and writing Markdown files and comparing your statements with your code.
Because the skill writes files into your repository, review its GLOSSARY.md and ADR changes in version control as you would any other edit.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
What people use it for
- Untangling a codebase where 'customer', 'user' and 'account' are used interchangeably.
- Preparing a design session and asking the agent to push for precise language and edge cases.
- Creating a first GLOSSARY.md for a team that follows domain-driven design.
- Recording a hard-to-reverse architecture choice, such as a storage model, as a numbered ADR.
Frequently asked questions
Is the Domain Modeling skill free?
The skill is published under the MIT licence, as listed on this page. The source does not list any prices, so check the licence text in the repository for the terms.
What does the domain-modeling skill require?
The listing says it requires nothing. It does not run scripts and does not use the network, according to this page.
Where do I install an agent skill?
Unzip the skill into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Can I use this skill just to read my glossary?
You can, but the skill states that simply reading GLOSSARY.md for vocabulary is a basic habit and not its purpose, so it adds little in that case.
Why doesn't the agent write an ADR for every decision?
The skill offers ADRs sparingly. It only offers one when the decision is hard to reverse, surprising without context, and the result of a real trade-off.
Should I use this skill for a small script or prototype?
Probably not. The skill is aimed at projects where a formal glossary and decision records are worth maintaining, and it suggests they would be overhead for small throwaway scripts or prototypes.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building or untangling a codebase with inconsistent terminology, or running design sessions where you want the agent to push for precise language and keep a GLOSSARY.md current. Skip it for small throwaway scripts, prototypes, or if you only need to read an existing glossary.
Download the skill