Converts source documents (transcripts, briefs, specs, flow descriptions) into structured YAML mental model files. Use this skill whenever the user wants to create a mental model, convert a document into a .yml mental model, generate a business or UX/UI model from source material, or mentions 'mental model', 'yml model', 'YAML model', or asks to structure project knowledge into models. Also trigger when the user provides a transcript or brief and asks to 'extract a model', 'structure this', or 'turn this into a mental model'. Covers both business-domain models (how a business works, operational flows, strategy) and UI/UX models (screens, features, interaction flows).
How this skill is triggered — by the user, by Claude, or both
Slash command
/mental-model-yml:mental-model-ymlThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Converts source documents into structured `.yml` mental model files following standardized templates.
Converts source documents into structured .yml mental model files following standardized templates.
This skill takes source material (meeting transcripts, briefs, specs, flow descriptions) and produces .yml files that follow one of two templates: business model or UI/UX model. The templates live in references/ — always read the relevant template before generating.
The skill operates in three phases: Gather → Plan → Generate.
Collect all required inputs before doing any work. Ask the user these questions — do not proceed until all required inputs are provided.
1. Source Material Ask: "What source material should I use? Attach transcripts, briefs, specs, or any relevant documents."
This is non-negotiable. Without source material, the skill cannot produce an evidence-based model. If the user tries to proceed without attaching anything, respond:
"I need at least one source document (transcript, brief, spec, etc.) to generate a mental model. The value of a mental model comes from being traceable to evidence — without sources, I'd be inventing content. Please attach the relevant documents."
2. Model Type Ask: "Is this a business model or a UI/UX model?"
| Type | Use when describing... | Template |
|---|---|---|
| Business | How a business works, operational flows, strategy, market dynamics | references/business_model_template.yml |
| UI/UX | Screens, features, interaction flows, user experiences | references/ui_model_template.yml |
If the user is unsure, help them decide: "If your model is about how something works in the real world (business processes, revenue, teams), it's a business model. If it's about how someone uses a screen or feature, it's UI/UX."
3. Title Ask: "What is the title of this mental model?"
Examples: Business Environment, Login Workflow, Campaign & Event Lifecycle, Educator Mobile Experience
4. Guiding Questions Ask: "What questions should this model answer? (leave blank to let me infer from the source material)"
If provided, these questions shape the core_content sections. Each question becomes a section or is answered within one. If left blank, infer key questions from the source material and include them in the plan for user validation.
5. Model ID Ask: "What ID should this model have? (e.g., MM-003 or MM-UI-AUTH). Leave blank if unknown."
Convention: business models use MM-XX, UI models use MM-UI-XX.
6. Language Ask: "Language? (default: en-us)"
After gathering inputs, read the relevant template from references/ and present a plan to the user. Do NOT generate any files yet.
Business model → read references/business_model_template.yml
UI/UX model → read references/ui_model_template.yml
Show the user exactly what you intend to create. The plan must include:
MM-003-campaign-event-lifecycle.ymlsection_title you plan to create, with a one-line summary of what it coversopen_questions or assumptions)Format the plan like this:
## Plan: MM-003 Campaign & Event Lifecycle
**File:** MM-003-campaign-event-lifecycle.yml
**Scope:** How campaigns and events flow from client request through execution
and reporting. Excludes educator management and financial settlement.
**Sections:**
1. Campaign Structure — how campaigns relate to suppliers, budgets, and brands
2. Event Creation Flow — steps from request to published event
3. Event Execution — what happens on the ground during an event
4. Post-Event Reporting — data consolidation and client delivery
5. Cancellation & Exceptions — handling snowstorms, no-shows, mid-flight changes
**Gaps (will become assumptions or open questions):**
- No source material covers cancellation SLAs → Open Question
- Event pricing structure not detailed → Assumption
Wait for the user to approve, modify, or reject the plan before proceeding.
Once the plan is approved, generate the .yml file following these rules.
Follow the template structure exactly. Do not add or remove top-level fields. The templates in references/ define the schema.
Every points entry must be a factual statement grounded in the source material. If it's an inference rather than something the material states, move it to assumptions.
Do not invent information. If the source material doesn't cover something, it goes in assumptions (if you can make a reasonable inference) or becomes an open question in the plan summary. Never fabricate facts to fill sections.
Be concise. Points should be declarative statements, not paragraphs. Think bullet points, not essays. One idea per point.
Do not insert cross-references to other models inside content fields (e.g., (see MM-UI-005), (see models/ui/.../file.yml), (this belongs in MM-X)). Cross-model relationships belong only in the dependencies field. Content fields should read as self-contained statements.
YAML formatting:
| for multi-line strings (context field)- for list itemsRead references/business_model_template.yml before generating.
core_content sections should describe how things work in the real world, not how they should work in softwareimplications should focus on consequences for product/architecture decisionsRead references/ui_model_template.yml before generating.
core_content sections should be organized by screen or interaction flow"Elements: ..." — what's visible on the screen"Functionality: ..." — how it behaves"Assumption: ..." — inline assumption about this specific screen"Design principle: ..." — one-line design intentcontext should include the primary User Storyimplications should cover both frontend and backend consequencesAlways generate the dependencies field with placeholder values:
dependencies:
depends_on:
- "TBD — to be filled manually"
feeds_into:
- "TBD — to be filled manually"
The user fills this in because only they know the full graph of mental models.
/mnt/user-data/outputs/ with the naming convention: MM-[ID]-[title-kebab-case].ymlBefore delivering, verify:
core_content point is factual (inferences moved to assumptions)(see MM-X))assumptions is not empty (if it is, something is being hidden)dependencies has placeholder values for manual fillcontext explains WHY, not WHATkey_concepts only includes genuinely ambiguous termsimplications are actionable consequences, not restatements of contentcore_content or flagged as a gapCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub rafaeelricco/dotfiles --plugin mental-model-yml