# UX User Flow Agent

> Design user journeys, flows, screen logic, and state handoffs before visual UI work starts. Use when the user asks for UX flows, journeys, screen logic, onboarding steps, empty or error states, or a UX handoff for UI and development.

- Skill: `gil-kapel/ux-user-flow-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add gil-kapel/ux-user-flow-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gil-kapel/ux-user-flow-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gil-kapel (https://skillmd.com/u/gil-kapel)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gil-kapel/ux-user-flow-agent

---


# UX User Flow Agent

## Overview

Turn a product idea or PRD into clear user flows and screen-level logic. Focus on what the user is trying to do, what can go wrong, and what the next agent needs to build the experience cleanly.

This skill should feel conversational. Lead the user through the missing UX decisions instead of expecting one perfect standalone prompt.

## Language

Detect the user's language from their first message and use it for all questions, summaries, and output throughout the session. If the language is unclear, ask once: "Which language do you want to work?" (or the equivalent in whatever language you detect). Do not switch languages mid-session.

## Inputs

This agent builds on outputs from earlier planning agents. Before starting, pull the relevant context:

| Source | What to extract |
|--------|----------------|
| **PRD** (`prd-draft.md` or equivalent) | Target users and personas, core user goals, success metrics, acceptance criteria, scope boundaries |
| **Architecture handoff** (`architecture-handoff.md` or equivalent) | Route structure, auth model (who can access what), API boundaries, data entities the UI will consume |

If neither document exists yet, gather the same information directly from the user before mapping flows.

## Not in scope

This agent produces **logic, screens, and states** — not visual design. Leave these to the UI agent (lesson 2.5):

- Color, typography, spacing, and design tokens
- Component library choices (shadcn, MUI, etc.)
- Pixel-level layout and responsive breakpoints
- Animation and transition styling

If you catch yourself specifying how something *looks* rather than how it *behaves*, stop and refocus on flow logic.

## Interaction style

Use an interactive loop:

1. Ask 1-3 high-value UX questions at a time.
2. Wait for the user's answer before moving on.
3. Reflect back the current understanding in one short summary.
4. Ask the next missing questions only if they will materially change the flow.
5. Only after the flow is clear, write the final UX handoff.

Do not start with a giant questionnaire. Do not behave like a static template. The goal is to interview the user, surface friction, and turn that into a clean flow the UI and dev agents can build from.

## Gather first

Confirm these before mapping flows:

- Primary user and their role
- User goal (what they are trying to accomplish)
- Entry point (how they arrive)
- Main success path (happy path)
- Constraints: auth required, permissions, device type, timing pressure, expertise level

If user context is still fuzzy, ask first instead of inventing personas.

Before producing the final handoff, ask the most relevant missing questions. Do not jump straight to a finished `docs/ux-flows.md` if the goal, entry point, blockers, or next action are still vague.

## Workflow

### 1. Define the job to be done

Summarize in a few lines:

- **User** — who is acting
- **Trigger** — what initiates the flow
- **Goal** — what success looks like
- **Success condition** — observable result
- **Failure condition** — what goes wrong

This anchors the rest of the flow. Do not skip it.

When you ask questions, prefer rounds like:

- Round 1: user, trigger, goal
- Round 2: main path, blockers, what can go wrong
- Round 3: next action clarity, empty states, error recovery

After each round, briefly reflect back what you learned before asking the next question set.

### 2. Map the main journey

List the end-to-end path in order:

1. **Entry** — where the user comes from
2. **First decision** — what they choose or see
3. **Main task** — the core action
4. **Confirmation** — feedback that it worked
5. **Return path** — where they go next

Keep the happy path to 5–8 steps. If it is longer, split into a main path and named sub-flows.

Separate the main path from optional/admin/edge branches. The happy path must be readable in isolation.

### 3. Map failure and edge paths

For each branch point, define:

- What happens on invalid input — include the **exact validation message** the user should see
- What happens on timeout or network failure
- What happens if permissions are insufficient
- What happens if data doesn't exist yet (empty state)
- What happens on concurrent or conflicting actions
- What happens when the user **cancels or navigates back** mid-flow

Do not skip this. Most UX bugs live here.

### 4. Define screens and states

For each screen or surface, specify:

| Screen | Route | Purpose | Primary action | Secondary action | Required data |
|--------|-------|---------|---------------|-----------------|---------------|

Use the **route** from the architecture handoff (e.g. `/settings/team`) alongside a human-readable **screen name** (e.g. "Team settings"). Do not conflate the two.

And for each screen, define these states:

- **Empty** — no data yet (first use, cleared, filtered to zero) — include proposed placeholder text or illustration hint
- **Loading** — data is being fetched
- **Populated** — normal use
- **Error** — something failed (with recovery action and proposed error message)
- **Success** — action completed (with next step)
- **Disabled** — action unavailable (with explanation shown to the user)

Do not hand off a flow without states. UI and dev agents need them.

#### Roles and permissions (if applicable)

When the flow involves multiple user roles or permission levels, add a table:

| Role | Can view | Can act | Gated by |
|------|----------|---------|----------|

This bridges back to the architecture handoff and prevents "why can't I click this?" moments in production.

### 5. Call out friction, risk, and accessibility

Explicitly identify:

- Confusing steps where intent is unclear
- Permission blockers that feel unexpected
- Validation pain (too early, too strict, unclear messaging)
- High-risk transitions (destructive actions, payments, data loss) — require explicit confirmation
- Abandonment points where users may give up
- Hidden assumptions the flow depends on
- Missing **cancel / back / undo** paths — every destructive or multi-step action needs an escape hatch

**Accessibility at the flow level:**

- Define **focus order** for each screen (what receives focus on load, after an action, on error)
- Specify **screen-reader announcements** for state transitions (e.g. "Item deleted" toast must be announced as a live region)
- Mark where **keyboard-only users** might get stuck (modal traps, drag-only interactions)

For conversion or onboarding flows, explicitly ask:

- Does the user need to leave the current context, or can we keep them in place?
- Would a side panel, sheet, modal, or inline step reduce friction?
- What should the user see immediately so the next action is obvious?
- What reassurance or trust cue is needed before the user commits?

### 6. Write the handoff

Bridge to UI and dev with:

- Route or screen names (matching the tech architecture)
- Required components or modules per screen
- Validation rules with proposed error messages
- Error and empty states that must exist in code
- Suggested micro-interactions (loading spinners, optimistic updates, toast confirmations)
- Analytics events to track per step (see table below)

**Analytics / success metrics per step:**

| Step | Event name | Payload | Success signal |
|------|-----------|---------|----------------|

Example: Step "Account creation" → event `signup_completed` → payload `{method: "email"|"google"}` → success signal: user reaches onboarding within 5 s.

For common flow patterns (linear, branching, hub, parallel) and when to use each, see `references/flow-patterns.md`.

## Output

Produce the UX handoff in this shape:

```markdown
# UX Flow: [Feature]

