# Audit Ui And Save Files

> Use if auditing a running web app UI across pages/viewports, saving per-bug findings to a tree.

- **Type:** Skill
- **Install:** `agentstack add skill-yigitkonur-skills-by-yigitkonur-audit-ui-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-ui-and-save-files/skills/audit-ui-and-save-files

## Install

```sh
agentstack add skill-yigitkonur-skills-by-yigitkonur-audit-ui-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 UI and Save Files

Disciplined visual QA of a running web app, with a durable on-disk artifact and an explicit fix-dispatch step.

Dispatch parallel audit subagents that each drive the `run-agent-browser` skill across an owned slice of pages, capture screenshots at canonical viewports, and write one markdown finding per real bug into a **dated, context-scoped, device-scoped tree** under `css-issues/`. When the audit returns, cluster findings into themes, present a Markdown dispatch table, **ask the user to approve**, and only then spawn fix subagents that route to the pack's `build-*` or direct-edit paths as appropriate.

The skill owns three things: where files live, how findings are written, and how the fix-pass is dispatched. It does NOT own design taste (the subagents bring that) and does NOT perform the fixes itself (it dispatches them).

## When to Use

Trigger on phrases and contexts like:

- *"audit the UI and save findings"*, *"find CSS issues across the app and write them up"*
- *"do a visual QA and prepare fix tasks"*, *"do a design QA pass and queue the fixes"*
- *"screenshot every page across viewports and inventory the bugs by date"*
- *"check responsive breakpoints on the whole site, then plan the fixes for me to approve"*
- *"the site is feature-complete — audit, save findings, and ask before fixing"*
- *"go through every page at desktop and mobile, write bug files, and propose fix subagents"*

Do NOT use this skill for:

- *Single-page UI debugging.* If the user knows the bug is on one page and just wants it fixed, drive `run-agent-browser` directly inline. This skill's overhead pays back when there are ≥5 routes or when the bug count is unknown.
- *Functional / behavior testing.* Clicks, form submits, end-to-end flows belong with `run-playwright` or similar; this skill is layout/visual-first.
- *Accessibility-only audits.* Use specialized a11y tooling; this skill is visual-first.
- *Performance audits.* Lighthouse / Web Vitals belong elsewhere.
- *Direct fix execution without an audit pass.* If the user has already inventoried the bugs and just wants them fixed, skip the audit phases and use the dispatch step in isolation — but only if the inventory already follows this skill's tree layout.

## Headline Capabilities (read this section)

Two structural commitments separate this skill from a generic visual-audit run. Both are non-negotiable.

### 1. Findings live in a dated, context-scoped, device-scoped tree

Every finding markdown file is written to:

```
css-issues/[YY-MM-DD]/[context]/[device]/NN-short-slug.md
```

Concrete example (an audit run on 2026-05-19, of the dashboard page, at the iPhone-13 viewport):

```
css-issues/26-05-19/dashboard/mobile-375/03-overflow-on-table-headers.md
```

Each segment is mandatory and has a precise meaning. See "Output Tree" below for the full grammar, the canonical viewport slugs, and how to choose `[context]` slugs. Plant the spec into `css-issues/README.md` at Phase 2 so every subagent enforces the same layout.

### 2. Fixes are dispatched only after the user approves a Markdown plan

After every audit subagent returns, Claude does NOT silently spawn fix workers. The skill MUST:

1. Read every finding from disk.
2. Cluster findings into **themes** (coherent units of fix work — shared source files, shared design-token misuse, shared breakpoint, or shared component family).
3. Choose `N` (1 ≤ N ≤ 20) — the number of fix subagents — driven by theme count, NOT by finding count.
4. Build a Markdown table with the columns specified in "Approval-Gated Fix Dispatch" below.
5. **Stop and ask the user to approve.** Banned: spawning any fix subagent before an explicit "go" reply.
6. On approval, spawn the fix subagents; each works against its theme's finding list and routes to the appropriate `build-*` / direct-edit path.

