Agent Skills › liaohch3/claude-tap › screenshot-validation

screenshot-validation

GitHub

验证PR证据截图和Viewer HTML的质量。检查图片尺寸、大小及空白度，并使用Playwright验证HTML渲染正确性，防止CI失败或误导性证据。

.agents/skills/screenshot-validation/SKILL.md liaohch3/claude-tap

Trigger Scenarios

添加或修改 .agents/evidence/pr/ 或 .agents/recordings/ 下的图像后生成新的 viewer HTML 文件后

Install

npx skills add liaohch3/claude-tap --skill screenshot-validation -g -y

More Options

Non-standard path

npx skills add https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/screenshot-validation -g -y

Use without installing

npx skills use liaohch3/claude-tap@screenshot-validation

指定 Agent (Claude Code)

npx skills add liaohch3/claude-tap --skill screenshot-validation -a claude-code -g -y

安装 repo 全部 skill

npx skills add liaohch3/claude-tap --all -g -y

预览 repo 内 skill

npx skills add liaohch3/claude-tap --list

SKILL.md

Frontmatter

{
    "name": "screenshot-validation",
    "description": "Validate screenshot and viewer HTML quality for PR evidence. Run this after adding or modifying images under .agents\/evidence\/pr\/ or .agents\/recordings\/, or after generating a new viewer HTML file. Combines image quality checks (resolution, blankness, file size) with Playwright-based viewer rendering verification.",
    "user_invocable": true
}

Screenshot Validation

Validate that evidence images and viewer HTML files meet quality standards before committing. This catches issues that would otherwise fail CI or produce misleading PR evidence.

Image quality check

Checks PNG/JPG/GIF/WEBP files for:

Minimum dimensions: 400x400 pixels (hard fail)
Desktop viewport width: >= 1280px (warning if narrower)
File size: <= 5MB (warning if larger)
Blankness detection (PNG only): fails if > 90% of pixels are white/transparent

Run on specific files or directories

uv run python scripts/check_screenshots.py .agents/evidence/pr/
uv run python scripts/check_screenshots.py .agents/recordings/
uv run python scripts/check_screenshots.py path/to/specific-image.png

Run on git-staged images

scripts/check_screenshots.sh

This shell wrapper automatically finds staged PNG/JPG files and runs the quality check on them — useful as a pre-commit sanity check.

Viewer HTML rendering verification

Uses Playwright (headless Chromium) to verify that generated viewer HTML files actually render correctly — not just raw JSON or Python errors.

Checks:

No JavaScript errors on page load
Normal traces render a sidebar with entries and a detail panel
Empty embedded traces render the explicit "No API calls captured" state
Body text doesn't contain raw JSON dumps or Python tracebacks

Run

uv run python scripts/verify_screenshots.py .traces/trace_*.html

Requires Playwright to be installed (uv pip install playwright && playwright install chromium).

Typical workflow

After generating new evidence for a PR:

# 1. Check image quality
uv run python scripts/check_screenshots.py .agents/evidence/pr/

# 2. If you generated new viewer HTML, verify it renders
uv run python scripts/verify_screenshots.py .traces/trace_*.html

# 3. If all passes, stage and commit
git add .agents/evidence/pr/

Fixing common failures

Failure	Fix
`very small image (WxH; minimum is 400x400)`	Retake screenshot at a larger viewport or higher resolution
`narrow desktop viewport (Wpx < 1280px)`	Resize browser window to >= 1280px wide before capturing
`mostly blank/white image`	Ensure the screenshot captures actual content, not an empty page
`No sidebar — viewer not rendered`	Viewer HTML is broken; regenerate from trace JSONL
`JS errors`	Check viewer.html for syntax errors in embedded data