uiverify-triage-visual-changes – Design & UI skill for AI agents

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 as advisory context, then independently inspect the evidence 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.

-

… (full content is in the download package)