ghost-users
Skill2 starsChanged yesterdayMITView on GitHub
Simulate 3-5 realistic personas walking through a product, doc or flow, report where each gets stuck, confused or leaves, then fix the worst issues. Use before shipping anything people must use or read without the author present (onboarding, README, landing page, form, CLI, API docs, email), or when the user says "how will users react", "walk through this as a user", "ghost users" or "where will people get stuck".
In this repository17 other files it gives its agents.
- autopilotSkill
- autopsySkill
- confidence-mapSkill
- delegateSkill
- expert-askSkill
- failure-museumSkill
- grill-dumpSkill
- intent-diffSkill
- md-to-mapSkill
- mind-mapSkill
- premortemSkill
- red-teamSkill
- shipitSkill
- stuck-detectorSkill
- taste-thiefSkill
- tournamentSkill
- workSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Every issue quotes the exact text or element that caused it, and says where it is.
≈ “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
Ghost Users
The author cannot see their own work as a stranger does. Send in ghosts who know only what is on the page, and let them fail where real people would.
Scale
- Skip for internal throwaway work, and when the only reader is one expert in the conversation (ask them instead).
- Light: 2 personas (the newcomer and the person in a hurry), first screen or first 5 steps only.
- Full: 3-5 personas, the whole flow.
Hard rules
- Personas come from the real audience of this thing, not a stock list. If the audience is unknown, say so and state the assumed one.
- Each persona has a goal, a context (device, time, mood), what they already know, and a patience budget (for example "leaves after 2 unexplained terms", "gives up after 30 seconds without progress").
- At least one persona must not fit the author's assumptions: wrong device, wrong prior knowledge, arrived mid-flow, or sceptical of the claim.
- A ghost knows only what is on the page. No author knowledge, and no reading the source to work out what a button does.
- Walk literally, step by step, in order, reading the actual words and elements. Do not skim to the intent.
- Every issue quotes the exact text or element that caused it, and says where it is.
- Outcomes are exactly: STUCK (cannot proceed), CONFUSED (proceeds unsure or wrongly), LEFT (patience spent), DONE.
- A persona who sails through is a valid result. Do not invent friction.
- These are hypotheses, not user research. Say so in one line and never write "users will".
Process
- State the thing and the one action it wants from people.
- Cast 3-5 personas, one line each: who, goal, knows, patience.
- Walk each persona. Per step record sees / thinks / does. For short text a step is a sentence. Stop that persona at the first STUCK or LEFT.
- Collect issues, merge duplicates, rank by personas hit x severity (LEFT > STUCK > CONFUSED).
- Fix the top 3, or every LEFT and STUCK if there are more. Prefer removing the cause over annotating it. Show the revised text or element, not just a description.
- Re-walk only the changed steps, with the personas that failed there.
- Report.
Output format
GHOST USERS: <thing> · wants people to <one action>
Cast
- <persona>: goal <..> · knows <..> · patience <..>
| # | Where | Quote | Who | Outcome | Fix |
|---|-------|-------|-----|---------|-----|
| 1 | <step or section> | "<exact text>" | <persona> | STUCK | <change made or proposed> |
Re-walk: <persona> now <outcome>
Hypotheses, not research. Worth testing with a real person: <the one thing>.Anti-patterns
- Personas that are demographics ("Sarah, 34, marketing") with no goal or patience budget.
- Personas chosen to be easy so that all finish happily, or all failing identically. (Sailing through is valid only for a persona who really fits the page.)
- The ghost using knowledge the page never gave.
- "Users may find this confusing" with no quote.
- Five personas all hitting the same single issue, reported five times.
- Fixing by adding explanatory text everywhere instead of removing the cause.
- Hunting logic or edge-case breaks in the work itself: that is
red-team.
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.