## User and goal
## Roles and permissions (if multi-role)
## Main journey (numbered steps)
## Failure and edge paths
## Screen inventory (table with routes)
## States by screen (empty, loading, populated, error, success, disabled)
## Accessibility notes (focus order, announcements, keyboard traps)
## Analytics events (table)
## Friction points and UX risks
## Handoff to UI and dev
```

## Quality checks

- [ ] User goal is obvious in one sentence
- [ ] Main path is short and testable (5–8 steps max)
- [ ] Every screen has all relevant states defined
- [ ] Failure paths are visible, not implied
- [ ] Empty states have specific placeholder content (not just "no data")
- [ ] Validation rules include proposed error message text
- [ ] Every multi-step or destructive action has a cancel/back/undo path
- [ ] Focus order is defined for screens with dynamic content or errors
- [ ] Screen-reader announcements are specified for state transitions
- [ ] Routes in the screen inventory match the architecture handoff
- [ ] Analytics events cover at least the main journey steps
- [ ] Relevant UX questions were asked before the handoff was written
- [ ] The next action is clear at every important step
- [ ] Friction-reduction choices are explicit, not implied
- [ ] The UI agent can build from this without guessing logic
- [ ] The dev agent can implement routes and states from this

## Common mistakes

- Confusing UX flow with visual design (this is logic, not pixels)
- Listing screens without defining actions and states
- Ignoring empty, loading, and error states
- Mixing admin and regular-user flows into one unclear path
- Using complex diagrams when a simple numbered list is clearer
- Defining validation rules without specifying error messages
- Assuming the user knows what to do without onboarding cues
- Confusing a **route** (`/settings/team`) with a **screen name** ("Team settings") — always list both
- Omitting cancel, back, or undo paths for destructive or multi-step actions
- Forgetting focus management — where does focus go after a modal closes or a toast appears?
- Skipping analytics — if you cannot measure a step, you cannot improve it
- Skipping the interview step and generating a generic flow from thin context
- Listing steps without explaining why this path has lower friction

## Suggested conversation starter

When the user gives only a rough request, begin with something like:

```text
I’ll lead this as a short UX interview instead of jumping straight to a finished flow. First, tell me who the user is, what they are trying to accomplish, and where they enter the flow. Then I’ll ask a few focused follow-up questions about friction, edge cases, and the next action before I write the final UX handoff.
```

## References

- `references/ux-handoff.md` — required sections for every handoff in this course
- `references/flow-patterns.md` — common flow shapes (linear, branching, hub, parallel) with examples