ux-flows
Catalog + orchestrator for a web application's usage (E2E) flows. Keeps the project's flow definitions and hands them, ONE at a time, to the `ux-persona` skill to validate usability in the browser. Use to "list the flows", "validate all flows as a user", "run the usability walkthrough", "create a new usage flow", or run flow walkthroughs with Webwright-style replayable evidence.
How do I install this agent skill?
npx skills add https://github.com/djalmajr/skills --skill ux-flowsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill orchestrates user experience (UX) flows by reading project documentation and source code to generate test scenarios. It presents a minor risk of indirect prompt injection due to its ingestion of untrusted local project data.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
ux-flows — usage-flow catalog and orchestration
This skill is the source of truth for a project's usage flows and the conductor that hands them to the persona. It separates the what (the flows, which are project data) from the how (the usability walkthrough, in the ux-persona skill). It is stack-agnostic: no hardcoded ports/addresses — each flow declares its own entry point.
Project root
This skill writes the flow catalog (e2e/flows/) and personas (e2e/personas/) at paths relative to the project root (the repo where the work happens), not the agent's current working directory.
- If invoked from inside the project, use the relative paths shown in this skill.
- If invoked from another directory (e.g., a sibling repo), prepend
<project-root>/to every path. - When the project root is ambiguous, confirm with the user via the harness question tool before writing.
Prompting
Follow the project-wide convention in CLAUDE.md / AGENTS.md ("Skill Prompting Conventions"). Use the harness's structured-question tool — AskUserQuestion (Claude Code), ask_user_question (Codex), or question (OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.
| Decision point | Why structured | Suggested options |
|---|---|---|
Next action after list | Branches the run | run one flow · run all · new flow · discover |
| Flow to run (short catalog) | Picks from a known list | the catalog flow ids, up to 4 |
| Confirm discovered drafts before running | Writes the catalog the user owns | accept all · trim first · cancel |
Free-form prompts (no structured tool):
- New flow goal, persona, and design reference
- Corrections to discovered steps
No-pause mode: if the user has explicitly disabled mid-skill clarification, or the skill runs as a delegated, non-interactive agent with nobody to ask, write discovered drafts as proposals, skip the run, and list them for review in the summary.
Where flows live
Convention: one file per flow at e2e/flows/<id>.md in the project, version-controlled. Template:
---
id: <kebab-id>
name: <readable name>
reference: <optional: requirement / ticket>
persona: <id of e2e/personas/<persona>.md, or a bundled ux-persona persona>
entry: "<entry-point URL — typically the app's home/landing>"
preconditions:
- <app running at the entry point>
- <minimal data required>
design_refs: # optional but recommended: the planned design per screen
<screen-key>: "<Figma node URL / exported image / spec — the source of truth for that screen>"
---
## User goal
<what the person wants to achieve, in one sentence>
## Steps (each step is a UI ACTION + the expected result)
1. At the entry point (`<screen-key>`), **<UI action>** → <expected result>.
2. (`<screen-key>`) **<UI action>** → <expected result>.
## Expected result
<the final observable state that proves success>
Modeling rule: every flow starts at the entry point (the home/landing) and describes UI actions (click/fill), never "go to URL X". That is what lets the persona flag screens unreachable by navigation. When a screen has a planned design, list it in
design_refsso the persona validates the coded screen against the prototype (design fidelity), not only its usability.
Commands (via $ARGUMENTS)
- empty or
list→ list the project's flows (id · name · persona · reference) and offer to run. If the catalog is empty or missing, rundiscoverfirst (see below) — never just report "no flows". <flow-id>→ run one flow: invoke theux-personaskill with the flow file's path.all→ run all, sequentially (the browser is a single resource — never in parallel): for each flow, invokeux-personaand wait for its report before the next. If the catalog is empty,discoverfirst (confirm the drafts), then run.new→ help author one flow: ask for goal/persona/reference, discover the entry point and the real UI steps (explore the project's routes/screens if needed), and writee2e/flows/<id>.mdusing the template above.discover→ survey the application and bootstrap the catalog when there are no flows yet (see Discovery below).
Discovery — bootstrapping an empty catalog
The catalog presupposes the e2e/flows/ convention, but a project may start with nothing. When there are no flows (or the user asks to discover), survey the app yourself and propose the initial catalog — don't make the user write it from scratch. This is stack-agnostic; combine whatever signals exist:
- Map the screens/routes. Inspect the codebase for the router (route definitions, a
routes//pages//app/directory, a sitemap, or a route manifest) to enumerate the reachable screens and the entry point (home/landing). Frameworks differ — search for the project's routing mechanism rather than assuming one. - Read the navigation. From the entry point (in the running app, or from the landing component), see which actions are actually exposed to the user — this is what separates a reachable journey from an orphan screen.
- Mine intent. Use product/requirements docs, READMEs, route/screen names, and primary CTAs to infer the user goals (e.g., "sign up", "search and view an item", "check an order's status", "complete a purchase"). One goal = one flow.
- Group by persona. Assign each flow a fitting persona (a bundled one, or a project persona). Different audiences (end user vs. back-office/admin) usually warrant different personas.
- Draft the catalog. Write one
e2e/flows/<id>.mdper goal using the template, with steps expressed as UI actions from the entry point. Create any needede2e/personas/<id>.md. - Confirm before running. Present the proposed flows (id · name · persona · entry · #steps) for the user to review/trim/correct. Discovery proposes; the user owns the catalog.
Discovery is best-effort: when a flow's UI path is unclear from code alone, note the assumption in the draft so the persona run (and the human) can confirm or refute it. A surveyed-but-unconfirmed flow is still better than no catalog.
Orchestration (run = dispatch to the persona)
- Single pre-check: is the app running at the flows' entry points? If not, start it via the project's run command, or report and stop. Is minimal data seeded?
- For each selected flow, call the
ux-personaskill with the flow file's path. Sequential — wait for one report before the next. - At the end, consolidate: read the reports produced this round (
e2e/usability/) and produce a scoreboard — per flow: verdict + number of findings per severity — and a prioritized list of usability fixes (blockers first), pointing to the screen/reference of each.
Webwright-backed runs
If the user asks for Webwright, replayable evidence, generated browser scripts,
or stronger screenshot/action logs, still keep this skill as the catalog
orchestrator and still dispatch each flow to ux-persona. Tell ux-persona to
use Webwright as its execution backend for that flow.
Do not replace e2e/flows/*.md with Webwright scripts. The flow definition
remains the source of truth; Webwright final_runs/run_<id>/ artifacts are
supporting evidence for the generated e2e/usability/<flow-id>--<date>.md
report. Native Playwright E2E remains the place for durable CI regressions.
Catalog maintenance
- When a new journey/screen appears, create the matching
e2e/flows/<id>.md. - When a usability fix is made, re-run the affected flow to confirm the finding is gone (UX regression).
- The reports in
e2e/usability/are the history — don't delete them; each round produces a new, dated one.
Recommended project layout
e2e/
personas/<persona>.md # reusable project personas (the persona's lens)
flows/<id>.md # one file per flow (the definition handed to the persona)
usability/<id>--<date>.md # findings reports (generated by runs)
Personas can also be the common ones bundled with the ux-persona skill (novice, rushed, skeptical, mobile, accessibility, power-user).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/djalmajr/skills/ux-flows">View ux-flows on skillZs</a>