verify-ui

A skill for coding agents (Claude Code, Codex, and others). It makes the agent prove a UI change with a short screen recording instead of just saying "it works". Every clip has a title card, real clicks, and a red box on each changed element. A validator then checks the delivered video frames and rejects the clip if the boxes or cards are not really in them.

The clip above is the skill's own smoke test, recorded and validated by the harness itself.

Install

You need macOS, Google Chrome, ffmpeg, python3, node, and the Playwright CLI at this exact version (the recording commands are tested against it only):

npm install -g @playwright/cli@0.1.17

Then install the skill (works for every agent the Skills CLI supports):

npx skills add arDaraz/verify-ui --skill verify-ui \
  --global --agent claude-code --agent codex

Check it worked - the last line must say all checks passed:

bash ~/.agents/skills/verify-ui/scripts/validate.sh

Use

Start your app, then ask your agent:

/verify-ui the renamed total column on the invoices page

The agent opens its own Chrome window (separate from your personal Chrome), navigates there off camera, records a short annotated clip, validates it, and replies with a screenshot and the video path:

Recording: /path/to/your-project/.playwright-cli/videos/verify-ui-total-column.mp4

For an app that is already running and needs no login, that is everything.

Teach it your project

Everything project-specific lives in one folder in your project. The skill never writes there, it only runs your scripts:

your-project/
└── .verify-ui/
    ├── config.sh            # VUI_BASE_URL="http://localhost:8080"
    ├── hooks/
    │   ├── ensure-servers   # script: exit 0 if the app is up, exit 2 + reason if not
    │   └── ensure-auth      # script: get the browser logged in (see docs/login.md)
    └── app/
        └── routes.md        # optional notes for the agent: routes, test users, quirks

A minimal ensure-servers:

#!/usr/bin/env bash
curl -sf -o /dev/null -m 5 "http://localhost:8080" && exit 0
echo "App is not running. Start it with: npm run dev" >&2
exit 2

Make hooks executable (chmod +x), or the skill skips them. If your app needs a login, follow docs/login.md - a 5-minute setup.

Cleanup

Crashed runs and bare playwright-cli calls can leave browsers behind. The doctor removes exactly those and nothing else - it acts only on proof (a daemon whose socket file is gone, whose start folder was deleted, an ownerless "default" browser older than 12 hours, or a browser whose daemon died). Named project sessions are never touched.

bash ~/.agents/skills/verify-ui/scripts/vui-doctor.sh          # report only
bash ~/.agents/skills/verify-ui/scripts/vui-doctor.sh clean    # fix what was flagged

Or ask your agent: /verify-ui doctor.

When something fails

You see	Do this
playwright-cli not found	npm install -g @playwright/cli@0.1.17. Custom location? Set VUI_PW_DIR to its folder.
PARITY NOT REACHED or below the 1280px desktop-layout floor	The Chrome window cannot show a 1280px page. Make the window bigger or use a larger display.
Browser session stuck or an old skill browser lingers	Run the doctor (see Cleanup). If that is not enough: pw.sh kill-all closes the skill's browsers for ALL projects, then run your ensure-auth hook.
Clip rejected with DO NOT REPORT	The validator names the exact reason. The agent must fix it and re-record. This is the skill working as intended.
download-proof fails	Read the printed reason. could not parse usually means the xlsx package is missing in your project (npm i -D xlsx).

Recordings land in <your-project>/.playwright-cli/videos/. Add .playwright-cli/ to your .gitignore.

License

MIT