If .claude/skills/ubiquitous-language/SKILL.md.disabled exists, stop before reading a fallback.
Project configuration: If the current project contains .claude/skills/ubiquitous-language/SKILL.md, read and apply it instead of this bundled default. The project copy is the capability source of truth.
Repository context: Read ../setup/references/task-context.md when resolving a task, project commands, named agent roles, or legacy .claude/ resource paths. Use repository evidence and applicable project instructions; a missing local workflow copy does not require setup. Resolve bundled resources from the installed skill, never from the target cwd.
Ubiquitous Language
Upstream: Adapted from mattpocock/skills/ubiquitous-language. Concept from Eric Evans, Domain-Driven Design.
Extract and formalize domain terminology from the current conversation into a consistent glossary stored at product-docs/UBIQUITOUS_LANGUAGE.md. The same vocabulary is used by domain experts, the user, and the AI — both in planning docs (PRD, JTBD, discovery, tech-decomposition) and in code.
When called from task work, resolve the repository and task with
../setup/references/task-context.md. Context-reading calls from
/nf, /product, and /ct are load-only. Write the glossary only for an explicit update request
or an authorized post-grill update, then link the result from the task record when relevant.
Classify the invocation before writing. A caller's context-reading request is read-only loading. An
explicit request to build/update the project glossary or define its domain terms authorizes
the glossary update; an authorized post-grill caller may do the same. An explanatory request
without that update intent returns proposed terms without writing.
When this fires
/nf Step 0: load existing glossary so discovery questions and the discovery doc use canonical terms.
/nf Step 4 → Step 5 transition: after the grill round, update glossary with new terms before writing the discovery doc.
/product Step 0 and after Step 4 grill: same pattern — load before interview, update before writing PRD/JTBD.
/ct context reading: reuse established project terms from the task's relevant inputs.
- Manual update invocation: when the user explicitly asks to harden terminology, define
domain terms in the project glossary, or build/update the glossary. If the user only asks
an explanatory terminology question, return a proposal without writing.
Process
Load-only branch (context reading)
- Read existing glossary at
product-docs/UBIQUITOUS_LANGUAGE.md (if it exists) and
report its current canonical terms. Stop here. Do not scan, merge, rewrite, or update the
example dialogue for a load-only call.
Build/update branch (explicit request or authorized post-grill call)
- Read existing glossary at
product-docs/UBIQUITOUS_LANGUAGE.md (if it exists). Hold
its content in memory — do NOT use Edit/section-patching. The file is small; the safe path
is read → merge in memory → overwrite.
- Scan the relevant scope for domain-relevant nouns, verbs, and concepts:
- Current conversation
- The active task's PRD / JTBD / discovery doc
- Source code only when terms are ambiguous and the code resolves them
- Identify problems:
- Same word used for different concepts (ambiguity)
- Different words used for the same concept (synonyms)
- Vague or overloaded terms
- Merge in memory: combine existing entries with new findings. Preserve every existing term unless evidence shows it's wrong; revise definitions that have sharpened. Add newly discovered terms. Update "Flagged ambiguities" with anything resolved.
- When the update branch is authorized, ensure the parent directory exists:
mkdir -p product-docs/ (the directory is repo-level, alongside .claude/, and may not
exist on a fresh repo).
- When the update branch is authorized, write the full merged glossary to
product-docs/UBIQUITOUS_LANGUAGE.md, fully overwriting the prior file.
- Output a summary inline so the caller (
/nf, /product, /ct) can paste it into its doc.
Output format
product-docs/UBIQUITOUS_LANGUAGE.md:
# Ubiquitous Language
> Domain terms used across PRDs, JTBDs, discovery docs, technical plans, and code. Read during relevant context gathering; update via `/ubiquitous-language` when authorized.
## [Subdomain or lifecycle name]
| Term | Definition | Aliases to avoid |
| ----------- | ------------------------------------------------------- | --------------------- |
| **Order** | A customer's request to purchase one or more items | Purchase, transaction |
| **Invoice** | A request for payment sent after delivery | Bill, payment request |
## People
| Term | Definition | Aliases to avoid |
| ------------ | ------------------------------------------- | ---------------------- |
| **Customer** | A person or organization that places orders | Client, buyer, account |
| **User** | An authentication identity in the system | Login, account |
## Relationships
- An **Invoice** belongs to exactly one **Customer**
- An **Order** produces one or more **Invoices**
## Example dialogue
> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
## Flagged ambiguities
- "account" was used to mean both **Customer** and **User** — these are distinct: a **Customer** places orders, while a **User** is an authentication identity.
Rules
- Be opinionated. When multiple words exist for the same concept, pick one and list the others as aliases to avoid.
- Flag conflicts explicitly. If a term is used ambiguously, call it out in "Flagged ambiguities" with a recommendation.
- Only domain terms. Skip generic programming concepts (array, function, endpoint) and skip the names of modules or classes unless they have meaning in the domain language.
- Tight definitions. One sentence max. Define what it IS, not what it does.
- Show relationships. Use bold term names; express cardinality where obvious.
- Group into multiple tables when natural clusters emerge (subdomain, lifecycle, actor). One table is fine if the domain is cohesive.
- Write an example dialogue. A short conversation (3-5 exchanges) between a dev and a domain expert that uses the terms precisely. The dialogue clarifies boundaries between related concepts.
- No file paths or code snippets. This is a domain document, not an implementation reference.
Re-running
When invoked again in the same conversation, follow the invocation branch:
- Step 0 load: reread and report the existing
UBIQUITOUS_LANGUAGE.md; do not rewrite it.
- Explicit build/update or authorized post-grill update: read the existing file,
incorporate new terms, update definitions and ambiguities, and rewrite the example dialogue
before the authorized full-file write.
Return to caller
After writing/updating the file, return a compact summary so /nf, /product, or /ct can reference it without re-reading the file:
- Terms added: [list]
- Terms revised: [list]
- Ambiguities flagged: [list]
- Suggested canonical phrasing for the upcoming doc: [1-3 examples]
1---2name: ubiquitous-language-43description: Build or update a DDD-style ubiquitous language glossary when the user explicitly asks to define domain terms,4 build/update the project glossary, or harden terminology. For /nf, /product, or /ct context-reading calls, load and report5 the glossary; for authorized post-grill updates, merge and write it. Do not write for a load-only or explanatory request.6 NOT for architectural vocabulary (use /architecture-language).7compatibility: Portable clients may not enforce Claude Code invocation guards or project setup behavior.8metadata:9 source: https://skillmd.com/skills/alexandrbasis/ubiquitous-language-410---1112<!-- claudops-build: project-config-pointer -->13> If `.claude/skills/ubiquitous-language/SKILL.md.disabled` exists, stop before reading a fallback.14> **Project configuration:** If the current project contains `.claude/skills/ubiquitous-language/SKILL.md`, read and apply it instead of this bundled default. The project copy is the capability source of truth.15> **Repository context:** Read `../setup/references/task-context.md` when resolving a task, project commands, named agent roles, or legacy `.claude/` resource paths. Use repository evidence and applicable project instructions; a missing local workflow copy does not require setup. Resolve bundled resources from the installed skill, never from the target cwd.1617# Ubiquitous Language1819> **Upstream**: Adapted from [mattpocock/skills/ubiquitous-language](https://github.com/mattpocock/skills/blob/main/ubiquitous-language/SKILL.md). Concept from Eric Evans, *Domain-Driven Design*.2021Extract and formalize domain terminology from the current conversation into a consistent glossary stored at `product-docs/UBIQUITOUS_LANGUAGE.md`. The same vocabulary is used by domain experts, the user, and the AI — both in planning docs (PRD, JTBD, discovery, tech-decomposition) and in code.2223When called from task work, resolve the repository and task with24[`../setup/references/task-context.md`](../setup/references/task-context.md). Context-reading calls from25`/nf`, `/product`, and `/ct` are load-only. Write the glossary only for an explicit update request26or an authorized post-grill update, then link the result from the task record when relevant.2728Classify the invocation before writing. A caller's context-reading request is read-only loading. An29explicit request to build/update the project glossary or define its domain terms authorizes30the glossary update; an authorized post-grill caller may do the same. An explanatory request31without that update intent returns proposed terms without writing.3233## When this fires3435- **`/nf` Step 0**: load existing glossary so discovery questions and the discovery doc use canonical terms.36- **`/nf` Step 4 → Step 5 transition**: after the grill round, update glossary with new terms before writing the discovery doc.37- **`/product` Step 0** and **after Step 4 grill**: same pattern — load before interview, update before writing PRD/JTBD.38- **`/ct` context reading**: reuse established project terms from the task's relevant inputs.39- **Manual update invocation**: when the user explicitly asks to harden terminology, define40 domain terms in the project glossary, or build/update the glossary. If the user only asks41 an explanatory terminology question, return a proposal without writing.4243## Process4445### Load-only branch (context reading)46471. **Read existing glossary** at `product-docs/UBIQUITOUS_LANGUAGE.md` (if it exists) and48 report its current canonical terms. Stop here. Do not scan, merge, rewrite, or update the49 example dialogue for a load-only call.5051### Build/update branch (explicit request or authorized post-grill call)52531. **Read existing glossary** at `product-docs/UBIQUITOUS_LANGUAGE.md` (if it exists). Hold54 its content in memory — do NOT use Edit/section-patching. The file is small; the safe path55 is read → merge in memory → overwrite.562. **Scan the relevant scope** for domain-relevant nouns, verbs, and concepts:57 - Current conversation58 - The active task's PRD / JTBD / discovery doc59 - Source code only when terms are ambiguous and the code resolves them603. **Identify problems**:61 - Same word used for different concepts (ambiguity)62 - Different words used for the same concept (synonyms)63 - Vague or overloaded terms644. **Merge in memory**: combine existing entries with new findings. Preserve every existing term unless evidence shows it's wrong; revise definitions that have sharpened. Add newly discovered terms. Update "Flagged ambiguities" with anything resolved.655. **When the update branch is authorized**, ensure the parent directory exists:66 `mkdir -p product-docs/` (the directory is repo-level, alongside `.claude/`, and may not67 exist on a fresh repo).686. **When the update branch is authorized**, write the full merged glossary to69 `product-docs/UBIQUITOUS_LANGUAGE.md`, fully overwriting the prior file.707. **Output a summary** inline so the caller (`/nf`, `/product`, `/ct`) can paste it into its doc.7172## Output format7374`product-docs/UBIQUITOUS_LANGUAGE.md`:7576```md77# Ubiquitous Language7879> Domain terms used across PRDs, JTBDs, discovery docs, technical plans, and code. Read during relevant context gathering; update via `/ubiquitous-language` when authorized.8081## [Subdomain or lifecycle name]8283| Term | Definition | Aliases to avoid |84| ----------- | ------------------------------------------------------- | --------------------- |85| **Order** | A customer's request to purchase one or more items | Purchase, transaction |86| **Invoice** | A request for payment sent after delivery | Bill, payment request |8788## People8990| Term | Definition | Aliases to avoid |91| ------------ | ------------------------------------------- | ---------------------- |92| **Customer** | A person or organization that places orders | Client, buyer, account |93| **User** | An authentication identity in the system | Login, account |9495## Relationships9697- An **Invoice** belongs to exactly one **Customer**98- An **Order** produces one or more **Invoices**99100## Example dialogue101102> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"103> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."104105## Flagged ambiguities106107- "account" was used to mean both **Customer** and **User** — these are distinct: a **Customer** places orders, while a **User** is an authentication identity.108```109110## Rules111112- **Be opinionated.** When multiple words exist for the same concept, pick one and list the others as aliases to avoid.113- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a recommendation.114- **Only domain terms.** Skip generic programming concepts (array, function, endpoint) and skip the names of modules or classes unless they have meaning in the domain language.115- **Tight definitions.** One sentence max. Define what it IS, not what it does.116- **Show relationships.** Use bold term names; express cardinality where obvious.117- **Group into multiple tables** when natural clusters emerge (subdomain, lifecycle, actor). One table is fine if the domain is cohesive.118- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that uses the terms precisely. The dialogue clarifies boundaries between related concepts.119- **No file paths or code snippets.** This is a domain document, not an implementation reference.120121## Re-running122123When invoked again in the same conversation, follow the invocation branch:124125- **Step 0 load:** reread and report the existing `UBIQUITOUS_LANGUAGE.md`; do not rewrite it.126- **Explicit build/update or authorized post-grill update:** read the existing file,127 incorporate new terms, update definitions and ambiguities, and rewrite the example dialogue128 before the authorized full-file write.129130## Return to caller131132After writing/updating the file, return a compact summary so `/nf`, `/product`, or `/ct` can reference it without re-reading the file:133134- Terms added: [list]135- Terms revised: [list]136- Ambiguities flagged: [list]137- Suggested canonical phrasing for the upcoming doc: [1-3 examples]