| name | screenshot-loop |
| description | Visual QA loop for UI development — build, screenshot, compare to reference, identify delta, prompt correction, repeat. Formalizes the self-review cycle and defines when to disable it. |
| version | 0.1.0 |
| level | 2 |
| triggers | ["screenshot loop","visual review","compare to reference","self review UI","/screenshot-loop"] |
| context_files | ["context/project.md"] |
| steps | [{"name":"Setup","description":"Confirm Puppeteer is available or identify fallback. Establish reference screenshots and naming convention."},{"name":"Build Pass","description":"Write the initial implementation."},{"name":"Screenshot and Compare","description":"Take section-by-section screenshots. Compare against reference. Identify specific deltas."},{"name":"Correct","description":"Issue targeted correction prompts for each delta. One delta per prompt."},{"name":"Final Pass","description":"Screenshot the corrected result. Confirm delta is closed. Repeat if needed."}] |
Screenshot Loop Skill
Formalize the visual QA cycle. Build, screenshot, compare, correct, repeat. The loop closes the gap between what Claude thinks it built and what the reference actually looks like.
What Claude Gets Wrong Without This Skill
Claude writes code and declares it done. It has no way to see the result without a screenshot mechanism. Without one, it is writing blind — making visual decisions based on mental simulation of CSS properties, not actual rendered output.
The second failure: when a screenshot loop is set up but not managed, it becomes a liability. Claude takes a screenshot, sees it does not perfectly match the reference, and issues another correction. And another. And another. It spirals because the goal (exact pixel match) is unachievable and the loop has no exit condition. This skill defines the exit condition.
Setup
With Puppeteer (preferred)
Puppeteer must be installed for automated screenshots:
npm install puppeteer
npx puppeteer install chrome
Screenshot configuration in CLAUDE.md (add to project CLAUDE.md, not global):
## Screenshot Workflow
- Tool: Puppeteer
- Output dir: temp_screenshots/
- Naming: [section]-[pass]-[timestamp].png
- On session start: delete old screenshots from temp_screenshots/
- On animated elements: DO NOT screenshot — review manually
Without Puppeteer (fallback)
If Puppeteer is not available, use browser DevTools:
- Open the page in Chrome/Firefox
- F12 → Console → Ctrl+Shift+P → "Capture full size screenshot"
- Drag the screenshot into the Claude Code session
- Proceed with manual comparison
The loop still works without Puppeteer — it just requires manual screenshot capture at each step.
Phase Gates
Setup — hard gate
Before the first implementation pass:
- Confirm screenshot method (Puppeteer or manual)
- Take a screenshot of the reference (the inspiration site or mockup)
- Store as
temp_screenshots/reference-[section].png
- Set naming convention:
temp_screenshots/[section]-v[N].png for each pass
Do not start building without a reference screenshot in place. Without it, there is nothing to compare against.
Build Pass
Write the initial implementation. Do not screenshot during writing — complete the implementation first, then screenshot.
