domain-modeling
Keep a project glossary of domain terms and lightweight decision records, and catch banned synonyms in docs and code
Install / Use
npx skills add borghei/Claude-Skills --skill domain-modelingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of domain-modeling
domain-modeling scores 86/100 on our quality scale, 743rd of 1,155 Content & Media skills we index.
Its SKILL.md is 14 KB long, well organised into 27 sections with 1 code example: a thorough specification that gives an agent plenty to work with.
It has 817 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so domain-modeling is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit โ read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk โ read a skill before letting an agent act on it.
domain-modeling compared with similar skills
All 4 of these similar skills score higher than domain-modeling; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| domain-modeling (this skill)by borghei | 86 | 817 | 56d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
Frequently asked questions
- How do I install domain-modeling?
- Run
npx skills add borghei/Claude-Skills --skill domain-modeling. The install tabs above show the steps for each supported agent. - Which AI agents does domain-modeling work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is domain-modeling safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is domain-modeling still maintained?
- The repository was last updated about 2 months ago, so domain-modeling is actively maintained.
Skill content
View source on GitHubname: domain-modeling description: > Keep a project glossary of domain terms and lightweight decision records, and catch banned synonyms in docs and code. Use when terms are used inconsistently, writing a GLOSSARY.md, or recording a design decision. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: engineering domain: domain-design updated: 2026-11-08 tags: [domain-modeling, glossary, ubiquitous-language, adr, decision-records, naming]
Domain Modeling
Shared language is the cheapest defect prevention there is. This skill keeps two
small artefacts: a GLOSSARY.md where every domain term has one name, one
definition in business language, the synonyms to avoid and an owner who settles
disputes; and a folder of short decision records for choices that are costly to
reverse, surprising later and the result of a real trade-off. Its tools pull
candidate terms out of conversations and code, lint the glossary, find banned
synonyms in docs and identifiers, and keep decision records numbered and linked.
When to use this skill
- The same thing has three names across code, docs, tickets and support macros
- A design conversation keeps stalling on what a word means ("account" โ the payer or the login?)
- Starting a GLOSSARY.md for a project or a bounded part of a system
- A decision was just made that a newcomer would otherwise undo
- Onboarding โ new people need the vocabulary before the code makes sense
- Before naming a new module, table or API resource, to use the agreed term
Inputs the skill expects
- Material that carries the language: meeting transcripts, design notes, tickets, code paths
- The existing
GLOSSARY.mdanddocs/adr/if present - Who owns which terms (roles that can settle a meaning)
- Whether the system has one context or several where the same word means different things
Clarify First
What most shapes the output is whether the language is being created, repaired or checked, and who has authority over it. Settle the inputs below before producing anything. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.
- One context or several: if a word legitimately means two things in two parts of the system, forcing one definition causes the bugs this skill exists to prevent.
- Term owners: a proposed term without an owner stays proposed forever; the owner decides synonym fights.
- Source material: transcripts and support tickets surface customer language and aliases; code surfaces engineering names โ the extraction differs.
- Decision threshold: which choices the team wants recorded; default is the three-part test (costly to reverse, surprising, real trade-off).
Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.
Quick Start
# Lint the sample glossary and find banned aliases in a feature note
python3 engineering/domain-modeling/scripts/glossary_lint.py \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md \
--scan engineering/domain-modeling/assets/sample_feature_notes.md
# Lint the sample decision records and get the next file name
python3 engineering/domain-modeling/scripts/adr_lint.py \
--input engineering/domain-modeling/assets/sample_adr_set.json \
--next-title "Publish events for billing"
Workflows
Workflow 1 โ Extract terms from conversations and code [RECOMMENDED]
-
Gather material: a design-session transcript, recent tickets, and the code paths for the area.
-
Run the extractor against the current glossary (or none, for a first pass):
python3 engineering/domain-modeling/scripts/term_extract.py \ --paths engineering/domain-modeling/assets/sample_conversation.txt \ --glossary engineering/domain-modeling/assets/sample_GLOSSARY.md --format text -
Triage each new candidate: add as a term, add as an alias of an existing term, split (one word, two concepts), or ignore. In the sample,
pauseandsuspensionare two concepts that need two entries;membershipis an alias of Subscription. -
Read the "never used" list: those terms are stale or called something else in practice.
-
Draft new entries with status
proposedand ask each owner to confirm.
Exit code 1 means new candidates exist and need a decision โ useful as a periodic review prompt, not a merge gate.
Workflow 2 โ Write and lint the glossary [PROVEN]
-
Start from
assets/GLOSSARY-template.md: one### Termblock per concept with Definition, Avoid, Owner, Related, Status. -
Definitions say what the thing is in at most two sentences. No tables, columns, classes or endpoints.
-
Each alias appears under exactly one term, and never matches another canonical term.
-
Lint it, then scan docs and code for the aliases you just banned:
python3 engineering/domain-modeling/scripts/glossary_lint.py \ --glossary engineering/domain-modeling/assets/sample_GLOSSARY.md \ --scan engineering/domain-modeling/assets/sample_feature_notes.md --format json -
The scan splits identifiers, so
clientIdandmemberships.renewcount as uses of "client" and "membership". Fix docs now; rename identifiers when the files are next touched.
Validation checkpoint: the lint reports no errors, every term has an owner, and the scan over changed docs is clean before the glossary change merges.
The sample glossary is deliberately flawed and exits 1: a duplicate Plan, the alias Account colliding with the canonical term Account, Churn mapped to two terms, an invalid status, and an implementation-heavy definition of Charge.
Workflow 3 โ Resolve a synonym conflict [PROVEN]
- Write a one-sentence definition for each competing word.
- Invent a scenario where one applies and the other does not. If one exists, they are two concepts: create two terms.
- If it is one concept, pick the name by: external (customer, contract) usage first, least overloaded internally second, most present in code third.
- Put the losing words under Avoid, run the
--scan, and if the choice was contested, record it as a decision so it is not reopened.
Workflow 4 โ Record a decision [RECOMMENDED]
The agent offers a record only when a choice passes all three tests: costly to reverse, surprising without context, and a real trade-off.
-
Get the next file name:
adr_lint.py --dir docs/adr --next-title "<decision>". -
Fill
assets/adr-template.md: decisive title, Context with glossary terms, "We willโฆ" Decision, alternatives with reasons, consequences. -
Start as
proposed; setacceptedonce deciders agree. Never edit an accepted record's decision โ supersede it and add**Supersedes:** NNNNto the new one. -
Validate the folder before merging:
python3 engineering/domain-modeling/scripts/adr_lint.py \ --input engineering/domain-modeling/assets/sample_adr_set.json --format text
The sample set exits 1: number 0004 is used twice, 0002 points at a missing replacement, 0005 claims to supersede 0002 while 0002 names another record, and one record has no Decision section.
Workflow 5 โ Keep the model honest during design work [RECOMMENDED]
- When someone uses a term against its glossary meaning, the agent points it out at once and asks which meaning they intend.
- When code contradicts a stated rule ("partial cancellation is possible" but the code cancels whole Subscriptions), the agent surfaces the contradiction instead of picking a side.
- Update the glossary in the same change that introduces or renames a concept.
- Validate that every new identifier in the change uses the canonical term (
--scanon the changed paths).
Decision frameworks
Does this word belong in the glossary?
| Question | Yes โ | No โ | |----------|-------|------| | Would two people here plausibly mean different things by it? | Add it | Next question | | Does a new hire need it explained to read tickets or code? | Add it | Next question | | Is it generic engineering vocabulary (cache, retry, queue)? | Leave it out | โ |
One context or two? [RECOMMENDED]
Split into per-context glossaries when a term keeps two definitions that both survive the scenario test, or when two teams keep correcting each other's usage. Keep a root GLOSSARY.md that lists contexts and translations, and translate explicitly at the code seam between them.
Record it or not? [PROVEN]
| Costly to reverse | Surprising later | Real alternative | Record? | |-------------------|------------------|------------------|---------| | Yes | Yes | Yes | Yes | | Yes | No | Yes | No โ the code explains it | | No | Any | Any | No โ just change it later | | Yes | Yes | No | Usually no; a code comment suffices |
Anti-Patterns
The Glossary as a Spec
Mistake: Definitions that describe tables, flags, endpoints and retry counts ("a row in the charges table with a captured boolean").
Why it happens: Engineers write the glossary and describe what they know best โ storage.
Instead: Define what the thing is in business language. Storage changes every quarter; the concept does not. glossary_lint.py warns on implementation words.
Every Synonym Is Fine
Mistake: Listing synonyms as "also known as" and accepting all of them. Why it happens: Picking one word feels like overruling colleagues. Instead: Choose one canonical term and list the rest under Avoid. A glossary that blesses three names has not removed any ambiguity. Let the term's owner make the call.
The One Alias, Two Meanings
Mistake: Banning "churn" under both Cancellation and Downgrade, or banning a word that is itself a canonical term elsewhere. Why it happens: Terms are added one at a time without checking the rest of the file. Instead: Each alias maps to exactly one term. If a word genuinely covers two concepts, it is a split, not an alias โ say so in both definitions. The linter rejects both collisions.
Recording Everything
Mistake: A decision record for every library choice and folder rename, until nobody reads the folder. Why it happens: Records feel like diligence, and writing one is easy. Instead: Apply the three-part test. A record that fails it is noise that hides the records that matter.
Editing History
Mistake: Rewriting an accepted record when the decision changes, or deleting a record that turned out wrong.
Why it happens: It keeps the folder tidy.
Instead: Supersede: write a new record, mark the old one superseded by NNNN, and add **Supersedes:** to the new one. The reasoning that was overturned is exactly what the next person needs to see.
Files
Tools Overview
| Script | Purpose | Exit codes |
|--------|---------|------------|
| scripts/glossary_lint.py | Lint ### Term entries (missing definition/owner, duplicates, alias collisions, circular, overlong or implementation-heavy definitions, invalid status, dangling Related); --scan finds avoided aliases in docs and code with identifier splitting | 0 clean, 1 errors or alias usages, 2 input error |
| scripts/term_extract.py | Count content words and two-word phrases in transcripts, docs and code; classify as defined, avoided alias or new; list glossary terms never used | 0 no new candidates, 1 candidates need a decision, 2 input error |
| scripts/adr_lint.py | Check numbering, title/file match, status values, two-way supersession links, required sections, decisive wording, recorded alternatives; --next-title prints the next file name | 0 clean, 1 errors, 2 input error |
All take --format text|json. adr_lint.py reads --dir docs/adr or a JSON bundle via --input.
Reference Documentation
| File | Purpose |
|------|---------|
| references/glossary-practice.md | What belongs,
Truncated for display โ read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio โ 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together ๅผๆบใ้็งไผๅ ใ่ชๆ็ฎก็็ฅ่ฏๅทฅไฝ็ฉบ้ด๏ผ่ฎฉไบบไธๆบ่ฝไฝๅจๆญคๅไฝ
x402
121.0kSet up Browser Use Cloud payments with x402 โ pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit โ see the Safety scan above for what the skill file itself contains.
