# Audit Ux And Save Files > Use if auditing a running app's usability via persona journeys, saving per-issue findings to a tree. - **Type:** Skill - **Install:** `agentstack add skill-yigitkonur-skills-by-yigitkonur-audit-ux-and-save-files` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [yigitkonur](https://agentstack.voostack.com/s/yigitkonur) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [yigitkonur](https://github.com/yigitkonur) - **Source:** https://github.com/yigitkonur/skills-by-yigitkonur/tree/main/plugins/audit-ux-and-save-files/skills/audit-ux-and-save-files ## Install ```sh agentstack add skill-yigitkonur-skills-by-yigitkonur-audit-ux-and-save-files ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Audit UX and Save Files Disciplined **usability** evaluation of a running app, from the perspective of the people who actually use it — not a frontend pass. The deliverable is a durable on-disk artifact of usability problems and a prioritized list of the **major changes** they imply. Dispatch parallel audit subagents that each **embody one persona** plus a UX expert's eye, drive the `run-agent-browser` skill through that persona's core **journeys**, capture screenshots at the moments friction appears, and write one markdown finding per real usability problem into a **dated, persona-scoped, journey-scoped tree** under `ux-findings/`. When the audit returns, cluster findings into UX themes, then synthesize a prioritized **recommendations** report. This skill **reports; it does not fix.** This is not "make it look nicer." The questions are: *Can this persona accomplish their goal? Where do they hesitate, misread, backtrack, or give up? What is confusing, redundant, or unnecessary? What one change would help most?* Findings are judged by task impact and business consequence, not by pixels. The skill owns three things: where files live, how usability findings are written (persona · journey · heuristic · severity · behavioral + business impact · recommended major change), and how the audit is synthesized into recommendations. It does NOT own visual/CSS correctness (that is `audit-ui-and-save-files`) and does NOT implement the recommendations. ## When to Use Trigger on phrases and contexts like: - *"audit the UX"*, *"run a usability audit"*, *"is this actually usable?"* - *"where do users get confused / stuck / drop off?"*, *"find the friction"* - *"evaluate it as different personas"*, *"walk a first-time user / power user / buyer through it"* - *"do a heuristic evaluation of the app"*, *"Nielsen-audit the flows"* - *"what's confusing here, what should we simplify or remove?"* - *"the feature works — but is it understandable? write up the usability problems for me"* - *"screenshot the journeys, find the usability issues, and recommend the big changes"* Do NOT use this skill for: - *Visual / CSS / layout / responsive bugs.* "The card overflows at 375px", "contrast is weak", "the grid breaks" → **`audit-ui-and-save-files`**. This skill ignores pixels except where they cause a *comprehension or task* failure. - *Implementing changes.* This skill stops at the recommendations report. If the user wants the changes built, that is a separate, explicitly-requested pass (and likely a different skill). - *Single-flow inline check.* If the user knows the one flow and just wants a quick read, drive `run-agent-browser` inline. This skill's overhead pays back at ≥2 personas or ≥3 journeys, or when the problem set is unknown. - *Accessibility-only audits.* WCAG/AT conformance needs specialized tooling. (A persona *with a disability* is in scope as a persona; full a11y conformance is not.) - *Quantitative testing.* Analytics, A/B tests, SUS-at-scale measure *what* happens; this skill is expert + persona-walkthrough and reveals *why*. ## Headline Capabilities (read this section) Three commitments separate this from a generic "review the UI" run. All three are non-negotiable. ### 1. The lens is persona + journey + heuristic — never pixels Every finding answers: **which persona**, on **which journey**, hit **which usability problem**, violating **which heuristic**, with **what behavioral and business consequence**, and **what major change** fixes it. A finding with no persona and no task impact is not a UX finding — it is either a visual nit (wrong skill) or an opinion (cut it). The full finding template, the Nielsen-10 heuristic catalog with common violations, the persona/journey rubrics, and the severity scale all live in `references/ux-finding-format.md` — plant it verbatim in Phase 2. ### 2. Findings live in a dated, persona-scoped, journey-scoped tree ``` ux-findings/[YY-MM-DD]/[persona]/[journey]/NN-short-slug.md ``` Concrete (a run on 2026-05-28, the first-time user, on the onboarding journey, second issue found): ``` ux-findings/26-05-28/first-time-user/onboarding/02-value-prop-unclear-on-landing.md ``` Each segment is mandatory. Full grammar, persona/journey slug rubrics, and screenshot convention in "Output Tree" below and `references/ux-finding-format.md`. ### 3. The audit ends in RECOMMENDATIONS, not fixes After the audit subagents return, cluster findings into UX **themes** and write `ux-findings/[YY-MM-DD]/RECOMMENDATIONS.md` — a prioritized list of the **major changes** (by severity × persona-reach), each with the personas it helps, the journeys it unblocks, and the business rationale. Then **stop and report.** Do NOT silently implement anything. If — and only if — the user explicitly asks to act, hand off per the routing note in `references/synthesis-and-recommendations.md`. Read that file before clustering. ## The Workflow (Five Phases) ### Phase 1 — Frame the personas and journeys (the most important phase) A UX audit is only as good as its personas. Before dispatching anything, establish: 1. **A dev or prod server is reachable.** `curl -s -o /dev/null -w "%{http_code}" ` must return 200. Boot the dev server in the background and wait for "Ready" if needed. Never audit a server that is not up. 2. **The `run-agent-browser` skill is available.** Check the available-skills list; if absent, surface it and stop — there is no fallback that produces real screenshots. 3. **Personas are defined and grounded in the product.** Each persona has: a name slug, a one-line identity, their **goal** ("what they came to do"), their **expertise** (first-time / returning / power / non-technical), and their **context** (mobile-on-the-go, evaluating-to-buy, daily-driver). Derive personas from the product's real audience — README, landing copy, pricing tiers, docs, the user. Do NOT invent personas the product was never built for. 2–5 personas is typical. The selection rubric is in `references/ux-finding-format.md`. 4. **Each persona's journeys are listed.** A journey is a goal-directed task: `onboarding`, `first-core-task`, `find-and-evaluate`, `recover-from-error`, `upgrade`, `daily-workflow`. Write tasks as **goals in the persona's own words**, never as click-by-click steps with product jargon — discoverability is half of what you're testing. 5. **The audit date is fixed.** Compute `YY-MM-DD` once and pin it for every subagent. Same audit = same date even across midnight. If personas/journeys aren't obvious, ask the user once. Guessing personas wrong invalidates the whole audit. ### Phase 2 — Plant the format spec Write `ux-findings/README.md` in the project root before dispatching. Copy it **verbatim** from `references/ux-finding-format.md` — every subagent reads this file as the single format authority (finding template, Nielsen-10 catalog, persona/journey rubrics, severity scale, path grammar). Do not paraphrase; subagents are matched against this exact file. Also create `ux-findings/[YY-MM-DD]/screenshots/` as the known flat PNG location (per-persona prefix avoids collisions). ### Phase 3 — Dispatch one audit subagent per persona **Partition by `[persona]`.** Each subagent owns one persona, walks that persona's listed journeys, and writes only under `ux-findings/[YY-MM-DD]//**`. A persona with many journeys can be split, but the default unit is one-subagent-one-persona — because the subagent must *stay in character* for a coherent walkthrough. **The subagent IS the persona.** Use the prompt template in `references/persona-subagent-template.md` (mission-protocol shape). It instructs the subagent to: adopt the persona's goal and expertise; attempt each journey as that persona would; **think aloud** (narrate confusion, hesitation, wrong guesses); **observe silently** — never use insider knowledge to rescue itself past a confusing point (the struggle *is* the finding); test the **error / empty / edge** paths, not just the happy path; screenshot the exact moment of friction; and write findings as a UX expert — what the persona *did and felt*, the heuristic violated, the business impact, the recommended major change. Fill the slots and dispatch. Do not compress the template. **DO NOT fully parallelize browser-driven subagents.** `run-agent-browser` shares a Chrome daemon with a SingletonLock; firing many at once makes them steal each other's sessions and return empty. **Stagger** (2 at a time, wait for a batch to return) or run **sequential single-instance**. See `references/footguns.md` §1. ### Phase 4 — Aggregate and find the systemic problems When subagents return: 1. **Inventory:** ```bash find ux-findings/ -name "*.md" -not -name "README.md" -not -name "RECOMMENDATIONS.md" | wc -l find ux-findings/ -mindepth 2 -maxdepth 2 -type d | sort # personas × journeys touched ``` Track counts by persona, by journey, by severity, and by heuristic. 2. **Surface systemic problems** — the highest-value patterns. The same confusion hitting **multiple personas**, or the same heuristic violated across **multiple journeys**, is a structural problem worth one big change, not many small ones. Lift these to the top. 3. **Verify tree shape.** Every path must match `ux-findings////NN-.md`. Move any stray file before continuing. 4. **Report a triage summary**: counts, severity breakdown, the top systemic problems, the worst per-persona blockers, and a path-to-everything. Do NOT start writing recommendations yet inline — that is Phase 5's structured artifact. ### Phase 5 — Synthesize recommendations (report-only) Follow `references/synthesis-and-recommendations.md`; the summary: 1. **Cluster findings into UX themes.** A theme groups findings that share a root cause — a broken journey step, a recurring mental-model mismatch, one confusing concept, or one missing feedback affordance. Merge near-duplicates. 2. **Prioritize by severity × reach**, not by count. A severity-4 blocker hitting the primary persona outranks ten cosmetic-UX nits. Use the impact/reach/confidence rubric in the reference. 3. **Write `ux-findings/[YY-MM-DD]/RECOMMENDATIONS.md`** — for each recommended **major change**: the problem (one line), the personas + journeys it affects, the supporting finding paths, the recommended change (a *direction*, not a pixel spec — "collapse the 3-step wizard into one screen with inline preview", "lead with the outcome, not the feature list"), and the expected behavioral/business win. Order by priority. 4. **Report and stop.** Present the recommendations. Do NOT implement. Only on an explicit user "go" do you hand off (routing in the reference) — and even then, this skill's job was the audit and the recommendations. ## Output Tree ``` ux-findings/ ├── README.md (format spec — copy verbatim from references/ux-finding-format.md) └── [YY-MM-DD]/ (audit date, pinned once at Phase 1) ├── screenshots/ (flat per-date dir; per-persona prefix avoids collisions) │ ├── firsttime-onboarding-02-value-prop.png │ └── power-daily-05-no-bulk-actions.png ├── RECOMMENDATIONS.md (Phase 5 synthesis — prioritized major changes) └── [persona]/ (WHO: first-time-user / power-user / evaluator-buyer / admin / ...) └── [journey]/ (WHAT they're doing: onboarding / first-core-task / upgrade / recover-from-error / ...) ├── 01-.md (one usability problem per file; NN preserves discovery order) └── 02-.md ``` **`[persona]`** — kebab-case slug for *who* is using it, grounded in the product's real audience. Rubric (identity · goal · expertise · context) in `references/ux-finding-format.md`. Examples: `first-time-user`, `returning-user`, `power-user`, `evaluator-buyer`, `admin`, `mobile-commuter`. **`[journey]`** — kebab-case slug for the *goal-directed task* being attempted. Examples: `onboarding`, `first-core-task`, `find-and-evaluate`, `daily-workflow`, `upgrade`, `recover-from-error`, `share-or-invite`. A journey is a goal, not a page. **`NN-short-slug.md`** — zero-padded ordinal within `[persona]/[journey]/`, then a 3–6-word kebab slug naming the *usability problem* (not the page). Examples: `02-value-prop-unclear-on-landing.md`, `05-no-way-to-undo-bulk-delete.md`, `03-jargon-blocks-first-task.md`. Each `.md` follows the template in `references/ux-finding-format.md`. ## Severity Rubric (task-impact framed) Non-negotiable; every finding gets one label. Severity is about **task completion and reach**, not how ugly it looks. - **catastrophe (4)** — the persona **cannot complete a core task** or abandons (gives up, leaves, picks a competitor). The journey is blocked. - **major (3)** — the task completes but with real cost: confusion, wrong turns, repeated errors, long delay, or a near-abandon. The persona succeeds *despite* the design. - **minor (2)** — a hesitation or moment of doubt that resolves; the persona pauses, re-reads, then proceeds. - **cosmetic-ux (1)** — wording/clarity nit with no task impediment (an unclear label that's still guessable). - **(0 = not a UX problem.** Do not file. If it's purely visual, it belongs in `audit-ui-and-save-files`.) Always annotate **reach**: how many of the audit's personas hit this. Severity × reach drives Phase 5 prioritization. The full rubric, with the persona-reaction guidance, is carried verbatim in `references/ux-finding-format.md`. ## Footguns Catalogued with recovery protocols in `references/footguns.md`. The headline list: 1. **Fully parallel browser dispatch causes SingletonLock contention** → stagger or run sequential. 2. **Filing visual/CSS nits as UX findings** → scope bleed into `audit-ui-and-save-files`. A finding must name a *task* impact, or it's the wrong skill. 3. **Inventing personas the product wasn't built for** → personas must be grounded in the real audience; a fabricated persona produces fabricated problems. 4. **"I'd prefer X" instead of "the user is blocked by X"** → taste is not a usability finding. File behavior and consequence, not preference. 5. **Persona drift** — the subagent stops role-playing and reverts to an omniscient developer who "knows where the button is." The struggle is the data; insider rescue destroys it. 6. **Happy-path-only walks** → error, empty, and edge states are where usability dies. The DoD requires testing at least one non-happy path per journey. 7. **Findings with no screenshot** → an unscreenshotted friction claim is unverifiable; the format spec rejects it. 8. **Recommending pixel fixes** → Phase 5 recommends *directions and major changes*, not "move it 8px". Pixel work is the other skill. 9. **Recommendations that are a restatement of findings** → synthesize across findings into fewer, bigger moves; don't just relist. 10. **Implementing instead of reporting** → the skill stops at RECOMMENDATIONS.md unless the user explicitly says go. 11. **Date computed per-subagent** → findings split across two date dirs; pin the date at Phase 1. ## Reference Files - `references/ux-finding-format.md` — verbatim contents of the `ux-findings/README.md` planted in Phase 2: the per-finding template (persona · journey · heuristic · severity · observed behavior · business impact · recommended change · screenshot), the **Nielsen-10 heuristic catalog with common violations**, the persona-selection and journey rubrics, the severity scale, the dated-tree path grammar, and the screenshot-prefix convention. - `references/persona-subagent-template.md` — mission-protocol-shaped per-persona audit subagent prompt, with slots for ``, `` (identity/goal/expertise/context), ``, ``, ``, ``, ``, ``. Embeds stay-in-character, think-aloud, observe-silently, test-error-paths, report-don't-fix. - `references/synthesis-and-recommendations.md` — the Phase 4–5 playbook: theme-clustering rubric, severity × rea … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [yigitkonur](https://github.com/yigitkonur) - **Source:** [yigitkonur/skills-by-yigitkonur](https://github.com/yigitkonur/skills-by-yigitkonur) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-yigitkonur-skills-by-yigitkonur-audit-ux-and-save-files - Seller: https://agentstack.voostack.com/s/yigitkonur - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.