ubiquitous-language

Overview of ubiquitous-language skill

The ubiquitous-language skill turns a messy discussion about a domain into a structured, DDD-style glossary with canonical terms, definitions, and aliases to avoid. Its core job is not “write a glossary” in the generic sense. It helps teams standardize language when product, engineering, and technical writing are using overlapping or inconsistent terms for the same concepts.

What ubiquitous-language is best for

Use the ubiquitous-language skill when you already have domain talk in the conversation and need to formalize it into something reusable. It is a strong fit for:

• domain-driven design work
• API and product terminology cleanup
• internal platform naming alignment
• onboarding docs
• content modeling
• ubiquitous-language for Technical Writing where documentation must use one canonical term consistently

The real job-to-be-done

Most users are trying to solve one of these problems:

• “We keep using multiple names for the same thing.”
• “One term means different things in different contexts.”
• “Our docs, product UI, and engineering discussions are drifting apart.”
• “We need a first-pass domain glossary from existing discussion, not a blank-page exercise.”

This skill scans the current conversation, identifies ambiguous or duplicated terminology, proposes opinionated canonical terms, and writes the result to UBIQUITOUS_LANGUAGE.md.

What makes this different from a normal prompt

A normal prompt can ask for a glossary. The ubiquitous-language workflow is more specific and therefore more useful for adoption decisions:

• it looks for ambiguity, synonyms, and overloaded terms
• it pushes toward canonical naming, not just extraction
• it outputs a reusable markdown artifact
• it follows a predictable table-based structure that is easy to review and edit

That makes it better for terminology hardening than a generic “summarize our domain terms” request.

What the output looks like

The skill writes UBIQUITOUS_LANGUAGE.md with topical sections such as order lifecycle or people, then tables containing:

• canonical term
• definition
• aliases to avoid

This format is especially useful for review because disagreements become visible fast.

When this skill is a poor fit

Skip this skill if:

• you do not yet have enough domain material in the conversation
• you need a full ontology, data model, or event storming output
• your goal is brand naming rather than domain clarity
• the domain is still too speculative for canonical term choices

In those cases, gather examples first, then run the skill later.

How to Use ubiquitous-language skill

Install context for ubiquitous-language

If you are using the skills ecosystem from mattpocock/skills, install the ubiquitous-language skill through your normal skill loader. A common pattern is:

npx skills add mattpocock/skills --skill ubiquitous-language

If your environment loads skills another way, use that method instead. The key requirement is that the agent can access the ubiquitous-language skill definition and write UBIQUITOUS_LANGUAGE.md in the working directory.

Read this file first before using it

Start with:

• SKILL.md

This repository path is unusually simple: the main usage logic is in that one file. You do not need to hunt through helper scripts or deep references before deciding whether to try it.

What input the skill actually needs

The skill works best when the current conversation already contains:

• domain nouns: order, invoice, account, shipment
• process verbs: approve, fulfill, cancel
• role names: customer, operator, reviewer
• examples of confusing usage: “we sometimes say subscription, sometimes contract”
• context about boundaries: product area, audience, system, or business process

Without that material, the output will be thin or overly speculative.

How to trigger ubiquitous-language well

A weak request is:

• “Make a glossary.”

A stronger request is:

• “Use the ubiquitous-language skill on this discussion. Extract domain terms, identify synonyms and overloaded words, propose canonical terms, and write UBIQUITOUS_LANGUAGE.md. Group terms by business area.”

That phrasing tells the agent to use the skill as intended, not just improvise a glossary.

Turn a rough goal into a high-quality prompt

A good ubiquitous-language usage prompt usually includes four parts:

1. the domain
2. the source material
3. the conflicts or pain points
4. the output expectation

Example:

“Use the ubiquitous-language skill for our order-management domain. Based on the conversation so far, extract core terms, flag where we use the same word for different concepts, and propose canonical terms with aliases to avoid. Separate customer-facing terms from internal operational terms where needed. Save the result to UBIQUITOUS_LANGUAGE.md.”

Suggested workflow in practice

A reliable workflow is:

1. discuss the domain naturally first
2. let terms collide in conversation
3. run ubiquitous-language
4. review the proposed canonical terms
5. correct business mistakes
6. use the approved glossary in docs, APIs, UI copy, and issue templates

The skill is most valuable after some real discussion, not before it.

Practical tips that improve output quality

To get better results:

• include concrete examples, not just abstract categories
• mention term conflicts explicitly
• say which audience matters most: engineers, users, support, writers
• note whether a term is internal-only or public-facing
• ask the model to preserve meaningful distinctions instead of collapsing everything into one label

