ubiquitous-language

Overview of ubiquitous-language skill

What ubiquitous-language does

The ubiquitous-language skill turns a messy conversation into a DDD-style glossary: it extracts domain terms, spots ambiguity and synonym drift, then writes a canonical UBIQUITOUS_LANGUAGE.md file. If you need a shared vocabulary for product, engineering, or Technical Writing, this ubiquitous-language skill helps make terminology explicit instead of letting the model improvise.

Who should install it

Install this ubiquitous-language skill if you are defining a domain model, documenting a product area, aligning teams on terms, or cleaning up confusing language across specs and docs. It is especially useful when you already have a live conversation, interview transcript, or requirements thread and want the terminology normalized fast.

Why it is useful

The real job-to-be-done is not “write a glossary”; it is “prevent meaning drift.” This skill is strong when your biggest risk is inconsistent naming, overloaded terms, or multiple words for the same thing. It is less about generating prose and more about choosing one canonical term and explaining what to avoid.

How to Use ubiquitous-language skill

Install and locate the skill files

Use the ubiquitous-language install flow from your skills manager, or install from the repo path mattpocock/skills under skills/deprecated/ubiquitous-language. Start with SKILL.md; there are no helper scripts, references, or resource folders here, so the main behavior is concentrated in that one file.

Give it the right source material

For best ubiquitous-language usage, provide the skill with a conversation, notes, ticket thread, or draft spec that contains real domain language. A strong prompt names the context and the decision surface, for example: “Extract the ubiquitous-language glossary from this product discovery conversation for an order-management app. Prioritize customer, order, invoice, shipment, and refund terms, and flag any words that seem overloaded.”

Shape the prompt for output quality

The skill works best when you tell it what terms matter and what audience the glossary serves. If you want ubiquitous-language for Technical Writing, say that explicitly and ask for terminology that can be reused in docs, UI labels, and API docs. Include constraints such as “prefer opinionated canonical terms,” “call out aliases to avoid,” or “focus on terms with user-facing impact.”

Follow a simple workflow

First, paste the source conversation or notes. Next, ask for the glossary and the ambiguities it finds. Then review the generated UBIQUITOUS_LANGUAGE.md against product reality: confirm whether each term is truly distinct, whether synonyms should be merged, and whether any term should be renamed to match the team’s actual vocabulary.

ubiquitous-language skill FAQ

Is this better than a normal prompt?

Yes, when you want repeatable terminology cleanup rather than a one-off summary. A normal prompt may produce a list of terms, but the ubiquitous-language skill is built to identify ambiguity, propose canonical wording, and save the result in a reusable file format.

What does it not do?

It does not replace domain validation with stakeholders. It can infer and organize terms from the conversation, but it cannot know which label your team has officially adopted. If the source material is thin or contradictory, the output should be treated as a draft for review, not a source of truth.

Is it beginner-friendly?

Yes, if you can provide a clear source text and a target domain. The main beginner mistake is asking for “a glossary” without supplying enough domain context. The more specific the conversation and the more explicit the audience, the better the ubiquitous-language guide will perform.

When should I skip it?

Skip this skill if you only need a short marketing definition, a generic glossary page, or a broad taxonomy with no real term conflicts. It is most valuable when language choice affects implementation, documentation, or cross-functional alignment.

How to Improve ubiquitous-language skill

Give more domain evidence, not more fluff

The biggest improvement comes from richer source language: user stories, support tickets, onboarding copy, and product discussions all help. For ubiquitous-language usage, terms surrounded by examples are easier to normalize than abstract feature lists.

Ask for the decisions that matter

Tell the skill what to optimize for: consistency across docs, fewer synonyms in the UI, clearer API naming, or stronger DDD alignment. If you are using ubiquitous-language for Technical Writing, ask it to prefer terms that work well in headings, labels, table rows, and reuse across docs.

Review for common failure modes

Watch for over-merging distinct concepts, inventing terms that the team would never use, or flattening domain nuance into generic language. If the first draft feels too abstract, respond with examples of edge cases and ask the skill to rework the glossary around those distinctions.

Iterate with specific corrections

The fastest way to improve output is to mark exactly which term choices are wrong and why. For example: “Use customer instead of account, keep order separate from purchase, and treat refund and credit as distinct concepts.” That kind of feedback makes the next ubiquitous-language skill pass much sharper.