Triage a UI Verify build from your agent
When a build comes back changed, the dashboard shows a triptych per story (baseline / candidate /
diff). This skill does that review from your agent over the UI Verify MCP — read what changed, look
at the pixels when a number is ambiguous, then summarize or accept.
When to Use This Skill
- Use when a UI Verify build reports changed or failed stories and the user wants the agent to review them instead of the dashboard.
- Use when the user asks to triage a build, summarize the visual regressions for a PR comment, or accept the new baselines.
- Use when the user wants the before-and-after of a pull request's UI changes, or to reply to or resolve a reviewer's comment on a diff.
- Requires a UI Verify project that uploads builds from CI, and the UI Verify MCP server connected in the agent.
Connect the MCP (once)
The server is a remote Streamable-HTTP MCP at https://uiverify.ai/mcp. You log in once with your UI
Verify account in the browser (OAuth), and that one connection reaches every project in every team you
are a member of, so there is no per-project setup and no API key in the config. Add it as a real MCP
server in your agent — don't hand-roll curl against the endpoint. Over raw curl the image tools come
back as MCP image blocks a shell can't render, so the pixels are useless to a script; a native client shows
them to the model directly.
Claude Code — run in the project root:
claude mcp add --scope project --transport http uiverify https://uiverify.ai/mcp
Then restart Claude Code, run /mcp, pick uiverify, and log in. --scope project writes the server to
the committed .mcp.json; it holds no secret, so the whole team gets it and each teammate logs in with
their own account.
Cursor — add to .cursor/mcp.json (commit it to share), then log in from Cursor's MCP settings:
{
"mcpServers": {
"uiverify": { "url": "https://uiverify.ai/mcp" }
}
}
Any other MCP client (VS Code, Codex, Copilot, Gemini): point it at the same Streamable-HTTP URL and it
asks you to log in. Restart the agent session after adding the server so the tools load. If a client can
only reach it over HTTP by hand, prefer the get_diff tool (it returns downloadable image URLs) over
render_diff_image (inline pixels) — see the tool table below.
Tools it exposes:
| Tool |
Does |
Key args |
list_projects |
Every project you can access, with its projectId, team, name, type, repo, and last build time. Only needed when you can access several projects: a commitSha / prNumber lookup and list_builds then take a projectId (with one project it is used automatically, and a call that's ambiguous returns an error listing them) |
none |
list_builds |
Recent builds + gate status, to find the one to inspect |
projectId?, branch?, status?, limit? |
get_build |
Lean triage of one build — the gate + counts {total, changed, failed, unchanged}, a build-wide comments {total, unresolved} review-comment tally, the AI tally, and the first page (25) of changed/failed stories (each with a diffResultId, diff %, and when AI review is on the judge's aiVerdict, aiConfidence, and for a regression aiFlagReason = its one-line "what looks unintended"), the page carrying a nextCursor. It does not dump the unchanged list — counts.unchanged is the signpost; page the rest with list_build_stories. comments.unresolved > 0 means a human/agent left an open note — read it with list_comments before you accept |
one of commitSha / prNumber / buildId |
list_build_stories |
Page through one build's stories by status — the only way to browse the full changed / failed / unchanged set beyond get_build's first page. counts.unchanged from get_build is the exact count it pages. Every changed-story row (here and in get_build) carries its own comments {total, unresolved} |
selector, status: changed | unchanged | failed, cursor?, limit? (default 25, max 100) |
get_diff |
Per-story diff metrics + presigned image URLs (baseline / candidate / diff) you can download to a file or link straight into a PR; when AI review is on, the judge's full call: aiVerdict, aiConfidence, aiSummary (what changed), aiReasoning (why), aiFlagReason; and a per-story comments {total, unresolved} (same signpost as get_build, scoped to the one story). Pass storyId to pull one story even if it didn't change — you get its current baseline URL, so you can show "identical to baseline" on a passed build |
same selector, optional storyId |
render_diff_image |
The actual pixels of one image, inline for the vision model to look at (not a URL): baseline / candidate / diff, or before_after for a before-and-after crop zoomed to the changed region — one crop per region, stacked, when the story moved in several far-apart places (a header and a footer). When the story has an unresolved review comment, a text note saying so comes before the image |
diffResultId (or storyId for a story that didn't change), which |
get_pr_changeset |
The cumulative "This PR vs base" changeset: what the whole pull request did to the UI vs the branch it merges into — new / changed / removed stories, each with review status (and the judge's verdict when AI review is on), plus counts {new, changed, removed, unchanged} and the first page (25) of each list. Distinct from get_build, which is one commit's gate: this survives in-PR accepts and merge, and catches an added-then-accepted story and a removed one that no single build's diff can see |
one of commitSha / prNumber / buildId |
list_pr_stories |
Page one bucket of the PR-vs-base changeset beyond get_pr_changeset's first page |
selector, kind: new | changed | removed, cursor?, limit? |
review_diff |
Record a decision on one story. accept and ignore are refused while the story has an unresolved review comment; deny always works |
diffResultId, decision: accept | deny | ignore |
accept_build |
Accept every changed story in a build at once. Refused, accepting nothing, while any changed story has an unresolved review comment — the error names those stories |
same selector |
list_comments |
Read the review comments a designer/QA (or another agent) left on a build's diffs — every live comment across the build, each carrying its diffResultId, authorType, body, side, parentId (a reply's thread root), anchor (a point/region on the image), and resolved. This is the thing get_build/get_diff's comments count points you to |
one of commitSha / prNumber / buildId |
post_comment |
Leave a comment (or a threaded reply) on one story's diff — e.g. reply to a reviewer's question, or flag a regression back to them. Authored as the agent; a new root comment is refused if a newer build exists on the branch (comment on the latest), but replies are always allowed |
selector + diffResultId, body, side?, anchor?, parentId? (reply to a root's id) |
resolve_comment |
Resolve (or reopen) a comment thread once its note is addressed |
commentId (thread root), resolved |
update_comment / delete_comment |
Edit or remove a comment — the agent may only touch agent-authored comments |
commentId (+ body for update) |
The comment tools (list_comments and the writes) are behind the team's image-comments feature; if they
are not exposed on your MCP connection, your team does not have it enabled, and get_build/get_diff
will simply report comments {total: 0, unresolved: 0}.
Recipe 1 — "Triage this build"
Bucket the changes so the human sees signal, not 60 rows. Call get_build for the PR — it carries the
AI judge's call per story (aiVerdict, and for a regression the aiFlagReason) for the first page of
changes; if counts.changed is larger than that page, keep paging list_build_stories { status: "changed" } on the nextCursor until it runs out, so no regression slips past the page boundary. Read the judge before
you form your own view, and for anything that actually changed content, adjudicate it against the
before image, not in isolation:
Render BOTH images, not just the diff. render_diff_image which: "baseline" and
which: "candidate" and compare them. The green diff mask tells you where pixels moved, never
whether the result is good — a code block that went dark-on-dark, text that lost contrast, a
control that's now clipped all look like "some pixels changed" in the mask and only reveal
themselves as regressions in the before/after. Judging the candidate alone is how "it has colours
now → improvement" passes an illegible block. Pull get_diff for the judge's aiReasoning /
aiFlagReason on the ones it flagged.
Read the human's comments before you decide. If get_build's comments.unresolved > 0 (or a
get_diff story shows comments), a designer/QA or another agent has left a note on this build —
list_comments reads them, each tied to its diffResultId so you can match a note to the story in your
buckets. A comment is context the pixels don't carry ("this spacing is intentional, don't revert it" /
"the logo is wrong here"), so read it before you bucket the story. You can't accept over one anyway:
accept_build and review_diff accept/ignore refuse a story with an unresolved comment. The loop is
read the note → do what it asks (often a code change and a new push) → resolve_comment → accept.
Never resolve a note just to unblock the accept; resolve it because you addressed it.
Report in four buckets, with real story names and % deltas:
- Regression — a real change that's wrong — content changed and the after is broken or worse:
illegible/low-contrast text, clipping, overlap, missing content, a control that stopped reading as
itself. A regression the current PR caused is still a regression — "my diff explains it"
says nothing about whether it's correct. Never accept these; they're the reason to triage.
- Intended change — content changed and the after is correct and matches the PR's stated intent
(a deliberate restyle, new copy, a genuinely new story). These still want a human eye, but they're
accept candidates.
- Cosmetic reflow — real diff pixels, but the diff image shows the same content shifted a few px
(a row moved down ~5px, text ghosted lower). Not a content change.
- Rendering noise — safe to accept — sub-0.4% jitter on chart edges / anti-aliased lines. Pure
render jitter.
The judge's regression verdict is a reason to look harder, never to dismiss. If you're about to
call a story the judge flagged "intended anyway", you need a concrete reason from the before/after that
refutes its aiFlagReason — not "it's a colour change, probably fine." When you can't refute it, trust
it.
Example output shape:
67 changed stories → buckets.
⚠️ Regressions (2) — real changes that look wrong, do NOT accept: SetupWizard/Playwright (8.3%,
code block now dark-on-dark / illegible — judge flagged regression), Card/Compact (5.1%, title
clipped) …
1. Intended changes (11) — content changed, looks correct, accept candidates: Hero/Default (14%,
new headline copy), …
2. Cosmetic reflow (9) — real pixels, vertical shift only: EventStatusCard/All Variants (4.1%,
rows shifted ~5px), TestingInit/Playground (3.7%), …
3. Chart anti-aliasing noise (6) — sub-0.4% edge jitter, safe to accept: FunnelChart/Smaller Screen (3.2%), UpliftChart (single 1px mark), …
New stories (12) — first baseline, nothing to compare: Button/AllVariants, …
Never accept from inside the triage step — surface the buckets and let the human decide, or do it
explicitly in recipe 3.
Recipe 2 — "Summarize the visual regressions"
Same read, but output the changes that need a human — the ⚠️ regressions first, then the intended
content changes — in a PR-comment shape, one line each, no reflow/noise. This is the comment to drop on
the PR:
🔎 Visual review — 1 regression, 2 intended (of 67 flagged; 64 reflow/noise, listed below the fold)
- ⚠️
SetupWizard/Playwright — code block dark-on-dark, illegible (8.3%, judge: regression)
Pricing/Card — CTA button color changed blue→green (12.4%)
Nav/Header — logo 8px larger (3.1%)
Recipe 3 — "Accept all the new baselines"
When the changes are all intended (a deliberate restyle) or all noise and you've confirmed no
regression is hiding in the list (bucket ⚠️ empty), advance every changed story's baseline in one call:
accept_build { prNumber: 123 }
Don't let "the headline change is intended" halo onto the whole build — a global CSS or theme change
sweeps into stories the PR never meant to touch, and "the PR caused it" is not "the PR intended it."
Each changed story earns its bucket on its own before-and-after.
For a targeted accept (some real, some not), loop review_diff per diffResultId with
accept / ignore / deny instead — accept the intended ones, ignore the noise, leave real
regressions for a human.
Recipe 4 — "Put the before/after in the PR"
Keep the human in the PR instead of sending them to the dashboard. After you've triaged, post the
changed stories inline:
- The fastest single image:
render_diff_image which: "before_after" gives you one PNG, before and
after side by side, cropped to the changed region (one crop per region, stacked, if the story moved in
several far-apart places) — the least to eyeball. Save it and attach it.
- Downloadable files / durable links:
get_diff returns presigned baselineUrl / candidateUrl /
diffUrl. Download them (curl -L "$url" -o before.png) to attach to the PR, or drop the build link
and the URLs into a comment. Always include the build link (https://uiverify.ai/builds/<id>) so the
reviewer can open the full triptych.
A good PR comment: the one-line-per-regression summary from Recipe 2, the before/after image for the
regressions, and the build link. Post it, don't make them go looking.
Recipe 5 — "What did this whole PR do to the UI?"
get_build answers one commit — is anything unreviewed on this build. It does not prove the
whole PR did what you intended, and it's blind to two things by construction: a story you added and
accepted earlier in the PR (the latest build renders it clean, so it never shows as changed) and a
removed story (a deleted or renamed baseline — no build renders it, so no per-build diff flags it).
get_pr_changeset is the only surface that catches both, so run it before you call a PR done.
Pull it for the PR and read the whole head-vs-base picture:
get_pr_changeset { prNumber: 123 } → new / changed / removed vs the base branch
list_pr_stories { prNumber: 123, kind: "removed" } → page any one bucket
Hold every entry to one bar: can you attribute it to something this PR's diff actually did?
- Yes, and it's correct → the intended visual impact of the PR.
- A change you can't attribute to your own diff → stop. Don't accept it, don't dismiss it as flake,
don't "re-run and see." Say so and flag it for a human — the likely cause is a baseline that moved when
it shouldn't have, which is silent by construction.
- A
removed story you didn't intend → an accidental deletion (or an unintended rename, which reads
as a remove plus an add). Flag it loudly; don't let a green check ship it.
The changeset is GA — no flag to enable, and on a public project anyone can read it for a build
without logging in.
Recipe 6 — "Answer or resolve a review comment"
When a reviewer's note is a question you can answer, or points at something you just fixed, close the loop
from the agent instead of making them chase you. Read the thread with list_comments, then:
- Reply in the thread —
post_comment { diffResultId, body, parentId } where parentId is the root
comment's id (a reply inherits the root's side and needs no anchor of its own). Use it to answer
"why did this move?" with the diff you made, or to confirm "fixed in the next push."
- Flag a regression back —
post_comment { diffResultId, body, anchor? } as a new root, to point the
reviewer at a story you're leaving for them (pair it with the ⚠️ bucket from Recipe 1).
- Resolve —
resolve_comment { commentId, resolved: true } once the note is addressed (you made the
change it asked for, or answered the question). Resolve before you accept: an open thread makes
accept_build / review_diff refuse that story. Only reach for this when the thread is genuinely done;
the open comment is the signal that stops a premature accept.
Your key authors comments as the agent, and can only edit/delete comments it authored — never touch a
human's comment.
Passed build? You can still show the pixels
A build with no changes shows no triptych — but the components still rendered, and "nothing changed" is
only trustworthy if you can see it. Enumerate the unchanged set with list_build_stories { status: "unchanged" } (page it on the returned nextCursor), then pull any story's current image by id:
get_diff { buildId, storyId } for its baseline URL, or render_diff_image { storyId, which: "baseline" }
for the pixels. Use it to
confirm a component looks right on a green build, or to hand the reviewer "here it is, identical to
baseline" without opening the dashboard.
Guardrails
- Read before you write. Always
get_build (and render_diff_image for anything ambiguous) before
review_diff / accept_build. Don't accept a build you haven't looked at.
- Compare before-and-after, never the after alone. For any story that changed content, render
which: "baseline" AND which: "candidate" and look at both — the diff mask shows where, the pair
shows whether it got worse (contrast/legibility, clipping, layout). "It has colours / it moved" is not
"it's better."
- The AI judge's
regression is a signal to trust by default. Overriding it needs a concrete reason
from the before/after that refutes its aiFlagReason, not a hand-wave. Attributable-to-this-PR is not
a reason to dismiss it.
- Bulk-accept is a baseline change.
accept_build makes the candidate the new truth for every
changed story — only reach for it when you've confirmed there's no real regression hiding in the list.
- An unresolved comment blocks the accept.
get_build's comments.unresolved > 0 means a human left
a note you haven't read — list_comments it and honor it before review_diff / accept_build. A
reviewer commenting "don't accept this" that an agent bulk-accepts anyway is exactly the failure this
count exists to prevent.
- Distinguish "new story" from "changed story." A first-baseline story has nothing to diff; it's not
a regression, just needs a baseline. Bucket it separately.
Examples
Example 1: Triage the build for a pull request
The user says: "Triage the UI Verify build for PR 123."
get_build { prNumber: 123 }
render_diff_image { diffResultId: "<diffResultId from get_build>", which: "before_after" }
Bucket each changed story as a regression, cosmetic reflow or rendering noise from its before-and-after, then report the regressions by story name.
Example 2: Accept the intended changes
The user says: "Those all come from the new button style, accept them."
accept_build { prNumber: 123 }
Only after every changed story was looked at and none is a regression. For a mixed build, call review_diff { diffResultId: "<id>", decision: "accept" } for each intended story instead.
Limitations
- Needs a UI Verify account and a project whose CI uploads builds with the
uiverify CLI (Storybook, Playwright or Vitest); with no build there is nothing to triage.
- Needs network access to the hosted MCP server at
https://uiverify.ai/mcp and a one-time browser login, which the agent cannot complete on its own.
- AI verdict fields appear only when AI review is on for the project, and the comment tools only when the team has image comments enabled.
- Over raw HTTP the image tools return MCP image blocks a shell cannot show; use a native MCP client, or
get_diff for image URLs.
Security & Safety Notes
review_diff (accept) and accept_build change the project's baselines on the service, and later builds are compared against them. Look at the before and after first, and never bulk-accept a build that may hide a regression.
- The server refuses accept and ignore while a story has an unresolved review comment; read it with
list_comments and honour it.
get_diff returns presigned image URLs that work for anyone holding them until they expire. Share them only where the team would share the screenshot.
- Each person connects with their own OAuth login; there is no API key in
.mcp.json.
Catalog adaptation
Copied from the official MIT source above at commit 181d9e4 with its instructions unchanged; this catalog adds When to Use This Skill, Examples, Limitations and Security & Safety Notes.
1---2name: uiverify-triage-visual-changes3description: "Triage a UI Verify visual regression build from your coding agent over MCP: sort changed screenshots into regressions, intended changes and noise, then accept baselines."4category: testing5risk: critical6source: "https://github.com/uiverify/uiverify/tree/main/packages/skills/skills/triage-visual-changes"7source_repo: uiverify/uiverify8source_type: official9date_added: "2026-10-19"10author: igrlk11tags: [visual-testing, visual-regression, screenshot-testing, mcp, storybook, playwright, vitest]12tools: [claude-code, codex, cursor, gemini]13license: "MIT"14license_source: "https://github.com/uiverify/uiverify/blob/main/LICENSE"15metadata:16 source: https://skillmd.com/skills/iradoweck/uiverify-triage-visual-changes17---1819# Triage a UI Verify build from your agent2021When a build comes back **changed**, the dashboard shows a triptych per story (baseline / candidate /22diff). This skill does that review from your agent over the **UI Verify MCP** — read what changed, look23at the pixels when a number is ambiguous, then summarize or accept.2425## When to Use This Skill2627- Use when a UI Verify build reports changed or failed stories and the user wants the agent to review them instead of the dashboard.28- Use when the user asks to triage a build, summarize the visual regressions for a PR comment, or accept the new baselines.29- Use when the user wants the before-and-after of a pull request's UI changes, or to reply to or resolve a reviewer's comment on a diff.30- Requires a UI Verify project that uploads builds from CI, and the UI Verify MCP server connected in the agent.3132## Connect the MCP (once)3334The server is a remote Streamable-HTTP MCP at `https://uiverify.ai/mcp`. You log in once with your UI35Verify account in the browser (OAuth), and that one connection reaches every project in every team you36are a member of, so there is no per-project setup and no API key in the config. **Add it as a real MCP37server in your agent — don't hand-roll `curl` against the endpoint.** Over raw `curl` the image tools come38back as MCP image blocks a shell can't render, so the pixels are useless to a script; a native client shows39them to the model directly.4041**Claude Code** — run in the project root:42```sh43claude mcp add --scope project --transport http uiverify https://uiverify.ai/mcp44```4546Then restart Claude Code, run `/mcp`, pick `uiverify`, and log in. `--scope project` writes the server to47the committed `.mcp.json`; it holds no secret, so the whole team gets it and each teammate logs in with48their own account.4950**Cursor** — add to `.cursor/mcp.json` (commit it to share), then log in from Cursor's MCP settings:51```json52{53 "mcpServers": {54 "uiverify": { "url": "https://uiverify.ai/mcp" }55 }56}57```5859Any other MCP client (VS Code, Codex, Copilot, Gemini): point it at the same Streamable-HTTP URL and it60asks you to log in. Restart the agent session after adding the server so the tools load. If a client can61only reach it over HTTP by hand, prefer the `get_diff` tool (it returns downloadable image **URLs**) over62`render_diff_image` (inline pixels) — see the tool table below.6364Tools it exposes:6566| Tool | Does | Key args |67|---|---|---|68| `list_projects` | Every project you can access, with its `projectId`, team, name, type, repo, and last build time. Only needed when you can access several projects: a `commitSha` / `prNumber` lookup and `list_builds` then take a `projectId` (with one project it is used automatically, and a call that's ambiguous returns an error listing them) | none |69| `list_builds` | Recent builds + gate status, to find the one to inspect | `projectId?`, `branch?`, `status?`, `limit?` |70| `get_build` | Lean triage of one build — the gate + `counts {total, changed, failed, unchanged}`, a build-wide `comments {total, unresolved}` review-comment tally, the AI tally, and the **first page (25)** of changed/failed stories (each with a `diffResultId`, diff %, and when AI review is on the judge's `aiVerdict`, `aiConfidence`, and for a regression `aiFlagReason` = its one-line "what looks unintended"), the page carrying a `nextCursor`. It does **not** dump the unchanged list — `counts.unchanged` is the signpost; page the rest with `list_build_stories`. `comments.unresolved > 0` means a human/agent left an open note — read it with `list_comments` before you accept | one of `commitSha` / `prNumber` / `buildId` |71| `list_build_stories` | Page through one build's stories by status — the only way to browse the full changed / failed / **unchanged** set beyond `get_build`'s first page. `counts.unchanged` from `get_build` is the exact count it pages. Every changed-story row (here and in `get_build`) carries its own `comments {total, unresolved}` | selector, `status: changed \| unchanged \| failed`, `cursor?`, `limit?` (default 25, max 100) |72| `get_diff` | Per-story diff metrics + **presigned image URLs** (baseline / candidate / diff) you can download to a file or link straight into a PR; when AI review is on, the judge's full call: `aiVerdict`, `aiConfidence`, `aiSummary` (what changed), `aiReasoning` (why), `aiFlagReason`; and a per-story `comments {total, unresolved}` (same signpost as `get_build`, scoped to the one story). Pass `storyId` to pull one story **even if it didn't change** — you get its current baseline URL, so you can show "identical to baseline" on a passed build | same selector, optional `storyId` |73| `render_diff_image` | The actual **pixels** of one image, inline for the vision model to look at (not a URL): `baseline` / `candidate` / `diff`, or `before_after` for a before-and-after crop zoomed to the changed region — one crop per region, stacked, when the story moved in several far-apart places (a header and a footer). When the story has an unresolved review comment, a text note saying so comes **before** the image | `diffResultId` (or `storyId` for a story that didn't change), `which` |74| `get_pr_changeset` | The **cumulative** "This PR vs base" changeset: what the *whole pull request* did to the UI vs the branch it merges into — `new` / `changed` / `removed` stories, each with review status (and the judge's verdict when AI review is on), plus `counts {new, changed, removed, unchanged}` and the **first page (25)** of each list. **Distinct from `get_build`**, which is one commit's gate: this survives in-PR accepts **and** merge, and catches an added-then-accepted story and a **removed** one that no single build's diff can see | one of `commitSha` / `prNumber` / `buildId` |75| `list_pr_stories` | Page one bucket of the PR-vs-base changeset beyond `get_pr_changeset`'s first page | selector, `kind: new \| changed \| removed`, `cursor?`, `limit?` |76| `review_diff` | Record a decision on one story. `accept` and `ignore` are **refused** while the story has an unresolved review comment; `deny` always works | `diffResultId`, `decision: accept \| deny \| ignore` |77| `accept_build` | Accept **every** changed story in a build at once. **Refused, accepting nothing,** while any changed story has an unresolved review comment — the error names those stories | same selector |78| `list_comments` | Read the review comments a designer/QA (or another agent) left on a build's diffs — every live comment across the build, each carrying its `diffResultId`, `authorType`, `body`, `side`, `parentId` (a reply's thread root), `anchor` (a point/region on the image), and `resolved`. This is the thing `get_build`/`get_diff`'s `comments` count points you to | one of `commitSha` / `prNumber` / `buildId` |79| `post_comment` | Leave a comment (or a threaded reply) on one story's diff — e.g. reply to a reviewer's question, or flag a regression back to them. Authored as the **agent**; a new root comment is refused if a newer build exists on the branch (comment on the latest), but replies are always allowed | selector + `diffResultId`, `body`, `side?`, `anchor?`, `parentId?` (reply to a root's id) |80| `resolve_comment` | Resolve (or reopen) a comment thread once its note is addressed | `commentId` (thread root), `resolved` |81| `update_comment` / `delete_comment` | Edit or remove a comment — the agent may only touch **agent-authored** comments | `commentId` (+ `body` for update) |8283The comment tools (`list_comments` and the writes) are behind the team's image-comments feature; if they84are not exposed on your MCP connection, your team does not have it enabled, and `get_build`/`get_diff`85will simply report `comments {total: 0, unresolved: 0}`.8687## Recipe 1 — "Triage this build"8889Bucket the changes so the human sees signal, not 60 rows. Call `get_build` for the PR — it carries the90AI judge's call per story (`aiVerdict`, and for a regression the `aiFlagReason`) for the **first page** of91changes; if `counts.changed` is larger than that page, keep paging `list_build_stories { status:92"changed" }` on the `nextCursor` until it runs out, so no regression slips past the page boundary. **Read the judge before93you form your own view, and for anything that actually changed content, adjudicate it against the94before image, not in isolation:**9596- **Render BOTH images, not just the diff.** `render_diff_image` `which: "baseline"` **and**97 `which: "candidate"` and compare them. The green diff mask tells you *where* pixels moved, never98 *whether the result is good* — a code block that went dark-on-dark, text that lost contrast, a99 control that's now clipped all look like "some pixels changed" in the mask and only reveal100 themselves as regressions in the before/after. Judging the candidate alone is how "it has colours101 now → improvement" passes an illegible block. Pull `get_diff` for the judge's `aiReasoning` /102 `aiFlagReason` on the ones it flagged.103104- **Read the human's comments before you decide.** If `get_build`'s `comments.unresolved > 0` (or a105 `get_diff` story shows `comments`), a designer/QA or another agent has left a note on this build —106 `list_comments` reads them, each tied to its `diffResultId` so you can match a note to the story in your107 buckets. A comment is context the pixels don't carry ("this spacing is intentional, don't revert it" /108 "the logo is wrong here"), so read it before you bucket the story. You can't accept over one anyway:109 `accept_build` and `review_diff` accept/ignore refuse a story with an **unresolved** comment. The loop is110 read the note → do what it asks (often a code change and a new push) → `resolve_comment` → accept.111 Never resolve a note just to unblock the accept; resolve it because you addressed it.112113Report in four buckets, with real story names and % deltas:1141151. **Regression — a real change that's wrong** — content changed and the after is broken or worse:116 illegible/low-contrast text, clipping, overlap, missing content, a control that stopped reading as117 itself. **A regression the current PR *caused* is still a regression** — "my diff explains it"118 says nothing about whether it's correct. Never accept these; they're the reason to triage.1192. **Intended change** — content changed and the after is correct and matches the PR's stated intent120 (a deliberate restyle, new copy, a genuinely new story). These still want a human eye, but they're121 accept candidates.1223. **Cosmetic reflow** — real diff pixels, but the diff image shows the *same* content shifted a few px123 (a row moved down ~5px, text ghosted lower). Not a content change.1244. **Rendering noise — safe to accept** — sub-0.4% jitter on chart edges / anti-aliased lines. Pure125 render jitter.126127**The judge's `regression` verdict is a reason to look harder, never to dismiss.** If you're about to128call a story the judge flagged "intended anyway", you need a concrete reason from the before/after that129refutes its `aiFlagReason` — not "it's a colour change, probably fine." When you can't refute it, trust130it.131132Example output shape:133> **67 changed stories → buckets.**134> **⚠️ Regressions (2)** — real changes that look wrong, do NOT accept: `SetupWizard/Playwright` (8.3%,135> code block now dark-on-dark / illegible — judge flagged `regression`), `Card/Compact` (5.1%, title136> clipped) …137> **1. Intended changes (11)** — content changed, looks correct, accept candidates: `Hero/Default` (14%,138> new headline copy), …139> **2. Cosmetic reflow (9)** — real pixels, vertical shift only: `EventStatusCard/All Variants` (4.1%,140> rows shifted ~5px), `TestingInit/Playground` (3.7%), …141> **3. Chart anti-aliasing noise (6)** — sub-0.4% edge jitter, safe to accept: `FunnelChart/Smaller142> Screen` (3.2%), `UpliftChart` (single 1px mark), …143> **New stories (12)** — first baseline, nothing to compare: `Button/AllVariants`, …144145Never accept from inside the triage step — surface the buckets and let the human decide, or do it146explicitly in recipe 3.147148## Recipe 2 — "Summarize the visual regressions"149150Same read, but output the changes that need a human — the ⚠️ regressions first, then the intended151content changes — in a PR-comment shape, one line each, no reflow/noise. This is the comment to drop on152the PR:153154> 🔎 **Visual review — 1 regression, 2 intended** (of 67 flagged; 64 reflow/noise, listed below the fold)155> - ⚠️ `SetupWizard/Playwright` — code block dark-on-dark, illegible (8.3%, judge: regression)156> - `Pricing/Card` — CTA button color changed blue→green (12.4%)157> - `Nav/Header` — logo 8px larger (3.1%)158159## Recipe 3 — "Accept all the new baselines"160161When the changes are all intended (a deliberate restyle) or all noise **and you've confirmed no162regression is hiding in the list** (bucket ⚠️ empty), advance every changed story's baseline in one call:163164```165accept_build { prNumber: 123 }166```167168Don't let "the headline change is intended" halo onto the whole build — a global CSS or theme change169sweeps into stories the PR never meant to touch, and "the PR caused it" is not "the PR intended it."170Each changed story earns its bucket on its own before-and-after.171172For a targeted accept (some real, some not), loop `review_diff` per `diffResultId` with173`accept` / `ignore` / `deny` instead — accept the intended ones, ignore the noise, leave real174regressions for a human.175176## Recipe 4 — "Put the before/after in the PR"177178Keep the human in the PR instead of sending them to the dashboard. After you've triaged, post the179changed stories inline:180181- **The fastest single image:** `render_diff_image` `which: "before_after"` gives you one PNG, before and182 after side by side, cropped to the changed region (one crop per region, stacked, if the story moved in183 several far-apart places) — the least to eyeball. Save it and attach it.184- **Downloadable files / durable links:** `get_diff` returns presigned `baselineUrl` / `candidateUrl` /185 `diffUrl`. Download them (`curl -L "$url" -o before.png`) to attach to the PR, or drop the build link186 and the URLs into a comment. Always include the build link (`https://uiverify.ai/builds/<id>`) so the187 reviewer can open the full triptych.188189A good PR comment: the one-line-per-regression summary from Recipe 2, the before/after image for the190regressions, and the build link. Post it, don't make them go looking.191192## Recipe 5 — "What did this whole PR do to the UI?"193194`get_build` answers one commit — *is anything unreviewed on this build*. It does **not** prove the195**whole PR** did what you intended, and it's blind to two things by construction: a story you **added and196accepted earlier in the PR** (the latest build renders it clean, so it never shows as changed) and a197**removed** story (a deleted or renamed baseline — no build renders it, so no per-build diff flags it).198`get_pr_changeset` is the only surface that catches both, so run it before you call a PR done.199200Pull it for the PR and read the whole head-vs-base picture:201202```203get_pr_changeset { prNumber: 123 } → new / changed / removed vs the base branch204list_pr_stories { prNumber: 123, kind: "removed" } → page any one bucket205```206207Hold every entry to one bar: **can you attribute it to something this PR's diff actually did?**208209- **Yes, and it's correct** → the intended visual impact of the PR.210- **A change you can't attribute to your own diff** → stop. Don't accept it, don't dismiss it as flake,211 don't "re-run and see." Say so and flag it for a human — the likely cause is a baseline that moved when212 it shouldn't have, which is silent by construction.213- **A `removed` story you didn't intend** → an accidental deletion (or an unintended rename, which reads214 as a remove plus an add). Flag it loudly; don't let a green check ship it.215216The changeset is GA — no flag to enable, and on a **public** project anyone can read it for a build217without logging in.218219## Recipe 6 — "Answer or resolve a review comment"220221When a reviewer's note is a question you can answer, or points at something you just fixed, close the loop222from the agent instead of making them chase you. Read the thread with `list_comments`, then:223224- **Reply in the thread** — `post_comment { diffResultId, body, parentId }` where `parentId` is the root225 comment's `id` (a reply inherits the root's side and needs no anchor of its own). Use it to answer226 "why did this move?" with the diff you made, or to confirm "fixed in the next push."227- **Flag a regression back** — `post_comment { diffResultId, body, anchor? }` as a new root, to point the228 reviewer at a story you're leaving for them (pair it with the ⚠️ bucket from Recipe 1).229- **Resolve** — `resolve_comment { commentId, resolved: true }` once the note is addressed (you made the230 change it asked for, or answered the question). Resolve **before** you accept: an open thread makes231 `accept_build` / `review_diff` refuse that story. Only reach for this when the thread is genuinely done;232 the open comment is the signal that stops a premature accept.233234Your key authors comments as the **agent**, and can only edit/delete comments it authored — never touch a235human's comment.236237## Passed build? You can still show the pixels238239A build with no changes shows no triptych — but the components still rendered, and "nothing changed" is240only trustworthy if you can see it. **Enumerate the unchanged set** with `list_build_stories { status:241"unchanged" }` (page it on the returned `nextCursor`), then pull any story's current image by id:242`get_diff { buildId, storyId }` for its baseline URL, or `render_diff_image { storyId, which: "baseline" }`243for the pixels. Use it to244confirm a component looks right on a green build, or to hand the reviewer "here it is, identical to245baseline" without opening the dashboard.246247## Guardrails248249- **Read before you write.** Always `get_build` (and `render_diff_image` for anything ambiguous) before250 `review_diff` / `accept_build`. Don't accept a build you haven't looked at.251- **Compare before-and-after, never the after alone.** For any story that changed content, render252 `which: "baseline"` AND `which: "candidate"` and look at both — the diff mask shows where, the pair253 shows whether it got worse (contrast/legibility, clipping, layout). "It has colours / it moved" is not254 "it's better."255- **The AI judge's `regression` is a signal to trust by default.** Overriding it needs a concrete reason256 from the before/after that refutes its `aiFlagReason`, not a hand-wave. Attributable-to-this-PR is not257 a reason to dismiss it.258- **Bulk-accept is a baseline change.** `accept_build` makes the candidate the new truth for every259 changed story — only reach for it when you've confirmed there's no real regression hiding in the list.260- **An unresolved comment blocks the accept.** `get_build`'s `comments.unresolved > 0` means a human left261 a note you haven't read — `list_comments` it and honor it before `review_diff` / `accept_build`. A262 reviewer commenting "don't accept this" that an agent bulk-accepts anyway is exactly the failure this263 count exists to prevent.264- **Distinguish "new story" from "changed story."** A first-baseline story has nothing to diff; it's not265 a regression, just needs a baseline. Bucket it separately.266267## Examples268269### Example 1: Triage the build for a pull request270271The user says: "Triage the UI Verify build for PR 123."272273```274get_build { prNumber: 123 }275render_diff_image { diffResultId: "<diffResultId from get_build>", which: "before_after" }276```277278Bucket each changed story as a regression, cosmetic reflow or rendering noise from its before-and-after, then report the regressions by story name.279280### Example 2: Accept the intended changes281282The user says: "Those all come from the new button style, accept them."283284```285accept_build { prNumber: 123 }286```287288Only after every changed story was looked at and none is a regression. For a mixed build, call `review_diff { diffResultId: "<id>", decision: "accept" }` for each intended story instead.289290## Limitations291292- Needs a UI Verify account and a project whose CI uploads builds with the `uiverify` CLI (Storybook, Playwright or Vitest); with no build there is nothing to triage.293- Needs network access to the hosted MCP server at `https://uiverify.ai/mcp` and a one-time browser login, which the agent cannot complete on its own.294- AI verdict fields appear only when AI review is on for the project, and the comment tools only when the team has image comments enabled.295- Over raw HTTP the image tools return MCP image blocks a shell cannot show; use a native MCP client, or `get_diff` for image URLs.296297## Security & Safety Notes298299- `review_diff` (accept) and `accept_build` change the project's baselines on the service, and later builds are compared against them. Look at the before and after first, and never bulk-accept a build that may hide a regression.300- The server refuses accept and ignore while a story has an unresolved review comment; read it with `list_comments` and honour it.301- `get_diff` returns presigned image URLs that work for anyone holding them until they expire. Share them only where the team would share the screenshot.302- Each person connects with their own OAuth login; there is no API key in `.mcp.json`.303304## Catalog adaptation305306Copied from the official MIT source above at commit `181d9e4` with its instructions unchanged; this catalog adds When to Use This Skill, Examples, Limitations and Security & Safety Notes.