empathy-map
Skill11 starsChanged 10 days agoMITView on GitHub
Map user feelings, thoughts, sayings, and doings from observation data into an empathy quadrant canvas. Use when the user says "map out the user experience", "what are users thinking", "build an empathy map", or invokes /empathy-map before designing a feature.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- fzfclee/consulting-skillstheir own version, first seen Oct 13, 2026
- miovrag/claude-skillstheir own version, first seen Jun 12, 2026
- launchapp-dev/animus-clitheir own version, first seen Mar 15, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- launchapp-dev/animus-cli★ 39same name
- fzfclee/consulting-skills★ 6same name
- miovrag/claude-skills★ 1same name
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 repository44 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- analyze-dataSkill
- brainstormingSkill
- craft-lessonSkill
- create-agentSkill
- create-skillSkill
- customize-agentSkill
- customize-skillSkill
- designSkill
- deslopSkill
- developSkill
- discovery-reportSkill
- elicitationSkill
- explore-ideaSkill
- grill-meSkill
- help-meSkill
- humanizeSkill
- incidentSkill
- iterateSkill
- journey-mapSkill
- jtbdSkill
- kanbanSkill
- launchSkill
- legal-safety-auditSkill
- maintenance-executeSkill
- maintenance-planSkill
- memorySkill
- motionSkill
- phaseSkill
- planSkill
- research-planSkill
- retroSkill
- reviewSkill
- root-causeSkill
- round-tableSkill
- shape-upSkill
- shut-upSkill
- statusSkill
- teach-meSkill
- testSkill
- unpack-problemSkill
- validate-ideaSkill
- validation-patternsSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
After user interviews — synthesize observations
- Distinctive: line 22
Before designing any feature
- Very specific: line 99
Run this before the complete call below, so a non-conformant canvas is never recorded as delivered.
- Very specific: line 101
Empathy-map minimums: all four quadrants populated.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Empathy Map
What this skill does
Structures user observations into an empathy canvas. Outputs to artifacts/output/02-research/empathy-map.md.
Persona delegation
This skill delegates to @user-researcher. The researcher facilitates empathy mapping from user data. The skill provides the canvas; @user-researcher provides the user insight and synthesis.
When to use
- "Help me understand what users are thinking"
- "Map out the user's experience for {scenario}"
- After user interviews — synthesize observations
- Before designing any feature
Workflow
Step 1: Define the user and scenario
Identify the specific user segment and the scenario/context you're mapping.
Step 2: Populate 4 quadrants
Work through each quadrant interactively:
Says — What does the user verbalize? Direct quotes from interviews, support tickets, reviews. Thinks — What does the user not say aloud? Inferred from behavior, hesitations, body language. Does — Observable behaviors. What actions do they take? What workarounds do they use? Feels — Emotional state. Frustrated? Anxious? Relieved? Confident? Map the emotional arc.
Step 3: Identify pains and gains
- Pains: What frustrates, blocks, or annoys the user?
- Gains: What would delight, relieve, or empower the user?
Step 4: Output
Write artifacts/output/02-research/empathy-map.md:
# Empathy Map — {user segment} in {scenario}
**Date:** YYYY-MM-DD
**Evidence basis:** {interviewed N / observed / analytics / support-tickets / survey / hypothesis — pick one, and label unvalidated content in the body}
**Inferred quadrants:** {which of Thinks / Feels are your inference rather than their words — usually both}
## User & Scenario
- **Segment:** {who specifically — role plus what distinguishes them: size, tool, constraint, tenure}
- **Scenario:** {the actual moment: when, doing what, with what at stake}
## Empathy Canvas
| Says | Thinks |
|------|--------|
| {direct quotes} | {inferred thoughts} |
| Does | Feels |
|------|-------|
| {observed behaviors} | {emotional states} |
## Pains
1. {pain point} — {severity: high/medium/low, or how many users hit it}
## Gains
1. {opportunity for delight}Done when — checked mechanically
These canvases shipped for the whole life of this repo with no gate at all: the template in the
Output step could be written to disk verbatim and nothing would notice. discovery_canvas_check.js
now checks form and evidence declaration:
node .agents/scripts/discovery_canvas_check.js check --kind empathy-map --file artifacts/output/02-research/empathy-map.md --jsonIt requires:
- no unfilled template placeholders —
{direct quotes}and{pain point}are the template, not an artifact **Evidence basis:**declared — one ofinterviewed/observed/analytics/support-tickets/survey/hypothesis. A canvas that does not say where it came from cannot be read as research, and nothing downstream can tell your finding from your guess- when the basis is
hypothesis, the body must say so too — announced only in a header, a hypothesis reads as a finding three paragraphs later - the kind's structural minimum, below
A green result is not a research finding. The gate checks form and one declaration. It cannot tell you whether the analysis is correct, and it does not pretend to.
Exit 0 conformant · 1 failures · 2 usage/IO error, fail-closed, never a silent pass.
Run this before the complete call below, so a non-conformant canvas is never recorded as
delivered.
Empathy-map minimums: all four quadrants populated; the Says quadrant carrying quoted material or
a source link — if there was no interview, declare the basis as a hypothesis rather than writing a
plausible paraphrase and presenting it as something a person said; non-empty Pains and Gains.
Four defects the first version of this gate missed
Re-audited after the gate shipped. A canvas that passes every check above can still be dishonest and still be useless downstream. Each of these greened a map that should not have:
| Defect | What is now required |
The canvas erases the distinction this skill itself draws. Step 2 defines Says as what the user verbalises and Thinks as what they do not say aloud, inferred — then renders all four quadrants as one table with identical formatting. A quoted sentence and your imagination of what someone felt are indistinguishable to the reader | **Inferred quadrants:** naming which quadrants are inference. This asks for a label, not new content — it requires labelling what you already know is an inference |
Segment: admins, Scenario: general is not a persona. A role name with nothing distinguishing it describes a population, and every downstream decision inherits the vagueness | The segment must carry enough to tell this user from the neighbouring one; the scenario must name a moment. general, whenever, various and friends are rejected as standing in for having one |
interviewed 1 was a full segment map. The basis is now required to state its count. A count below five is a named limit, not a failure — printed as a caveat on both the pass and fail paths, and carried in the JSON | The interviews already happened; failing on a small N would only push an author to misstate the number, which is strictly worse |
| Four pains, no order of importance. A numbered list is document order, not priority — it hands the decision of what to fix to whoever reads it first | Each pain carries a severity, frequency, or priority marker |
What this gate still cannot do: judge whether an inference is correct, or whether the pain you ranked highest is the one that matters. It checks that the map tells the truth about its own provenance. Judging the analysis is a researcher's job.
State machine integration
At start: Run node .agents/scripts/orchestrator_state.js status
At end: Run node .agents/scripts/orchestrator_state.js complete --agent user-researcher --artifact 02-research/empathy-map.md
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.

