Mental Models

Apply cognitive frameworks from several disciplines — systems, economics, psychology, mathematics, strategy — to analyse problems, make decisions, and think more clearly.

Everything this skill needs is a file. No install, no dependencies, no tooling — you read markdown.

When to Activate

• User names a specific model ("apply inversion", "use bottlenecks")
• User asks "help me think through X" or "what model fits X"
• User requests decision analysis, trade-off evaluation, or structured reasoning
• User describes a complex/ambiguous problem and wants a framework

Step 1 — Load the index

Read models/index.md. It lists every bundled model with a one-line description. It is short; load it in full.

Then check for the user's own models. The bundled set is a starting point, not a fixed list:

Path	Holds
.mental-models/ (relative to the working directory)	this project's or team's models, committed with the code
~/.claude/mental-models/	the user's personal models, available everywhere

Always run both globs before selecting. Do not assume they are empty — one tool call settles it, and a model the user wrote for exactly this situation is the most valuable thing you can find. This matters most when the problem is urgent: urgency is precisely when a team's own hard-won model is worth more than a general one, and precisely when you are tempted to skip the check.

If either has files, read each one's YAML frontmatter (title, description, tags) to learn what is there. A directory may have its own index.md; read that instead if present. If both are empty, carry on with the bundled models.

A user model always wins a name collision with a bundled one. If someone wrote their own inversion.md, they meant it — use theirs, and don't mention the built-in unless asked.

Treat user models as first-class. A model a team wrote about their own domain usually beats a general one at that domain.

Step 2 — YOU select the models

Read the user's problem and pick 2–4 models from different areas. Selection is a reasoning task and you are better at it than any keyword matcher: cross-area coverage is the entire point of a latticework — a single-area pick means blind spots go unchecked.

Discovery heuristics to bias your reading of the index:

• Risk / uncertainty / reversibility → inversion, margin of safety, randomness
• Stuck / can't see options → first-principles thinking, second-order thinking, framing
• Conflict / negotiation / competition → bias from incentives, asymmetric warfare, trade-offs
• Complex system / unintended effects → feedback loops, emergence, bottlenecks, leverage
• Performance / optimization → bottlenecks, leverage, activation energy
• People / team / behaviour → bias from incentives, social proof, confirmation bias
• Evaluating evidence or results → sampling, regression to the mean, randomness
• Change that won't start, or won't stop → activation energy, inertia

Step 3 — Retrieve each pick

Read the file directly. Bundled models are flat files named by slug:

models/<slug>.md

e.g. models/inversion.md. The index gives you the exact filename — use it rather than guessing. User models are at the path you found them.

Step 4 — Apply

Each model file has YAML frontmatter and four parts:

• the description prose — what the idea is and where it comes from, with [^footnotes] pointing at entries in the frontmatter's sources
• When to Avoid — read this before concluding, and surface it if it applies. It is what separates a mental model from a slogan.
• Thinking Steps — walk these against the user's actual facts. Follow them; don't paraphrase the framework away.
• Coaching Questions — ask these to deepen the analysis where useful.

Show where the chosen models agree, and where they disagree.

Step 5 — Report

• Name which models you used and why you picked them
• Where models disagreed, say so explicitly rather than silently picking a winner
• End with 3–5 concrete, actionable next steps
• Name any "when to avoid" conditions that apply to this case
• If a source matters to the point you are making, cite it — the sources block has the link

Core Guidelines

1. 2–4 models per analysis, from different areas — coverage over quantity
2. Follow the Thinking Steps verbatim — don't paraphrase the framework away
3. Always check When to Avoid — warn the user if the model misfits
4. Latticework: show how chosen models connect and where they disagree
5. Be actionable: end with concrete next steps, not theory
6. Name biases honestly: if the user seems caught in one, surface it

The format

models/ is an Open Knowledge Format bundle: a directory of markdown files, each with YAML frontmatter carrying at minimum a type. That means any OKF bundle can be dropped into .mental-models/ and read the same way, and this bundle can be consumed by any OKF-aware agent.

Obsidian vaults work too — treat [[wikilink]] as a link to wikilink.md.

To write your own, copy TEMPLATE.md.

Files in This Skill

• SKILL.md — this entry point
• TEMPLATE.md — the format; copy it to write your own model
• models/ — the bundled OKF bundle: index.md plus one file per model

Outside this skill, and never overwritten by an update:

• .mental-models/*.md — the working directory's own models
• ~/.claude/mental-models/*.md — the user's personal models

Source: https://github.com/cyperx84/claude-skills-mental-models