The full clustering rubric, table template, approval grammar, and post-dispatch reconciliation steps live in `references/dispatch-fixes-plan.md` — read it in full before clustering.

## The Workflow (Five Phases)

### Phase 1 — Verify preconditions

Before dispatching any subagents, confirm:

1. **A dev or prod server is reachable.** Run `curl -s -o /dev/null -w "%{http_code}" ` — must return 200. If the user wants to audit `localhost:3000` and nothing is running, boot the dev server in the background and wait for "Ready in" before continuing. Don't dispatch audit subagents against a server that isn't up.
2. **The `run-agent-browser` skill is available.** Check the available-skills list. If it isn't there, surface this and stop — there is no graceful fallback that produces real screenshots.
3. **The page list is known.** Ask the user for the full route list if it's not obvious from context. For larger sites, enumerate routes from source (Next.js App Router pages, sitemap.xml, etc.) rather than guessing.
4. **The audit date is fixed.** Compute `YY-MM-DD` once at the start of the run (e.g. `26-05-19`) and pin it for every subagent. Do not let later subagents recompute — same audit, same date, even if it crosses midnight.
5. **The audit's context labels are known.** Decide upfront which `[context]` slugs the audit covers (e.g. `dashboard`, `signup-flow`, `pricing-page`, `tables-component`). One subagent typically owns one context; large contexts can be split. See "Choosing context slugs" under "Output Tree" for the rubric.

### Phase 2 — Plant the format spec

Write `css-issues/README.md` in the project root before dispatching anything. Every audit subagent reads this file as their format authority — pulling the format spec out of every subagent prompt and into one shared file keeps prompts lean and the format consistent.

Copy the spec verbatim from `references/audit-format-spec.md`. Do NOT paraphrase or recreate — the subagents are matched against this exact file.

Also create `css-issues/[YY-MM-DD]/screenshots/` so subagents have a known location to write PNGs. Screenshots are scoped to the audit date, not to context — they live in one flat per-date directory keyed by prefix to avoid collisions.

### Phase 3 — Split work and dispatch audit subagents

**Partition by `[context]`.** Each subagent owns one (or sometimes two) contexts under the date — a context is the unit of "what slice was audited" and maps cleanly to a subagent's mental model. Common partitions for a marketing-site audit:

- One subagent for the homepage (context = `homepage`)
- One subagent per major route family (`features`, `pricing`, `customers`)
- One subagent for stub / shallow pages (context = `stubs`)

A 21-route site fits cleanly into 3–4 subagents. A larger site can scale to 6–8.

**File ownership is the boundary.** Each subagent's "Hard constraints" section names exactly which paths under `css-issues/[YY-MM-DD]//**` they may touch. Sibling subagents do not write to each other's subtrees. Screenshots use a per-subagent prefix — see the screenshot-prefix rule below.

**Use the prompt template** in `references/subagent-prompt-template.md`. It follows the mission-protocol shape (context → mission gravity → hard constraints → research guidance → DoD → verification → failure protocol → handback). Fill the per-agent slots and dispatch. The template is calibrated against real subagent runs — do NOT compress it.

**Dispatch strategy — DO NOT fully parallelize browser-driven audits.** This is the single most important footgun. `run-agent-browser` uses a shared Chrome daemon with a SingletonLock; if you fire 4 audit subagents in the same message they will contend, steal each other's sessions, and most will return with 0 findings. The patterns that actually work:

- **Stagger:** dispatch 2 at a time, wait for one batch to return before dispatching the next.
- **Sequential single-instance:** one subagent does all the pages serially. Slower wall-clock, dramatically higher reliability.

See `references/footguns.md` §1 and §7 for the full failure analysis and recovery protocol.

### Phase 4 — Aggregate audit output

When all subagents return:

