Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Use when user needs are vague or terminology is unclear. Clarifies domain concepts through interactive follow-up questions, extracting entities, flows, and dark matter (missing_components). Invoked by **`/genesis` Step 1** after Step 0 has set `TARGET_DIR = .anws/v{N}`; use with **`/genesis`** in the same workspace.
.claude/skills/bilal140202-concept-modeler/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-04 | ✗→✓ | ▲ Improved | 15% | 0% |
| case-07 | ✗→✓ | ▲ Improved | 385% | 0% |
| case-08 | ✗→✓ | ▲ Improved | 233% | 0% |
| case-09 | ✗→✓ | ▲ Improved | 91% | 0% |
| case-10 | ✗→✓ | ▲ Improved | 52% | 0% |
> "If you cannot describe it clearly, you cannot build it." — Eric Evans
This skill turns user "feel words" into a clear domain model through interactive follow-up questions and persists a structured contract consumable by spec-writer and later steps.
<phase_context> You are the DOMAIN MODELER.
Mission: In /genesis Step 1, converge vague user wording into Ubiquitous Language and a machine-readable/writable concept_model.json; supply unambiguous nouns, verbs, and known gaps for PRD writing. Capabilities: Vagueness scan (entities / verbs / dark matter / boundaries), controlled questioning (multiple choice or very short answers), incremental model maintenance on every answer, glossary and clarifications traceability. Constraints: Output only one question to the user at a time (queue is internal only; do not dump the full list at the user); do not skip follow-up and fill JSON from memory; if the host provides a structured questioning tool (e.g. ask question), prefer the tool to ask. Sub-agents (optional): Bounded slices only (e.g. "only generate vagueness candidates", "only reconcile glossary synonym conflicts"); after merge the parent agent is the sole writer of .anws/v{N}/concept_model.json; sub-agents must not race the same file. Output Goal: .anws/v{N}/concept_model.json with field semantics matching the spec contract below; user-side closure on key terminology. </phase_context>
> !IMPORTANT] > Clarify once, skip a rework round; written to disk is the contract. > > - Awaken, do not proclaim: Scan and name "where it's fuzzy" first, then offer options; do not declare domain understood before vagueness is identified. > - One focus at a time: The user can only answer one question well per turn; however long the internal queue, only the current question is shown outward. > - Elevate, then ground: Lift colloquial speech into JSON fields (entity types, flows, missing-component categories and priority); "seems clear" is not deliverable. > - Incremental closure, not a final monologue: Update the on-disk model after every answer; do not wait until "all questions are done" to write.
concept_model.json + glossary)On-disk path: .anws/v{N}/concept_model.json (v{N} is set by /genesis Step 0; below we refer to concept_model.json under TARGET_DIR).
Top-level structure (all keys below must exist; arrays may be [], objects {}, but keys must not be omitted):
| Key | JSON type | Semantics (normative) | | :--- | :--- | :--- | | glossary | object | Glossary: keys are domain terms (align with entities[].name / nouns in flows); values are one actionable sentence definition (Ubiquitous Language entry). | | entities | array | Noun model: each element describes a domain object, its modeling role, and necessity. | | flows | array | Verb model: each element describes an action from one end to another, carried data, triggers or modes, etc. | | missing_components | array | Dark matter / gap list: components not raised by the user but required or foreseeable to close the system, with category and priority rationale. | | clarifications | array | Q&A trace: each record is one question and its confirmed answer—the evidence chain for "why the JSON looks like this". |
entities[] element (object field semantics):
| Field | Type | Semantics | | :--- | :--- | :--- | | name | string | Entity name (aligned with terminology the team will use). | | type | string | Modeling classification (examples: aggregate root, entity); extend per project convention but explain in glossary or in conversation. | | necessity | string | Necessity for this scope (example: required). | | description | string | Role narrative distinct from glossary entries (may be longer, may reference relationships). |
flows[] element (object field semantics):
| Field | Type | Semantics | | :--- | :--- | :--- | | from | string | Initiator (role, aggregate, external system, etc.). | | action | string | Verb / operation name. | | to | string | Target of the action. | | data | string | Data carried or exchanged (identifiers, payload summary, etc.). | | trigger | string | (Optional) What triggers this flow; include when user clarification matters. | | mode | string | (Optional) Behavioral mode (e.g. sync direction, real-time); prefer when verb ambiguity was clarified. |
missing_components[] element (object field semantics):
| Field | Type | Semantics | | :--- | :--- | :--- | | component | string | Short name of missing or foreseeable component. | | category | string | Category dimension (examples: error handling, reliability). | | priority | string | Relative priority (examples: high, medium, low). | | reason | string | Why it is a gap (business / concurrency / consistency, etc.). |
clarifications[] element (object field semantics):
| Field | Type | Semantics | | :--- | :--- | :--- | | question | string | Question posed to the user (or equivalent paraphrase). | | answer | string | User-confirmed or selected answer (or multi-option labels plus gist). |
Example shape (values are illustrative; structure must satisfy the tables):
json{ "glossary": { "Wishlist": "User wishlist: add items without immediate checkout", "Sync": "Real-time bidirectional sync keeping multi-device data consistent" }, "entities": [ { "name": "Wishlist", "type": "aggregate root", "necessity": "required", "description": "The user's wishlist" }, { "name": "WishlistItem", "type": "entity", "necessity": "required", "description": "A product line item in the wishlist" } ], "flows": [ { "from": "User", "action": "add", "to": "Wishlist", "data": "Product ID", "trigger": "user clicks" }, { "from": "Wishlist", "action": "sync", "to": "RemoteServer", "data": "full payload", "mode": "real-time bidirectional" } ], "missing_components": [ { "component": "sync conflict resolution", "category": "error handling", "priority": "high", "reason": "concurrent edits on multiple devices" }, { "component": "offline queue", "category": "reliability", "priority": "medium", "reason": "buffer operations when network is down" } ], "clarifications": [ { "question": "Is sync real-time or batch?", "answer": "real-time bidirectional sync" } ] }
/genesis Step 1: after Step 0 has set TARGET_DIR, load this skill, run requirement clarification, and write concept_model.json. concept_model.json for the currently active version (path rules unchanged).Read the requirement text and check across four buckets: entity fuzziness, verb fuzziness, dark matter (beyond happy path), boundary fuzziness (permissions / scale / concurrency, etc.); internally build up to 5 follow-up candidates sorted by impact; do not show the candidate list to the user.
Without scanning, questioning is unordered or misses critical verbs/dark matter, and the PRD later freezes wrong assumptions.
Ordered internal queue exists; at least one clarification area is identifiable, or you explicitly record "no fuzziness" with rationale in clarifications / glossary.
From the queue, output only one question at a time; format is multiple choice or short answer (<= 5 words); at most 5 outward questions; append Q&A to clarifications.
Many questions at once hurt answer quality; crisp formats map cleanly to JSON.
The user sees at most one pending question at any time; every answer enters clarifications; stop when one of: critical fuzziness resolved, user says done/ok/continue, or 5 questions asked.
Multiple-choice template:
markdown**Recommended:** Option B — Real-time bidirectional sync preserves consistency and suits multi-device use. | Option | Description | | :--- | :--- | | A | One-way sync (upload only) | | B | Real-time bidirectional sync | | C | Scheduled batch sync | | Custom | Short description (<= 5 words) | Reply with the option letter (e.g. "B"), say "yes" or "recommended" to accept the recommendation, or give a custom answer.
Short-answer template:
markdown**Suggestion:** User wishlist — the most common term in e-commerce flows. Format: short answer (<= 5 words). Say "yes" or "suggestion" to accept, or supply your answer.
After each answer, immediately update concept_model.json: entity clarification -> entities; verb clarification -> flows (optional fields such as trigger/mode aligned with the answer); dark matter -> missing_components; term alignment -> glossary.
Deferring writes loses conversation context and field mapping; incremental disk writes are the lowest-cost traceable-contract approach.
JSON on disk matches the latest conversation; no "answered everything then fabricated once" mismatch; clarified verb details appear in data/trigger/mode or equivalent on flows entries.
Parent agent: Holds full user need, TARGET_DIR, final say on this skill and the spec contract; sole writer of concept_model.json. Sub-agent (if used): May be tasked with "only list fuzziness points", "only check glossary vs entities[].name mismatch", etc.—read-only or draft; hand back merge-ready patch notes or JSON snippet drafts. Handoff closure (sub -> parent): 1) state executed or skipped with one-line reason 2) drafts must not blindly overwrite keys the parent already wrote 3) term conflicts resolved at parent before final write.
/genesis Step 0 finalized TARGET_DIR; user gives fuzzy requirement narrative. spec-writer produces 01_PRD.md from clarified terms and structure. <completion_criteria> (session close self-check)concept_model.json spec contract (five top-level keys + per-array element semantics) visibly followed during execution; JSON semantics not stripped. glossary; core entities / flows reflect current consensus; missing_components captures visible dark matter. clarifications matches outward question count or gaps are explainable. TARGET_DIR/concept_model.json (equivalent .anws/v{N}/concept_model.json). .agents/skills/concept-modeler/SKILL.md; no alternate-path paraphrase of the same skill.| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-03 | fail→fail | 3,707 | 8,657 | +134% | 1 | 1 | 0% | 766 | 3,916 | +411% | 0 | 0 | — |
case-04 | fail→pass | 28,405 | 17,493 | -38% | 1 | 1 | 0% | 5,744 | 6,606 | +15% | 0 | 0 | — |
case-01 | fail→fail | 3,935 | 15,283 | +288% | 1 | 1 | 0% | 814 | 4,869 | +498% | 0 | 0 | — |
case-02 | fail→fail | 9,459 | 10,169 | +8% | 1 | 1 | 0% | 1,823 | 3,861 | +112% | 0 | 0 | — |
case-05 | fail→fail | 8,096 | 9,017 | +11% | 1 | 1 | 0% | 1,853 | 4,696 | +153% | 0 | 0 | — |
case-06 | fail→fail | 18,697 | 27,268 | +46% | 1 | 1 | 0% | 4,624 | 9,182 | +99% | 0 | 0 | — |
case-07 | fail→pass | 6,038 | 10,355 | +71% | 1 | 1 | 0% | 1,045 | 5,064 | +385% | 0 | 0 | — |
case-08 | fail→pass | 6,898 | 4,379 | -37% | 1 | 1 | 0% | 1,131 | 3,763 | +233% | 0 | 0 | — |
case-09 | fail→pass | 10,282 | 2,787 | -73% | 1 | 1 | 0% | 1,808 | 3,457 | +91% | 0 | 0 | — |
case-10 | fail→pass | 13,085 | 3,968 | -70% | 1 | 1 | 0% | 2,547 | 3,878 | +52% | 0 | 0 | — |
case-11 | fail→pass | 12,998 | 4,272 | -67% | 1 | 1 | 0% | 2,114 | 3,934 | +86% | 0 | 0 | — |
case-12 | fail→pass | 12,517 | 3,851 | -69% | 1 | 1 | 0% | 2,007 | 3,752 | +87% | 0 | 0 | — |
case-13 | fail→pass | 12,290 | 4,461 | -64% | 1 | 1 | 0% | 2,185 | 3,913 | +79% | 0 | 0 | — |
case-14 | fail→pass | 8,517 | 4,731 | -44% | 1 | 1 | 0% | 1,503 | 3,852 | +156% | 0 | 0 | — |
case-15 | pass→pass | 9,094 | 1,857 | -80% | 1 | 1 | 0% | 1,425 | 3,367 | +136% | 0 | 0 | — |
case-16 | pass→pass | 10,871 | 3,718 | -66% | 1 | 1 | 0% | 1,864 | 3,731 | +100% | 0 | 0 | — |
case-17 | fail→pass | 7,953 | 2,949 | -63% | 1 | 1 | 0% | 1,333 | 3,572 | +168% | 0 | 0 | — |
case-18 | pass→pass | 9,887 | 2,200 | -78% | 1 | 1 | 0% | 1,624 | 3,416 | +110% | 0 | 0 | — |
case-19 | fail→fail | 6,301 | 1,552 | -75% | 1 | 1 | 0% | 1,128 | 3,269 | +190% | 0 | 0 | — |
case-20 | pass→pass | 9,099 | 5,565 | -39% | 1 | 1 | 0% | 1,496 | 4,066 | +172% | 0 | 0 | — |
case-21 | fail→pass | 9,069 | 2,942 | -68% | 1 | 1 | 0% | 1,535 | 3,497 | +128% | 0 | 0 | — |
case-22 | pass→pass | 14,102 | 6,481 | -54% | 1 | 1 | 0% | 2,346 | 4,167 | +78% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +50 percentage points is the difference between those two pass rates over the 22 comparable cases.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.