These details materially improve the glossary because they reduce false synonym merging.

What technical writers should do differently

For ubiquitous-language for Technical Writing, add constraints such as:

• preferred reader vocabulary
• banned internal jargon
• UI label constraints
• API term constraints
• whether docs should mirror product language or normalize it

Example:

“Use the ubiquitous-language skill, but optimize for external documentation. Prefer terms users will recognize, keep internal code names in aliases to avoid, and note any term that should not appear in public docs.”

That makes the output more editorially usable.

Expected output file and review pattern

The generated file is UBIQUITOUS_LANGUAGE.md. Review it with these questions:

• Did the skill merge distinct concepts by accident?
• Did it keep ambiguous terms without warning?
• Are the “aliases to avoid” realistic?
• Do definitions reflect actual system behavior, not just wording preference?

Treat the first output as a decision draft, not final truth.

ubiquitous-language skill FAQ

Is ubiquitous-language beginner-friendly?

Yes, if you already have a conversation about the domain. You do not need deep DDD expertise to benefit. The output is readable markdown, and the tables make disagreements visible. What beginners often miss is that the quality depends heavily on the specificity of the source discussion.

How is this better than asking for a glossary directly?

The ubiquitous-language skill is narrower and therefore more reliable for terminology alignment. It is designed to detect ambiguity, synonyms, and overloaded terms, then force canonical choices. A generic glossary prompt often lists terms without resolving conflicts.

Does it only help DDD teams?

No. DDD vocabulary is the framing, but the skill is useful anywhere terminology drift causes friction: technical documentation, APIs, support operations, product design, or internal tooling. It is especially useful when multiple teams describe the same workflow differently.

When should I not install ubiquitous-language?

Do not prioritize ubiquitous-language install if your main need is one of these:

• brainstorming product names
• generating end-user documentation from scratch
• building a database schema
• mapping every business rule in detail

This skill is for language normalization, not full domain modeling.

Can it work from a small conversation?

It can, but results are weaker. The skill extracts from the current conversation, so sparse input leads to generic definitions and fewer meaningful conflict detections. If you only have a short chat, add examples, edge cases, and competing terms first.

Does it fit documentation workflows?

Yes. The output file is easy to version, review in pull requests, and reuse across style guides, architecture docs, onboarding material, and API references. That makes ubiquitous-language usage practical for teams who want terminology decisions to live alongside code and docs.

How to Improve ubiquitous-language skill

Give the skill richer domain evidence

The biggest output-quality lever is better source material. Before running ubiquitous-language, include:

• real user-facing terms
• internal shorthand
• process steps
• edge cases
• examples where two people used different words for the same thing

The skill can only normalize what it can see.

Separate true synonyms from important distinctions

A common failure mode is collapsing two related but distinct concepts. Prevent that by stating contrasts directly, for example:

• “Order is the customer request; invoice is the billing artifact.”
• “Account is the legal entity; workspace is the product container.”

This helps the skill preserve domain boundaries instead of over-simplifying.

Tell it which language should win

Canonical naming is opinionated. If you do not state your preference, the skill may choose terms that are technically correct but wrong for your workflow. Improve results by specifying:

• external vs internal vocabulary
• engineering vs business terminology
• UI labels vs back-office labels
• terms that must remain for compatibility

That guidance makes the glossary more usable after generation.

Use stronger prompts for ambiguous domains

If your domain is overloaded, ask explicitly for ambiguity analysis. Example:

“Use the ubiquitous-language skill and be strict about ambiguity. If the same term refers to multiple concepts, split them into separate entries and call out the conflict clearly instead of picking one silently.”

This reduces the risk of false clarity.

Review aliases to avoid with extra care

The “aliases to avoid” column is where many teams get the most value, but also where mistakes can cause confusion. Check whether the banned aliases are:

• truly misleading
• still needed in legacy docs
• acceptable in one audience but not another

A better second pass often keeps the canonical term but softens the alias guidance.

Iterate after the first draft

The best ubiquitous-language guide is iterative:

1. run the skill
2. mark disputed terms
3. add clarifying examples to the conversation
4. rerun the skill
5. approve the glossary
6. apply it across docs and product language

Do not expect the first pass to settle every naming decision.

Extend the result into your documentation system

Once UBIQUITOUS_LANGUAGE.md is stable, improve the value of the ubiquitous-language skill by connecting it to real editorial work:

• link it from your docs style guide
• use it during PR review
• align headings and UI references to canonical terms
• audit old docs for banned aliases

That is how the glossary becomes operational instead of decorative.