| name | visual-debug |
| description | This skill should be used when the user provides screenshots, videos, screen recordings, or mentions visual bugs, UI glitches, layout shifts, animation issues, or visual regressions. Analyzes media files to create annotated montage grids with diff overlays for visual debugging. |
| allowed-tools | ["Bash","Read","Glob"] |
| license | MIT |
| compatibility | Claude Code >= 1.0, ffmpeg (optional, for video) |
| metadata | {"author":"hoangsa","version":"0.0.1","category":"debugging","spec":"agentskills.io/1.0"} |
Analyze screenshots, screen recordings, and video files to identify visual bugs, UI glitches, layout shifts, animation issues, and visual regressions. Produces annotated montage grids with diff overlays.
- User shares screenshots, screen recordings, or video files
- "There's a UI glitch in my app"
- "This animation looks wrong"
- "Something changed visually between versions"
- "The layout shifts when I scroll"
- Investigating layout shifts, rendering bugs, or visual regressions
Identify media files in user input by extension. Classify as image or video.
Supported formats:
- Video:
.mp4, .mov, .webm, .avi, .mkv
- Image:
.png, .jpg, .jpeg, .webp, .gif
For detailed format info and ffmpeg requirements, see references/supported-formats.md.
Read image files directly using Claude's native vision capability — no processing needed. Analyze visually and report findings.
1. Check ffmpeg availability: `hoangsa-cli media check-ffmpeg`
2. If not available, install: `hoangsa-cli media install-ffmpeg` (show platform-specific instructions if auto-install fails)
3. Determine output directory:
- If the environment variable `SESSION_DIR` is set: `OUTPUT_DIR=$SESSION_DIR/attachments/media-analysis`
- Otherwise: `OUTPUT_DIR=/tmp/hoangsa-debug-`
4. Extract frames, then build both montages:
- `hoangsa-cli media frames --output-dir $OUTPUT_DIR/frames`
- `hoangsa-cli media montage $OUTPUT_DIR/frames --timestamps --output $OUTPUT_DIR/montage.png`
- `hoangsa-cli media diff $OUTPUT_DIR/frames --output $OUTPUT_DIR/diff-montage.png`
5. Read output files:
- `$OUTPUT_DIR/montage.png` — annotated grid with timestamps
- `$OUTPUT_DIR/diff-montage.png` — red overlay showing frame-to-frame changes
6. Analyze both images to identify UI changes across frames, visual regressions, animation issues, and layout shifts
Report findings with timestamps referencing specific frames visible in the montage grid. Include:
- **What changed**: specific UI elements affected
- **Where**: frame numbers and timestamps from the montage
- **Severity**: cosmetic, functional, or blocking
- **Suggested fix**: if the root cause is identifiable from the visual evidence
| Rule | Detail |
|------|--------|
| **Always classify first** | Identify media file type (image vs video) before processing |
| **ffmpeg required for video** | Confirm ffmpeg is available before video analysis |
| **Timestamp references** | Always reference specific frames and timestamps from montage |
| **Severity rating** | Every finding must include severity: cosmetic, functional, or blocking |
- **`references/supported-formats.md`** — Supported video/image formats, ffmpeg requirements, output artifacts, and analysis capabilities
