From ywc-agent-toolkit
Creates, extracts, or updates a project's ubiquitous language document (shared domain vocabulary) to align developers, domain experts, and LLMs. Supports new, extract, and update modes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ywc-agent-toolkit:ywc-ubiquitous-languageThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Announce at start:** "I'm using the ywc-ubiquitous-language skill to create or update the project's shared domain vocabulary."
Announce at start: "I'm using the ywc-ubiquitous-language skill to create or update the project's shared domain vocabulary."
This skill produces or maintains docs/ubiquitous-language.md — a shared vocabulary file that aligns developers, domain experts, and LLMs on canonical term usage. It operates in three modes: new (interview-driven creation from scratch), extract (term discovery from an existing codebase), and update (incremental revision of an existing document).
When tempted to bypass a rule, check this table first:
| Excuse | Reality |
|---|---|
| "Everyone on the team knows the terms — no need for a document" | LLMs do not share team knowledge. Every term the LLM misinterprets costs a correction cycle. The document is primarily for LLM context injection, not just team alignment. |
| "I'll auto-extract and write the file without user confirmation" | Extracted terms without definition review produce a synonym-polluted glossary. A raw class name is not a domain term until a human confirms its meaning. Always present candidates before writing. |
| "Korean translation is obvious — I'll infer it" | Machine-inferred Korean business terms introduce errors that survive in code and prompts for years. Surface every Korean equivalent to the user for confirmation. |
| "Bounded Contexts add complexity for a small project, use a flat list" | A flat glossary lets homonyms (same term, different meaning in different contexts) silently coexist. Start with "Core Domain" if only one context exists — it takes one line. |
| "The file already exists, I'll append without reading it" | Appending without reading creates duplicate entries and contradictory definitions. Always read the full file before any write. |
| "ywc-project-docs handles the docs/ structure, I'll skip update" | ywc-project-docs manages directory skeleton and README-level docs. ywc-ubiquitous-language owns domain vocabulary content. Both must run independently. |
| "DDD types (Entity, Aggregate etc.) are overkill here, skip the column" | DDD Type column is optional — controlled by --ddd flag. But the Synonyms to Avoid column is always required; it is the highest-value anti-confusion signal. |
Violating the letter of these rules is violating the spirit. A glossary with unconfirmed terms or missing synonyms degrades LLM output quality with every prompt that references it.
| Parameter | Format | Default | Description |
|---|---|---|---|
--mode | --mode new|extract|update | auto-detect | Force a specific mode (see Mode Detection below) |
--context | --context <name> | all contexts | Scope to a single Bounded Context for extract/update |
--output | --output <path> | docs/ubiquitous-language.md | Output file path |
--ddd | flag | off | Add DDD Type column (Entity / Value Object / Aggregate / Domain Event / Policy) |
--dry-run | flag | off | Show proposed changes without writing to disk |
--mode is omitted)| Condition | Auto-selected mode |
|---|---|
docs/ubiquitous-language.md exists | update |
File absent AND source files found (src/, app/, lib/, internal/) | extract |
| File absent AND no source files | new |
Step 1: Domain Overview Ask the user for a 2-3 sentence description of the domain if not already in context. Identify the primary domain and any obvious sub-domains.
Step 2: Bounded Context Identification
Propose "Core Domain" as the default single context. If the domain description suggests multiple areas of responsibility, propose 2-4 candidate context names and ask the user to confirm or revise. Start with the minimum set — contexts can be added in update mode.
Step 3: Term Elicitation per Context For each context, gather 5–15 core terms via conversation. For each term, collect:
If --ddd flag is set, also collect: DDD Type (Entity / Value Object / Aggregate / Domain Event / Policy).
Step 4: Write File
Write to --output path using the format in references/document-format.md.
Step 5: CLAUDE.md Integration Prompt After writing, print:
★ To give LLMs automatic access to this vocabulary, add the following line to your CLAUDE.md:
@docs/ubiquitous-language.md
Step 1: Scan for Candidate Terms Apply the extraction heuristics in references/extraction-guide.md. Focus on:
Step 2: Cluster into Context Candidates Group candidates by module/package path. Propose each group as a Bounded Context name. Show the user a table:
Context candidate: "Order" (from src/order/, 12 candidates)
Context candidate: "Payment" (from src/payment/, 7 candidates)
Step 3: User Confirmation Present the full candidate list. User confirms, rejects, or relabels each term. Do not write any term the user has not confirmed.
Step 4: Definition Gathering For confirmed terms, gather definitions the same way as Mode: new — Step 3.
Step 5: Write File Same as Mode: new — Step 4 and Step 5.
Step 1: Read Existing File
Read the full docs/ubiquitous-language.md. Parse all existing terms, contexts, and synonyms.
Step 2: Identify Changes Ask the user: "What changed since the last update?" Options:
git log --oneline -20 and surface domain-relevant changesStep 3: Build CHANGESET Propose three lists for user confirmation:
~~strikethrough~~ + note, do not delete)Step 4: Apply and Update
Apply confirmed changes. Update the <!-- updated: DATE --> header. Append a brief change summary at the bottom of the file.
The full format specification is in references/document-format.md.
Summary:
# Ubiquitous Language — [Project Name]
<!-- updated: YYYY-MM-DD -->
## Overview
[Domain description, 2-3 sentences]
## Bounded Contexts
| Context | Responsibility |
|---------|---------------|
---
## [Context Name]
| Term | Korean | Definition | Synonyms to Avoid |
|------|--------|-----------|------------------|
With --ddd flag, a Type column (Entity/Value Object/Aggregate/Domain Event/Policy) is inserted between Korean and Definition.
Before declaring complete:
— if truly none)docs/ubiquitous-language.md is parseable Markdown with no broken table rows<!-- updated: DATE --> header reflects today's date~~deprecated~~ marker destroys the history of why a term was abandoned. Teams need that context.ywc-plan (call during planning to establish vocabulary before spec writing), ywc-project-docs (project docs skeleton)ywc-task-generator (tasks reference canonical terms), ywc-code-gen (code generation uses canonical naming), ywc-spec-validate (spec consistency check)ywc-spec-validate — spec terms should match ubiquitous language; flag mismatchesnpx claudepluginhub yongwoon/ywc-agent-toolkitGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.