1. **Inventory the output:**
   ```bash
   find css-issues/ -name "*.md" -not -name "README.md" | wc -l
   ls css-issues//screenshots/ | wc -l
   find css-issues/ -mindepth 3 -maxdepth 3 -type d | sort
   ```
   Track count by context, by device, and by severity (critical / major / minor).

2. **Surface systemic findings.** The highest-value patterns are bugs that recur across contexts or devices — they collapse the fix pass from N edits to 1 edit. Read each subagent's "Observations" handback section and lift any "this manifests on N other pages" notes into the top of your summary.

3. **Verify tree shape.** Every finding file path should match `css-issues////NN-.md`. Any file outside this shape is a subagent error — move it before continuing.

4. **Report a triage summary** to the user: total counts, severity breakdown, top 5–8 most critical individual bugs, the systemic patterns, and a path-to-everything. **Do not start fixing.** That is Phase 5.

### Phase 5 — Approval-gated fix dispatch

This phase is the headline new capability. Follow `references/dispatch-fixes-plan.md` in detail; the summary is:

1. **Cluster findings into themes.** A theme is a group whose findings share at least one of: the same source files, the same design-token misuse, the same viewport breakpoint, the same component family. If two candidate themes share more than ~70% of their target files, merge them.

2. **Choose `N` (1 ≤ N ≤ 20) fix subagents.** `N` is driven by **theme count**, NOT by finding count. A 60-finding audit can map cleanly to 4 themes and 4 subagents; an 18-finding audit might need 6 subagents if the themes are tightly file-disjoint. Cap at 20.

3. **Build the dispatch table** with these columns, in this order:

   | # | Theme | Findings (count + paths) | Files likely touched | Outcome | Suggested skill(s) |
   |---|---|---|---|---|---|

   - `#` — ordinal subagent number (1..N).
   - `Theme` — short name (3–6 words) for the cluster (`mobile-375 overflow cluster`, `dashboard contrast on dark surfaces`, `BrandLogo fallback`).
   - `Findings (count + paths)` — count and the full per-finding paths (relative to repo root). For >5 findings, list the first 5 and `…+N more`; the full list goes into the subagent prompt.
   - `Files likely touched` — best-guess `src/...` paths derived from each finding's `Likely cause` field. Deduplicated.
   - `Outcome` — one-line success criterion (`bug is invisible at 1440×900 and 375×812`, `BrandLogo renders correctly on every page`).
   - `Suggested skill(s) to invoke` — `frontend-design` is NOT a skill in this pack; route to canonical alternatives instead: `build-tinacms-nextjs` / `build-chrome-extension` for framework-specific edits, plain `Edit` / `Write` for vanilla CSS/component fixes, `run-review` Mode A for the post-fix self-review step. See `references/dispatch-fixes-plan.md` for the full routing matrix.

4. **Show the full table to the user** in the chat. Then ask, verbatim or close to it:

   > **Approve the plan above? Reply `go` to dispatch all, `go 1,3,5` to dispatch only those subagents, `change` to revise the plan, or `cancel` to stop here.**

5. **Block on the reply.** Do NOT spawn any fix subagent before the user has typed `go` (with optional subset) or an equivalent affirmative. If the reply is `change`, revise the table and re-ask. If `cancel`, stop — the audit artifact remains on disk for later.

6. **Spawn the approved fix subagents.** Each gets a tightly scoped prompt: (a) the list of finding files it owns (full paths), (b) the suggested skill to invoke, (c) the outcome criterion, (d) hard constraints on what it must NOT touch outside its theme. See `references/dispatch-fixes-plan.md` for the fix-subagent prompt template.

7. **Reconcile after fixes land.** When fix subagents return, each finding file gets its `## Fix tracking` block updated (`Fixed by subagent #N` checkbox flipped). The audit skill's job ends when (a) fixes are committed and (b) the audit tree reflects which findings are resolved. Re-running the audit verb is a separate session.

## Output Tree

