ux-flow-auditor
Traces user task flows with Playwright: click depth, step success, friction: and writes reports to .heyeddi/docs/ux-flows/. Use when measuring ease of use, clicks to complete a task, or onboarding friction. Not for static visual critique (use heyeddi-design critique) or layout screenshots (use visual-auditor).
How do I install this agent skill?
npx skills add https://github.com/heyeddi-com/heyeddi-skills --skill ux-flow-auditorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a UX auditing tool that uses Playwright to automate browser interactions for task flow analysis. It follows security best practices, including safe subprocess execution and localized file system operations.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
UX Flow Auditor
Task-oriented UX: how many clicks to achieve a goal, where users get stuck.
All artifacts go under .heyeddi/docs/ and .heyeddi/audits/: never repo root.
Cross-pillar sync (mandatory)
Read reference/cross-pillar-handoff.md. Bookend every flow trace:
@heyeddi load_workflow_context --route /path
trace_flow …
update ux-flows report + friction notes
@heyeddi append_pillar_opinion --pillar ux …
→ @heyeddi-product updates AC if needed; @heyeddi-design notes layout friction
When to use
- "How many clicks to update settings?"
- Post-ship ease-of-use check
- Compare desktop vs mobile flow (separate flow JSON or viewport)
- Product acceptance: task completes within click budget
Subagents (default)
See reference/subagents.md. Run trace_flow.py via Task shell (needs dev server + Playwright).
Pipeline
init_ux_flows → ux-flows.md index + example .flow.json
define steps in ux-flows/<task>.flow.json
trace_flow --task-id → ux-flows/<task>.md + audit screenshot
agent adds friction notes to report
Instructions
- Ensure
.heyeddi/product.mddefines user tasks (optional context). python scripts/init_ux_flows.py --project-root <root>once per project.- Add or edit
.heyeddi/docs/ux-flows/<task-id>.flow.jsonwith steps (expect,fill,click). - Start dev server; set
DEV_SERVER_URLif nothttp://localhost:5173. python scripts/trace_flow.py --task-id <id> --project-root <root> --check- Append Friction notes to the generated markdown report.
Flow JSON schema
{
"task_id": "update-profile",
"goal": "User saves profile",
"start_route": "/settings",
"max_clicks": 4,
"viewport_width": 1440,
"steps": [
{ "action": "expect", "selector": ".settings .p-inputtext", "label": "Form visible" },
{ "action": "fill", "selector": ".settings input >> nth=0", "value": "Alex", "label": "Name" },
{ "action": "click", "selector": "button:has-text('Save')", "label": "Save" }
]
}
.heyeddi/ outputs
| Path | Purpose |
|---|---|
.heyeddi/docs/ux-flows.md | Index of tasks, budgets, last run |
.heyeddi/docs/ux-flows/<task>.flow.json | Machine-readable steps |
.heyeddi/docs/ux-flows/<task>.md | Human report + friction notes |
.heyeddi/audits/ux-flow/ | Step screenshots |
Chain
- After
@heyeddi-handoff/@heyeddi-design: verify tasks are completable @visual-auditor: layout proof; this skill: interaction proof@engineering-excellence: separate concern (code structure)
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/heyeddi-com/heyeddi-skills/ux-flow-auditor">View ux-flow-auditor on skillZs</a>