maintaining-ubiquitous-language
Skill0 starsChanged 25 days agoApache-2.0View on GitHub
Maintain a project-specific glossary of domain terms in LANGUAGE.md at the repo root. Use when a new domain term emerges in conversation, when reviewing code that uses inconsistent terminology, when onboarding a new contributor or agent, or when an existing definition becomes stale.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- configuration-managementSkill
- designing-clear-data-displaysSkill
- lake-conventionsSkill
- maintaining-project-contextSkill
- maintaining-the-common-operating-pictureSkill
- python-venv-managementSkill
- recording-architecture-decisionsSkill
- shift-left-testingSkill
- traversing-the-knowledge-baseSkill
- using-topic-branchesSkill
- verifying-claimsSkill
- writing-simple-and-directSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Do not invoke this skill for:
- Distinctive: line 34
If you find yourself writing a multi-sentence definition, the term probably belongs in CONTEXT.md, in a design doc, or in code …
- Distinctive: line 56
When a candidate term emerges:
- Distinctive: line 60
Confirm with the user: Do not commit to LANGUAGE.md without the user's nod: definitions are policy-level, not implementation-level.
- Distinctive: line 61
Update LANGUAGE.md: Add the entry to the correct topical section (Decision Science, Agent Framework, Escalation Ladder, Governance, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Maintaining Ubiquitous Language
Maintain a project-specific glossary of domain terms in LANGUAGE.md at the repo root. The pattern is general; the vocabulary is project-specific. This project's LANGUAGE.md covers decision science, the agent framework, the military escalation ladder, and governance, not TypeScript ecosystem overloads.
When to Use
Invoke this skill when any of the following occur:
- A new domain term enters the conversation that risks being defined two different ways by two different people or two different agents.
- Code review surfaces inconsistent terminology: different files using different words for the same concept, or the same word for different concepts.
- A new contributor or agent is onboarded and needs to know what words mean here.
- An existing LANGUAGE.md entry becomes stale (the concept changed; the synonyms list is incomplete; the entry conflicts with how the term is actually used).
Do not invoke this skill for:
- Terms that have appeared exactly once and may not recur.
- General-purpose programming vocabulary that has no project-specific meaning.
- Synonyms or aliases handled adequately by a comment or docstring.
Core Rules
These rules come from Pocock's CONTEXT-FORMAT.md, verbatim where strong. They are not negotiable: the discipline is the point.
- Keep definitions tight. One sentence max.
- Define what it IS, not what it does.
- Each term gets a bold name, one-line definition, and
_Avoid:_list of synonyms (when ambiguity exists). - It is a glossary and nothing else. Not a spec, not a scratch pad.
If you find yourself writing a multi-sentence definition, the term probably belongs in CONTEXT.md, in a design doc, or in code documentation, not in LANGUAGE.md.
Entry Format
**TermName**: One-sentence definition stating what the term IS, not what it does. _Avoid:_ synonym1, synonym2, synonym3.Real examples from this project's LANGUAGE.md:
**Criterion**: A dimension along which alternatives are compared. _Avoid:_ factor, attribute, measure, metric.
**Wave**: A tactical parallel-execution unit inside a CONOP or OPORD where agent teams deploy. Bounded by a shared exit criterion. _Avoid:_ sprint, batch.
**Skill**: A self-loading capability defined in `.claude/skills/<name>/SKILL.md` (directory form, preferred) or `.claude/skills/<name>.md` (single-file, legacy), invoked by name or auto-triggered by Claude when the description matches. _Avoid:_ procedure (too generic), playbook (already taken by team templates).The _Avoid:_ list is only included when ambiguity exists. A term with no plausible synonyms doesn't need one.
Workflow
When a candidate term emerges:
- Notice the moment. A term is candidate-worthy when (a) two participants in the conversation appear to mean different things by it, OR (b) the same concept has been referred to by two different names in the last few exchanges.
- Propose the entry inline. Draft the entry following the format. Keep it under one sentence. Identify the
_Avoid:_list. - Confirm with the user. Do not commit to LANGUAGE.md without the user's nod: definitions are policy-level, not implementation-level.
- Update LANGUAGE.md. Add the entry to the correct topical section (Decision Science, Agent Framework, Escalation Ladder, Governance, Workflow Artifacts, or a new section if the term doesn't fit).
- Propagate the rename. If the new entry conflicts with existing prose or code (e.g., LANGUAGE.md now says use "criterion" but several files say "factor"), surface the inconsistency. Do not silently rewrite; flag it for the user to decide whether to fix now or track as a separate task.
What LANGUAGE.md Is Not
To prevent scope creep, LANGUAGE.md is not:
- A specification of behavior. (That's CONTEXT.md or design docs.)
- A scratch pad for exploratory thinking. (That's
docs/design/hold/or session notes.) - A list of every term in the codebase. (Only project-specific terms with ambiguity risk belong.)
- A versioned API surface. (Definitions can change; consumers don't depend on stability.)
- Documentation of one-off jargon. (Recurrence + ambiguity is the bar.)
References
- Eric Evans, Domain-Driven Design — the original "ubiquitous language" pattern, adapted here.
- Matt Pocock,
mattpocock/skills/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md— the format and discipline adopted here. - This project's LANGUAGE.md — the artifact this skill maintains.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

