How to use the Visual QA Verdict agent skill

What does the visual-verdict skill make the agent do?

The skill makes the agent compare a generated UI screenshot against reference images, such as a design mock or a target site. The comparison is returned as a strict JSON verdict that the agent uses to decide what to change next.

The report contains a score from 0 to 100, a verdict of pass, revise or fail, a flag for whether the screenshot matches the intended UI category, a list of concrete visual differences, actionable suggestions tied to those differences, and a short reasoning summary. The target pass threshold is 90 or higher. If the score is below 90, the agent keeps editing and runs the check again before treating the task as complete.

• Inputs: one or more reference image paths, the generated screenshot path, and an optional category hint such as hackernews, sns-feed or dashboard.
• Output: JSON only, with the fields score, verdict, category_match, differences, suggestions and reasoning.
• Differences cover layout, spacing, typography, colors and hierarchy.

How do you install the skill?

The skill ships as a single file, SKILL.md. You can install it in one of two ways, depending on where you use your agent.

Option one is a manual install. Download the ZIP from the skill's page on this directory and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder to limit it to that project.

Option two is to upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the skill there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

What do you need before you start?

The skill needs an agent runtime that supports this skill format and the oh-my-claudecode plugin, because it is invoked as /oh-my-claudecode:visual-verdict. You also need image files for the reference and the generated screenshot.

Pixel-diff tooling such as pixel diff or pixelmatch is optional. It can help you find hotspots when a mismatch is hard to diagnose. The SKILL.md does not specify how to install that tooling, so check its own documentation if you want to use it.

• An agent runtime that supports the skill format and the oh-my-claudecode plugin
• Reference image file(s) and a generated screenshot file
• Optional: pixel-diff tooling (pixel diff or pixelmatch) for debugging

How do you trigger the skill with natural requests?

Ask the agent for a visual task and give it a reference. Make the reference explicit, name the screenshot the agent should compare, and say that you want the check repeated until it clears the threshold. The skill is meant to run inside an edit loop, so the request should describe that loop.

You can also invoke the skill directly with its command when you want a one-off verdict on a specific screenshot.

• "Build this page to match reference.png, then score the screenshot and keep editing until it reaches 90 or higher."
• "Compare my current screenshot with the two mock-ups in the designs folder and list the visual differences."
• "This is a dashboard. Check whether the generated screenshot matches the dashboard style before we continue."

What does a verdict look like in practice?

A typical report looks like the example below. A score of 87 with a revise verdict tells the agent that the core layout is close but style details still differ. The agent then applies the suggested edits, such as adjusting padding or font weight, and runs the check again on the new screenshot.

Treat each difference as a to-do item. The suggestions are written to map back to those differences, which makes the next edit specific.

What are the safety notes?

According to the skill's listing, it runs no scripts and uses no network access. It works by reading the image files you provide and returning a JSON report.

Remember that the score comes from an AI judgment. It is not a validated measurement, so do not rely on it alone for final design sign-off or accessibility audits. Pixel-diff tooling is only an optional debugging aid, and the skill is not designed for pixel-exact output.

• Runs scripts: no
• Uses network: no
• The score is an AI judgment, not a validated measurement

What tips help you get better results?

Always provide at least one reference image, because the skill cannot judge a task that has no visual reference. Give a category hint when you know the UI style, since the category_match field depends on the intended category. Keep the reference and screenshot files at a consistent size so that comparisons are easier to read.

Use the pixel-diff step only when the differences are hard to locate by eye. Keep the skill's verdict as the decision-maker and use the diff to turn hotspots into specific edits.

• Supply at least one reference image every time
• Pass a category_hint such as dashboard or hackernews when the style is known
• Use pixel diff only to localise hotspots, not to decide pass or fail
• Stop only when the newest screenshot scores 90 or higher