szoloth/screenshot

Universal Screenshot Skill

A unified screenshot tool that captures any source (web, desktop, images) with viewport presets, element targeting, batch capture, and auto-upload.

Agent Behavior Rules

DO:

• Detect source type automatically from input (URL, app name, file path)
• Use --mobile, --tablet, or --desktop for web captures
• Wait for networkidle before capturing web pages
• Use --markdown when user wants output for PRs or docs
• Use --upload when user wants shareable links
• Run pre-flight checks before first capture

DO NOT:

• Assume viewport without user context (default to desktop for web)
• Use --full unless explicitly asked for full-page/scroll capture
• Skip the networkidle wait on dynamic pages
• Upload without asking if destination is unclear

Source Detection

| Input Pattern | Source Type | Tool Used | |---------------|-------------|-----------| | http://, https://, file:// | Web | playwright-cli | | App name (e.g., "Figma", "Xcode") | Desktop | OS screenshot | | .png, .jpg, .pdf path | Image | sips/ImageMagick | | Figma URL (figma.com/...) | Figma | Web capture |

Quick Reference

# Set skill path
export SCREENSHOT_SKILL="$HOME/.claude/skills/screenshot"

# Basic web capture
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" https://example.com

# Mobile viewport with selector
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" https://example.com --mobile --selector ".hero"

# Desktop app capture
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" --app "Figma"

# Capture existing image region
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" image.png --crop 100,100,800,600

# Batch capture with multiple viewports
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" --batch urls.txt --viewports mobile,tablet,desktop

# Capture with upload and markdown
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" https://example.com --upload --markdown

Command Options

Viewport Presets (web only)

| Flag | Dimensions | Use Case | |------|------------|----------| | --mobile | 375x812 | iPhone viewport | | --tablet | 768x1024 | iPad viewport | | --desktop | 1440x900 | Default for web | | --size WxH | Custom | Any dimensions | | --full | Full scroll | Full page capture |

Element Targeting (web only)

| Flag | Description | |------|-------------| | --selector ".class" | CSS selector | | --text "Button" | Text content match | | --id "element-id" | Element ID |

Desktop App Capture

| Flag | Description | |------|-------------| | --app "Name" | Capture app by name | | --window "Title" | Specific window title | | --active | Capture active window | | --region x,y,w,h | Capture region |

Image Processing

| Flag | Description | |------|-------------| | --crop x,y,w,h | Crop region | | --resize WxH | Resize output | | --format png/jpg | Output format |

Batch Capture

| Flag | Description | |------|-------------| | --batch file.txt | URLs/apps from file | | --viewports m,t,d | Capture all viewports |

Output Options

| Flag | Description | |------|-------------| | --output dir/ | Output directory | | --name prefix | Filename prefix | | --upload | Upload to 0x0.st | | --upload gist | Upload to GitHub Gist | | --markdown | Generate markdown table | | --copy | Copy result to clipboard |

Pre-flight Checks

The tool automatically:

1. Checks for playwright-cli availability
2. Installs if missing: npm install -g @playwright/mcp@latest
3. Verifies OS screenshot tools on desktop captures
4. Checks for curl (uploads) and gh CLI (gist)

Vercel Protection Handling

For .vercel.app URLs returning 401/403:

1. Tool detects protected deployment
2. Prompts for bypass token or suggests alternatives
3. Can use vercel inspect if Vercel CLI is available

Output Examples

Single capture:

Screenshot saved: ~/Downloads/example-desktop-1706900000.png

With upload:

Screenshot saved: ~/Downloads/example-desktop-1706900000.png
Uploaded: https://0x0.st/abc123.png

Markdown output:

| Viewport | Screenshot |
|----------|------------|
| Desktop | ![desktop](https://0x0.st/abc123.png) |
| Mobile | ![mobile](https://0x0.st/def456.png) |

Error Handling

| Error | Resolution | |-------|------------| | playwright-cli not found | Auto-installs via npm | | Element not found | Verify selector, try broader match | | 401/403 on URL | Protected deployment, see above | | App not found | Check app name, ensure visible | | Upload failed | Retry or try different host |

Integration with PR Workflow

# Capture staging vs production
python3 "$SCREENSHOT_SKILL/scripts/screenshot.py" https://staging.example.com --upload --markdown > screenshots.md

# Append to PR
gh pr edit --body-file <(cat <(gh pr view --json body -q .body) screenshots.md)