ubiquitous-language
Skill5 starsChanged 39 days agoMITView on GitHub
Maintains feature documentation in .agents/features/ and performs mandatory feature overlap detection before any new feature is proposed. Also builds a shared domain vocabulary for Qadam Flow. Use when the user asks to define domain terms, build a glossary, harden terminology, create ubiquitous language, references "domain model" or "DDD", or asks about adding a new feature.
65 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- Robo-Co-op/robobuilder-standardtheir own version, first seen Nov 16, 2026
- richard12511/claude-skillstheir own version, first seen Nov 16, 2026
- draekien/skillstheir own version, first seen Nov 15, 2026
- aegntic/compound-engineeringtheir own version, first seen Nov 8, 2026
- chrislacey89/skillstheir own version, first seen Nov 4, 2026
- Boom-Vitt/skills-thaitheir own version, first seen Nov 1, 2026
Used with
Projects with it also use request-refactor-plan, edit-article and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
simo97Skillrequest-refactor-plan
Use this skill when user wants to create a refactor plan.
Also in 42 projects that use this
simo97Skilledit-article
The user will invoke this skill to help them edit an article.
Also in 35 projects that use this
boyingliu01Skillbatch-grill-me
A relentless interview that asks every frontier question at once, round by round. Thin alias of `grilling` (#540) — upstream mattpocock/skills absorbed this protocol into grilling; XP-Gate keeps this name as the sprint-flow Phase 2 entry point so orchestration docs stay stable.
Also in 5 projects that use this
HK-hubSkillprd-to-plan
Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices, saved as a local Markdown file in ./plans/. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions "tracer bullets".
Also in 9 projects that use this
AnasX7Skillscaffold-exercises
Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
Also in 30 projects that use this
AnasX7Skillsetup-pre-commit
Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
Also in 38 projects that use this
- +4 more from simo97
Other versions65 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- jpoindexter/theft-kit★ 196% same
Wrote their own version · 64
- karlomikus/bar-assistant★ 1.1ksame name
- amazingloft999-droid/mattpocock-skills★ 422same name
- InditexTech/weavejs★ 276same name
- loulanyue/skills★ 231same name
- ayoubben18/ab-method★ 193same name
- CodeAlive-AI/ai-driven-development★ 184same name
- aurorasoft2/Matt_Pocock_Skills★ 133same name
- VisualxIntelligence/mattpocok-skills★ 55same name
- jan-bogaerts/md2★ 42same name
- metrogg/AgentHub★ 19same name
54 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- .agents/features/agents.mdAGENTS.md
- AGENTS.mdAGENTS.md
- add-endpointSkill
- add-entitySkill
- add-featureSkill
- agent-browserSkill
- db-migrationSkill
- designSkill
- grill-meSkill
- local-docker-deploySkill
- mcp-builderSkill
- mintlifySkill
- playwright-e2e-testingSkill
- qadam-builderSkill
- versioningSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 61 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Before writing a single line of code or proposing a design for a new feature, you MUST check for existing features with similar or …
- Distinctive: line 48
Always present your findings to the user before proceeding.
- Very specific: line 54
Every feature in Qadam Flow must have a corresponding .md file in .agents/features/.
- Very specific: line 58
After the feature is implemented, create a new file at .agents/features/<feature-name>.md with this structure:
- Very specific: line 86
After making changes to a feature, update its .agents/features/<feature-name>.md to reflect:
- Distinctive: line 92
This is not optional: Every PR that changes a feature's behavior must include an update to its feature doc.
- Distinctive: line 109
Before updating the glossary, surface any of the following to the user for resolution:
- Distinctive: line 117
Do not silently resolve ambiguities — always confirm with the user.
- Distinctive: line 121
Create or update this file as the central domain glossary.
- Distinctive: line 146
Keep terms in alphabetical order within each cluster.
- Distinctive: line 150
When writing or reviewing code, use only the canonical term from the glossary.
- Distinctive: line 156
When this skill is triggered a second or subsequent time in the same session:
- Very specific: line 158
Read the existing .agents/features/ docs and GLOSSARY.md (do not recreate from scratch).
- Distinctive: line 161
Create or update feature docs as needed.
“Common” is measured: kept by at least 6 in 10 of the 61 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Qadam Flow Ubiquitous Language
Maintain per-feature documentation in .agents/features/, establish a shared vocabulary for the Qadam Flow domain, and prevent redundant features by detecting overlap with existing functionality before any new work begins.
Trigger Phrases
Activate this skill when the user:
- Asks to define domain terms, build a glossary, or harden terminology
- Mentions "ubiquitous language", "domain model", or "DDD"
- Says they want to "create ubiquitous language" or "align on terminology"
- Asks about adding, building, or proposing any new feature
- Uses a term ambiguously or inconsistently across the conversation
Workflow
Step 1: FEATURE OVERLAP DETECTION (mandatory before any new feature)
Before writing a single line of code or proposing a design for a new feature, you MUST check for existing features with similar or overlapping functionality.
Search checklist — complete all five before concluding:
- Feature docs — read all
.mdfiles in.agents/features/to understand what features already exist, what they cover, and how they work. This is the primary source of truth for feature inventory. - Components / services / hooks — use the Glob tool to find files whose names relate to the proposed concept (e.g.,
packages/**/*<keyword>*.{ts,tsx}), then use the Grep tool to search file contents for the keyword. Also search by directory name patterns (e.g.,packages/server/api/src/app/<concept>/). - Route definitions — use the Grep tool to check whether an API route already covers the use case: search for the keyword in
packages/server/api/srcwith glob*.ts. - Shared types — use the Grep tool to inspect
packages/shared/src/for existing type definitions or enums that represent the concept. - Feature flags / plan limits — use the Grep tool to search
packages/shared/src/lib/for any existing capability or plan flag that may gate the feature.
Decision rule:
| Finding | Action |
| Close match exists | Present the match to the user. Recommend extending the existing feature. Do NOT proceed with a new feature without explicit user approval. |
| Partial overlap | Present overlapping parts. Ask whether the new feature should be merged into the existing one or kept separate, and document the rationale. |
| No match | Confirm to the user that no overlap was found, then proceed with the new feature design. |
Always present your findings to the user before proceeding. Never silently skip this step.
Step 2: FEATURE DOCUMENTATION
Every feature in Qadam Flow must have a corresponding .md file in .agents/features/. This is a living registry that agents and developers use to understand what exists before building something new.
2a. When creating a new feature
After the feature is implemented, create a new file at .agents/features/<feature-name>.md with this structure:
# <Feature Name>
## Summary
One-paragraph description of what this feature does and why it exists.
## Key Files
- `packages/web/src/features/<path>` — frontend components
- `packages/server/api/src/app/<path>` — backend service/controller
- `packages/shared/src/lib/<path>` — shared types
## Domain Terms
Key terms used by this feature (link to glossary definitions if they exist).Never add an "Edition Availability" section. This repo ships a single edition — see
.agents/rules/edition-safety.md. There is no ApEdition enum, no plan tier, and the
module-local getPlan() in packages/server/api/src/app/platform/platform.service.ts returns a
fixed object, so any per-edition statement is untrue by construction. (getPlan is not a member of
platformService — the public surface is getOneWithPlan / getOneWithPlanOrThrow /
getOneWithPlanAndUsageOrThrow, which attach its result.) If a feature really is gated, document the
gate itself: name the PlatformPlan flag, the file that reads it, and the value getPlan()
hardcodes — that is checkable and stays true.
2b. When modifying an existing feature
After making changes to a feature, update its .agents/features/<feature-name>.md to reflect:
- New or removed key files
- Any
PlatformPlanflag the change starts or stops reading - New domain terms introduced
- Any scope changes to the feature's summary
This is not optional. Every PR that changes a feature's behavior must include an update to its feature doc.
Step 3: DOMAIN GLOSSARY MANAGEMENT
3a. Scan the conversation for domain terms
As you read the conversation, collect every noun, verb, or phrase that:
- Names a core entity (e.g. Flow, Piece, Step, Run, Connection, Project, Platform)
- Names a process or action (e.g. publish, trigger, execute, sync)
- Carries specialised meaning in this codebase that differs from everyday usage
- Is used inconsistently or interchangeably with another term
3b. Flag problems before writing the glossary
Before updating the glossary, surface any of the following to the user for resolution:
| Problem type | Example | How to flag |
| Ambiguity — same word, different meanings | "connection" means both a saved credential and a live socket | List both usages; ask which meaning should be canonical |
| Synonym collision — different words, same concept | "run" vs "execution" vs "flow run" | Identify the preferred term; mark the others as aliases to avoid |
| Undefined jargon — term used but never defined | "piece" first appears without explanation | Ask for a one-sentence definition |
Do not silently resolve ambiguities — always confirm with the user.
3c. Write or update .agents/features/GLOSSARY.md
Create or update this file as the central domain glossary. Structure it as follows:
# Domain Glossary — Qadam Flow
> Last updated: <date>
## <Domain Cluster Name>
| Term | Definition (one sentence) | Aliases to avoid | Related terms |
|---|---|---|---|
| Flow | A named automation consisting of a trigger and one or more steps. | workflow, automation, pipeline | Step, Trigger, Run |
| ... | ... | ... | ... |
## <Next Domain Cluster Name>
...Formatting rules:
- Group terms into domain clusters (e.g., Automation Core, Platform & Multi-tenancy, Pieces & Integrations, Tables & Data, Authentication).
- Each definition is one sentence only — no exceptions. If a concept needs more explanation, link to a doc or ADR.
- The "Aliases to avoid" column lists terms that have been seen in the codebase or conversation but should be retired in favour of the canonical term.
- The "Related terms" column lists other glossary entries that are closely connected.
- Keep terms in alphabetical order within each cluster.
3d. Canonical term enforcement
When writing or reviewing code, use only the canonical term from the glossary. If you see a deprecated alias in existing code, inform the user about each occurrence and let them decide whether to rename it now or track it as technical debt for later.
Step 4: RE-INVOCATION (when called again in the same conversation)
When this skill is triggered a second or subsequent time in the same session:
- Read the existing
.agents/features/docs andGLOSSARY.md(do not recreate from scratch). - Identify new terms or features introduced since the last invocation.
- Integrate new terms into the glossary, maintaining alphabetical order.
- Create or update feature docs as needed.
- Flag any fresh ambiguities or synonym collisions found in the new context.
- Present a diff summary to the user: which terms/features were added, updated, or flagged.
Quick Reference
| Task | Action |
| New feature requested | Run Step 1 (overlap detection via .agents/features/ + codebase search) — always |
| Feature implemented or modified | Update its .agents/features/<name>.md via Step 2 |
| New term encountered | Add to glossary via Step 3 |
| Ambiguity detected | Flag to user before resolving |
| Skill re-invoked | Follow Step 4 (incremental update) |
| Deprecated alias found in code | Inform user; let them decide to rename now or defer as tech debt |
Critical Reminders
- Feature overlap detection is not optional — check
.agents/features/and the codebase before every new feature, no exceptions. - Feature docs must stay current — every change to a feature's behavior requires an update to its
.agents/features/<name>.md. - One-sentence definitions — longer definitions are a sign the concept needs to be split.
- Never resolve ambiguities silently — always confirm the canonical meaning with the user.
- Aliases to avoid are as important as definitions — they prevent synonym drift from creeping back into the codebase.
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.

