# Improve User Experience > Find bridging opportunities in a product, informed by the intended experience in EXPERIENCE.md and the domain language in CONTEXT.md. Use when the user wants to improve UX, reduce friction in a flow, find where users get stuck or confused, close the gap between what the product does and what it should feel like, or add purposeful delight (micro-interactions, celebrations, empathetic errors) to a flow. - Skill: `jcaraballo113/improve-user-experience` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add jcaraballo113/improve-user-experience` - Raw SKILL.md: https://api.skillmd.com/api/skills/jcaraballo113/improve-user-experience/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: JCaraballo113 (https://skillmd.com/u/jcaraballo113) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/jcaraballo113/improve-user-experience --- # Improve User Experience Surface experiential friction and propose **bridging opportunities** — changes that close a **gulf** the user currently has to cross on their own. The aim is a product where a first-time user can form the right intention and confirm the result without help. ## Required tooling Design is how this skill models experience, and it holds that design to a quality bar — so two dependencies are **required**, not optional: - **Pencil MCP** — the `.pen` design editor. Every read of the designed experience and every bridge you produce goes through it. - **`impeccable` skill** — the visual-craft bar every bridge design is held to. Layered on top of the design, never a substitute for closing the gulf. **Preflight before any design work.** If the Pencil MCP tools aren't connected or the `impeccable` skill isn't installed, **stop and ask the user to install/connect them** (install commands in [skill.deps.json](./skill.deps.json)) before continuing — do not fall back to hand-drawn mockups or unpolished designs. (A missing `.pen` *file* in the project is fine — that's a project state, not a missing dependency; you'll create one in phase 3.) ## Glossary Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "confusing," "clunky," "intuitive," or "clean." Full definitions in [LANGUAGE.md](LANGUAGE.md). - **Job** — what the user is trying to accomplish, in their terms and outcome ("get a refund for a late order"), not the feature or screen. - **Gulf of Execution** — the distance between the user's intention and the actions the interface offers. Felt as "how do I do this?" - **Gulf of Evaluation** — the distance between the system's actual state and the user's ability to perceive and interpret it. Felt as "did that work? what now?" - **Signifier** — a perceptible cue announcing that an action is possible, and where. Distinct from the affordance it advertises. - **Affordance** — an action the interface actually permits. - **Feedback** — the system's perceptible response confirming what an action did and what state resulted. - **Conceptual model** — the model of how the system works that the design projects, and the one the user forms. Good UX makes them match. - **Friction** — effort, decisions, waiting, or steps the user spends that don't advance the Job. The quantity being reduced. - **Bridge** — a design change that closes a gulf so the user no longer crosses it themselves. The verb of this skill. This skill is _informed_ by the project's intended experience. `EXPERIENCE.md` is the human-owned **glossary of the experience** — Jobs, flows, and feels — that mirrors `CONTEXT.md` (which names the domain). It is the bar: the skill finds where the built experience falls short of the intended one, and never edits `EXPERIENCE.md` without explicit human approval — it is the source of truth code conforms to, not the reverse. What graduates into `EXPERIENCE.md`, into `CONTEXT.md`, or into a **design decision record** ([DECISION-RECORD.md](DECISION-RECORD.md)) — and in what format — is spelled out in phase 3's side effects. ## Process ### 1. Explore Read `EXPERIENCE.md` in full and the relevant `CONTEXT.md` domain terms first. They are the intended experience and the names for it — the bar you're measuring against. **The design is the second source of the bar.** `EXPERIENCE.md` states the intended experience; the `.pen` design *shows* it. Open it with Pencil — call `get_editor_state({ include_schema: true })` first (`.pen` files are encrypted: Pencil tools only, never Read or Grep), then read the designed flow with `batch_get` and capture frames with `get_screenshot` / `export_nodes` so the report can show the real designed experience, not a hand-drawn approximation. This unlocks a gulf source the prose misses: **drift between the designed experience and the built one** — where implementation quietly diverged from the design is often where the richest gulfs hide. If the project has no `.pen` design *yet*, there's nothing to compare against — work from `EXPERIENCE.md` plus the built app, and you'll create the design in phase 3. Then walk the actual user flows in the area you're touching. Prefer **driving the running app** so you feel the friction yourself — start it however this project runs and move through the flow as a first-time user (browser automation, where available, lets a sub-agent walk it for you). When the app isn't runnable, trace the flow through the code with the Agent tool. Don't follow rigid heuristics — move through the product organically and note where you experience friction: - Where does the user have to guess **how** to start a Job — no signifier for the affordance that does it? (execution gulf) - Where does the user act and get no **feedback** — can't tell if it worked or what state they're now in? (evaluation gulf) - Where does the product's **conceptual model** contradict what the user already believes, forcing them to relearn it? - Where does a Job take more **friction** — steps, decisions, waiting — than the value it returns? - Where does an error leave the user stranded with no next action? - Where does the layout itself tax the Job — a frequent action rendered small or far from the user's attention (Fitts' Law), or one needed choice buried among many (Hick's Law)? (friction) - Where does the **built** screen diverge from the **designed** one in the `.pen` — a gulf introduced by drift, not by the design? Apply the **hesitation test** at every step: would a first-time user pause to ask "how do I do this?" or "did that work?" Each pause is a candidate. Confirm the gulf is real (a pattern, not one imagined user) before proposing a bridge. ### 2. Present candidates as an HTML report Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `/ux-review-.html` so each run gets a fresh file. Open it for the user — `xdg-open ` on Linux, `open ` on macOS, `start ` on Windows — and tell them the absolute path. Each candidate gets a card with a **before/after visualisation** and a recommendation-strength badge; the report ends with a **Top recommendation** section. The full scaffold, candidate-card fields, diagram patterns, and styling live in [JOURNEY-REPORT.md](JOURNEY-REPORT.md) — follow it. **Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the experience.** Talk about "the Job: return an item" and "the execution gulf at the payment step" — not "the confusing button" or "the bad onboarding." **EXPERIENCE.md conflicts**: if a candidate contradicts the documented intended experience, only surface it when the friction is real enough to warrant revisiting that intent. Mark it clearly in the card (e.g. a warning callout: _"contradicts EXPERIENCE.md §Onboarding — but worth reopening because…"_). Don't list every theoretical change the doc rules out. Do NOT design the bridge in detail yet. After the file is written, ask the user: "Which of these would you like to explore?" ### 3. Grilling loop Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — the user's Job, exactly where the gulf opens, the shape of the bridge, which signifier or feedback or model change closes it, and which states the bridge must cover — empty, loading, error, success, plus the two most-forgotten: the **precondition already satisfied** (the step is a no-op this time — don't render it as pending) and the **action in flight** (show motion, not a static label). **Model the bridge in Pencil, held to `impeccable`'s bar — don't describe it in prose.** Experience is designed, not specified — once the bridge's shape is settled, build it as an actual `.pen` design (`batch_design` against the schema from `get_editor_state`), covering every state the grilling surfaced. Layer `impeccable` over the design for visual hierarchy, motion, accessibility, and edge states, so the bridge ships polished, not merely functional. Where the bridge's feedback moments can carry personality — acknowledgments, gestures, celebrations, waits, errors — hold them to [DELIGHT.md](DELIGHT.md). Then show the user a `get_screenshot` (one taken immediately after a large `batch_design` can render stale — re-take if it comes back empty). The deliverable is two things: the approved `.pen` design — the spec whatever implements designs in the project builds from — **and** a **design decision record** ([DECISION-RECORD.md](DECISION-RECORD.md)). Implementation is out of scope. When several bridge shapes are in play, design them as separate variants — see [BRIDGE-DESIGN.md](BRIDGE-DESIGN.md) for the design-the-bridge-twice pattern (parallel sub-agents, real `.pen` frames, not written specs). Side effects happen inline as decisions crystallize: - **Surfaced a genuinely new _domain noun_ (a thing the business has — an Order, a Cart, a Subscription)?** Add it to `CONTEXT.md` — the shared domain glossary — as a one-line entry: the term, then a sentence defining it in the domain's own words. Create the file lazily if it doesn't exist. This is the _only_ reason a UX session touches `CONTEXT.md`. - **Named a new _experience term_ (a Job, a flow, a state, a feel)?** Add it to `EXPERIENCE.md`, mirroring `CONTEXT.md`'s glossary format (`**Term**:` → a one- or two-sentence definition of what it IS → optional `_Avoid_`), grouped under Jobs / Flows & states / Feel. Never decisions or implementation. Human-approved, like any `EXPERIENCE.md` edit. - **Chose a bridge — or set one aside with a load-bearing reason?** That's a decision, not vocabulary. Record it as a **design decision record** in `designs/decisions/NNNN-slug.md`, co-located with the `.pen` ([DECISION-RECORD.md](DECISION-RECORD.md)): the chosen bridge, the alternatives considered and why they lost (so a future review doesn't re-suggest them), and the behaviour the bridge commits the product to. This — not `EXPERIENCE.md` — is where "we considered X and set it aside" lives. Only the reusable _vocabulary_ a decision introduces (a named state like "Armed") graduates into the `EXPERIENCE.md` glossary. See [BRIDGING.md](BRIDGING.md) for how to close a gulf safely given its type — execution vs evaluation tactics, and why a bridge removes the gulf rather than papering over it with help text.