Skip to content
Skills Library
Programming · Testing

visual-feedback-loop

/visual-feedback-loop

AI agent visual feedback loop for any web app. Use when iterating on visual code (UI, canvas, 3D, SVG, charts, animations) and you need to SEE the rendered result to evaluate quality. Covers: dev-screenshot API pattern (GET trigger → SSE → client capture → POST back → file saved), parameterized rendering, metadata sidecars, visual regression with pixel diff, WebMCP tool registration, and console fallbacks. Activate on: 'take a screenshot', 'show me the render', 'visual QA', 'compare before/after', 'pixel diff', or any iterative visual work where the agent needs to inspect rendered output.

Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

AI agent visual feedback loop for any web app. Use when iterating on visual code (UI, canvas, 3D, SVG, charts, animations) and you need to SEE the rendered result to evaluate quality. Covers: dev-screenshot API pattern (GET trigger → SSE → client capture → POST back → file saved), parameterized rendering, metadata sidecars, visual regression with pixel diff, WebMCP tool registration, and console fallbacks. Activate on: 'take a screenshot', 'show me the render', 'visual QA', 'compare before/after', 'pixel diff', or any iterative visual work where the agent needs to inspect rendered output.

Triggers from the description

take a screenshotshow me the rendervisual QAcompare before/afterpixel diff
Original author description

AI agent visual feedback loop for any web app. Use when iterating on visual code (UI, canvas, 3D, SVG, charts, animations) and you need to SEE the rendered result to evaluate quality. Covers: dev-screenshot API pattern (GET trigger → SSE → client capture → POST back → file saved), parameterized rendering, metadata sidecars, visual regression with pixel diff, WebMCP tool registration, and console fallbacks. Activate on: 'take a screenshot', 'show me the render', 'visual QA', 'compare before/after', 'pixel diff', or any iterative visual work where the agent needs to inspect rendered output.

How it works

  1. How It Works
  2. Usage
  3. Rules
  4. Troubleshooting
  5. Setup
Original SKILL.md headings · 101 lines, 591 words
SKILL.md preview
---
name: visual-feedback-loop
description: "AI agent visual feedback loop for any web app. Use when iterating on visual code (UI, canvas, 3D, SVG, charts, animations) and you need to SEE the rendered result to evaluate quality. Covers: dev-screenshot API pattern (GET trigger → SSE → client capture → POST back → file saved), parameterized rendering, metadata sidecars, visual regression with pixel diff, WebMCP tool registration, and console fallbacks. Activate on: 'take a screenshot', 'show me the render', 'visual QA', 'compare before/after', 'pixel diff', or any iterative visual work where the agent needs to inspect rendered output."
---

# Visual Feedback Loop

Capture, inspect, and compare visual output from a running web app during iterative development.

## How It Works

```
Agent (CLI)                     Server                            Browser
     |--- GET /api/dev-screenshot -->|--- SSE "capture" ----------->|
     |    ?param=value               |                              |-- capture canvas
     |                               |<-- POST { dataUrl } ---------|
     |                               | writes:
     |                               |   .screenshots/{UTC}.webp
     |                               |   .screenshots/{UTC}.json  (metadata)
     |                               |   .screenshots/latest.webp (convenience copy)
     |<-- { ok, path, latest } ------|
```

Agent can't access the browser directly. Server relays: GET triggers → SSE notifies browser → browser captures and POSTs back → GET resolves.

## Usage

Capture current view:
```bash
curl http://localhost:3000/api/dev-screenshot
```

Capture with params (app-specific — browser client interprets them):
```bash
curl 'http://localhost:3000/api/dev-screenshot?component=header&theme=dark'
curl 'http://localhost:3000/api/dev-screenshot?letter=б&depth=0.8'
```

Then read the result. Response includes `path` (timestamped file) and `latest` (convenience copy):
```
Read .screenshots/latest.webp
```

### Visual Regression (pixel diff)

Compare against a ground truth screenshot using ImageMagick:
```bash
magick compare -metric RMSE .screenshots/ground-truth.webp .screenshots/latest.webp .screenshots/diff.webp
```

RMSE output: `0.01` = ~1% difference (rendering noise), `0.03+` = visible change. Save diff image for inspection.

### Metadata Sidecars

