How do I install the Visual Diff skill?

Run npx skillmds@latest add keybase/visual-diff in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Visual Diff safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Visual Diff?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Visual Diff free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Visual Diff?

keybase (@keybase) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Visual Diff by keybase — Agent Skill

Name: Visual Diff
Author: keybase

Visual Diff

This skill should be used when the user asks to "compare screenshots", "visual diff", "check for visual regressions", "before and after screenshots", "did the UI change", or mentions comparing the desktop app UI between branches or before/after a change. Also triggered by "take baseline", "take current", or "compare against baseline".

keybase c6e481c 2.6 KB Updated Sep 17, 2026

File contents

Run a visual regression test by capturing baseline and current screenshots of the app, then comparing them with ImageMagick to find pixel-level differences.

Workflow

Prerequisites

App running with KB_ENABLE_REMOTE_DEBUG=1 yarn desktop:start:hot
ImageMagick installed (brew install imagemagick)

Option A: Automated Scripts (preferred)

# Baseline (on base branch, app running)
cd shared && node perf/visual-diff-take.js baseline

# Current (on feature branch, app restarted)
cd shared && node perf/visual-diff-take.js current

# Compare
cd shared && ./perf/visual-diff-compare.sh

Option B: Playwright MCP (manual)

Close the DevTools tab (browser_tabs action=close index=0), select the app tab.
Navigate to each tab (People, Chat, Files, Crypto, Teams, Git, Devices, Settings) via browser_snapshot + browser_click.
Take screenshots to /tmp/visual-diff/baseline/ or /tmp/visual-diff/current/.
Run cd shared && ./perf/visual-diff-compare.sh.

Viewing Results

After comparison, read the diff images to evaluate:

Resize each diff image for token efficiency:

sips -Z 800 /tmp/visual-diff/diff/<tab>.png --out /tmp/visual-diff-resized/<tab>.png

Use the Read tool to display each resized diff image.

Interpreting Diffs

Red pixels indicate differences between baseline and current screenshots.

Subpixel noise (<200px): Scattered faint red dots from font antialiasing. Safe to ignore.
Dynamic content: Avatars, timestamps, badges change between runs. Safe to ignore.
COLOR REGRESSION: Entire icons or text areas are solid red — colors changed (e.g. icon went blue → gray). Investigate.
SIZE/POSITION REGRESSION: Red outlines or doubled shapes — something shifted. Common cause: Box2 adding alignSelf: 'center' where old code used <div>.
Rule of thumb: Clean text labels + solid red icons = real bug, not noise.

Typical Session

User says "take baseline" → run the baseline capture step.
User makes code changes and restarts app.
User says "compare" or "take current" → run the current capture + comparison.
Display diff images and summarize findings: which tabs changed, whether changes look intentional or are regressions.

---name: visual-diffdescription: This skill should be used when the user asks to "compare screenshots", "visual diff", "check for visual regressions", "before and after screenshots", "did the UI change", or mentions comparing the desktop app UI between branches or before/after a change. Also triggered by "take baseline", "take current", or "compare against baseline".---Run a visual regression test by capturing baseline and current screenshots of the app, then comparing them with ImageMagick to find pixel-level differences.## Workflow### Prerequisites- App running with `KB_ENABLE_REMOTE_DEBUG=1 yarn desktop:start:hot`- ImageMagick installed (`brew install imagemagick`)### Option A: Automated Scripts (preferred)```bash# Baseline (on base branch, app running)cd shared && node perf/visual-diff-take.js baseline# Current (on feature branch, app restarted)cd shared && node perf/visual-diff-take.js current# Comparecd shared && ./perf/visual-diff-compare.sh```### Option B: Playwright MCP (manual)1. Close the DevTools tab (`browser_tabs` action=close index=0), select the app tab.2. Navigate to each tab (People, Chat, Files, Crypto, Teams, Git, Devices, Settings) via `browser_snapshot` + `browser_click`.3. Take screenshots to `/tmp/visual-diff/baseline/` or `/tmp/visual-diff/current/`.4. Run `cd shared && ./perf/visual-diff-compare.sh`.## Viewing ResultsAfter comparison, read the diff images to evaluate:1. Resize each diff image for token efficiency: ``` sips -Z 800 /tmp/visual-diff/diff/<tab>.png --out /tmp/visual-diff-resized/<tab>.png ```2. Use the Read tool to display each resized diff image.## Interpreting DiffsRed pixels indicate differences between baseline and current screenshots.- **Subpixel noise** (<200px): Scattered faint red dots from font antialiasing. Safe to ignore.- **Dynamic content**: Avatars, timestamps, badges change between runs. Safe to ignore.- **COLOR REGRESSION**: Entire icons or text areas are solid red — colors changed (e.g. icon went blue → gray). Investigate.- **SIZE/POSITION REGRESSION**: Red outlines or doubled shapes — something shifted. Common cause: `Box2` adding `alignSelf: 'center'` where old code used `<div>`.- **Rule of thumb**: Clean text labels + solid red icons = real bug, not noise.## Typical Session1. User says "take baseline" → run the baseline capture step.2. User makes code changes and restarts app.3. User says "compare" or "take current" → run the current capture + comparison.4. Display diff images and summarize findings: which tabs changed, whether changes look intentional or are regressions.

Frequently asked questions