The full grammar of the on-disk artifact:

```
css-issues/
├── README.md                                   (format spec — single source of truth, copy from references/audit-format-spec.md)
└── [YY-MM-DD]/                                  (audit date, e.g. 26-05-19; computed once at Phase 1)
    ├── screenshots/                             (flat per-date directory; per-subagent prefix avoids collisions)
    │   ├── homepage-bento-01-cards-overlap.png
    │   ├── feat-pricing-02-cta-cut-off.png
    │   └── stub-careers-01-page-x-scroll.png
    └── [context]/                                (the slice audited: dashboard / homepage / features / signup-flow / tables / ...)
        └── [device]/                             (viewport slug: mobile-375 / desktop-1440 / tablet-768 / ...)
            ├── 01-.md                (one finding per file; NN preserves discovery order within context/device)
            ├── 02-.md
            └── ...
```

### Segment definitions

**`YY-MM-DD`** — two-digit year, two-digit month, two-digit day of the audit. Computed at Phase 1 and pinned for every subagent. Same audit = same date even if it crosses midnight. Re-audits get a new date; old dates are durable history.

**`[context]`** — a hand-chosen short kebab-case name for the slice being audited. Choose one of these granularities depending on what makes sense for the codebase:

- **Page-level:** `dashboard`, `homepage`, `pricing`, `signup`, `settings-profile`. Best when each page has distinct visual concerns.
- **Flow-level:** `signup-flow`, `checkout-flow`, `onboarding`. Best when the audit spans 2–4 related pages with shared visual identity.
- **Component-family:** `tables`, `forms`, `modals`, `navigation`. Best when the bug class is component-shape across pages (a `` overflows on mobile *everywhere*).
- **Section:** `homepage-hero`, `homepage-bento`. Best when a single page is large enough to split across subagents.

Avoid mixing granularities in one audit — e.g. `dashboard/` and `tables/` overlap because tables appear on the dashboard; pick one. If the audit genuinely needs both, namespace them explicitly (`tables-component/` to clarify it's the standalone component, not the dashboard's tables).

**`[device]`** — canonical viewport slug. Choose from this list:

| Slug | Width × Height | Used for |
|---|---|---|
| `mobile-375` | 375 × 812 | iPhone-13 baseline; the brutal-truth viewport |
| `mobile-414` | 414 × 896 | iPhone Plus-class |
| `tablet-768` | 768 × 1024 | Where mega-menus collapse to slide-in panels |
| `tablet-1024` | 1024 × 768 | Where bento/feature grids go 2-col |
| `desktop-1280` | 1280 × 800 | Where 12-col grids often collapse to 8/4 |
| `desktop-1440` | 1440 × 900 | Primary design target on most modern sites |
| `desktop-1920` | 1920 × 1080 | Where max-width caps and white space appear |

Auditor MAY add more (e.g. `mobile-360` for Android baseline, `desktop-2560` for 4K) but MUST explain in the handback Observations why the canonical set was insufficient. The canonical set is the default; expansions are exceptions.

**`NN-short-slug.md`** — zero-padded ordinal (`01`, `02`, …, `99`) within `[context]/[device]/`, then a 3–6-word kebab-case slug describing the bug. Ordinal is per-`[context]/[device]/` (not global), preserves manual sort order, and gives the fix subagents a stable iteration order. Examples:

- `01-bento-cards-overlap-row2.md`
- `03-overflow-on-table-headers.md`
- `07-cta-button-clipped-by-cookie-banner.md`

### Canonical example

A finding for a table overflow on the dashboard, iPhone-13 viewport, third bug discovered for that context/device on 2026-05-19:

```
css-issues/26-05-19/dashboard/mobile-375/03-overflow-on-table-headers.md
```

That path is searchable, sortable, and locatable to a single subagent's worth of work. The fix dispatch step in Phase 5 reads these paths verbatim and assigns them to

…

## 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-ui-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%.