Each screenshot gets a JSON sidecar with the same UTC timestamp:
```json
{
  "timestamp": "2026-02-25T08:22:12.655Z",
  "git": { "commit": "0a5726f", "dirty": true },
  "params": { "letter": "о", "chamferModel": "membrane", "cameraView": "front" },
  "format": "webp",
  "file": "2026-02-25T08-22-12-655Z.webp"
}
```

Use this to trace which code state + params produced a screenshot — critical when iterating across multiple code changes.

### A/B Comparison Workflow

1. Capture ground truth: `curl '...?letter=о'` → note the `{UTC}.webp` filename
2. Make code changes, refresh browser
3. Capture again: `curl '...?letter=о'`
4. Diff: `magick compare -metric RMSE .screenshots/{ground-truth}.webp .screenshots/latest.webp .screenshots/diff.webp`
5. Read diff image + check RMSE value

Console fallback: `await window.__takeDevScreenshot()`

## Rules

1. **Always `Read .screenshots/latest.webp` after capture.** Never assume the render is correct.
2. **Browser tab must be open** at the app URL. Timeout = no SSE connection = ask user to refresh.
3. **One request at a time.** Second GET returns 409. Wait for first to resolve (success/error/10s timeout).
4. **Errors return instantly**, not as timeouts. Client POSTs errors back: `{ ok: false, error: "..." }`.
5. **HMR resilience.** Store server-side SSE state on `globalThis` so it survives module reloads. EventSource auto-reconnects on the client. If screenshots still fail after code changes, ask user to refresh.
6. **HMR does NOT update offscreen render paths.** Closures in `useEffect` capture stale module references. After code changes to rendering logic, always ask user to **hard refresh** (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux).

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Timeout: browser did not respond | Open/refresh app in browser |
| 409: already in progress | Wait for timeout (10s) |
| Black/empty image | Refresh browser tab |
| Works once, then times out | HMR broke SSE — refresh tab (rare if using globalThis pattern) |
| Code changes not reflected in screenshots | HMR doesn't update offscreen renderers — hard refresh (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux) |
| Comparing screenshots from different code states | Check JSON sidecar for git commit + dirty flag |

See [references/errors.md](references/errors.md) for full error reference.

## Setup

The pattern is framework-agnostic — it only requires an HTTP server with GET/POST routes and SSE. The reference implementation uses Next.js, but the same approach works with Express, Fastify, Hono, Vite dev server plugins, or any Node.js HTTP server.

See [references/setup-nextjs.md](references/setup-nextjs.md) for a complete Next.js implementation (API route, SSE listener, WebMCP registration). Adapt the route handler to your framework — the client-side SSE listener and capture logic are identical regardless of server framework.
Files in this package (3)
  • SKILL.md 5 KB
  • references/errors.md 1 KB
  • references/setup-nextjs.md 7 KB

Versions

RepositoryScoreLicence
This page · vladmdgolam/agent-skills100MIT
mcorbett51090/ravenclaude100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ac5118a310bc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100doncheli-visual-test
    Run visual regression tests by comparing UI screenshots against baselines. Activate when user mentions "visual test", "screenshot", "UI regression", "visual diff", "pixel diff", "visual snapshot".
  • 100visual-review
    Two visual modes — render a PR diff as an HTML page with each hunk annotated by principle, or check a UI change in a real browser (screenshots, console, network). Use for a visual/HTML diff report, "check the UI", or "screenshot before/after". Don't use for text-only feedback…
  • 100testing-visual-regression
    Detect visual changes in UI components using screenshot comparison. Use when detecting unintended UI changes or pixel differences. Trigger with phrases like "test visual changes", "compare screenshots", or "detect UI regressions".
  • 100testing-visual-regression
    Detect visual changes in UI components using screenshot comparison. Use when detecting unintended UI changes or pixel differences. Trigger with phrases like "test visual changes", "compare screenshots", or "detect UI regressions".
  • 100visual-diff
    Visual Regression Testing — screenshot comparison before and after changes. Use when user wants to check for visual regressions, compare UI changes, or verify CSS/layout changes didn't break anything.
  • 100browser-screenshot
    Take a screenshot of the running web application for visual verification of UI/CSS changes. Use when iterating on frontend changes and need to see the result.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.