screenshotting

Take screenshots to see what's on screen. Triggers on 'screenshot', 'grab a screenshot', 'have a look', 'can you see', 'what does it look like', 'check the screen', 'did that work', 'verify it worked', 'what happened'. AFTER uncertain CLI operations (backgrounded processes, nohup, visual changes), consider capturing to verify state. Captures windows or full screen to files. (user)

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The Screenshotting skill empowers Claude with visual perception of the macOS environment by capturing high-resolution, token-optimized images of specific application windows or the entire screen. Unlike ephemeral browser snapshots, this tool persists captures as files, making it indispensable for visual debugging, verifying the state of background CLI operations, and generating automated technical documentation.

Use Cases

  • Visual Debugging: Capture specific application windows to identify UI glitches, layout inconsistencies, or rendering issues during the development process.
  • CLI State Verification: Proactively take screenshots after executing uncertain or backgrounded terminal commands (like nohup) to verify that the visual output matches expected results.
  • Automated Documentation: Generate persistent image artifacts for step-by-step technical guides, bug reports, or 'before-and-after' comparisons in a project workflow.
  • Cross-App Monitoring: Observe and analyze the state of non-browser applications such as IDEs, terminals, and communication tools that standard web-based tools cannot access.
  • Visual QA: Use automated triggers like 'did that work' to have the agent visually inspect the screen and confirm successful UI interactions or state changes.
namescreenshotting
description>

Screenshotting

Take screenshots to see what's on screen. Captures persist as files (unlike browsermcp snapshots which only exist in context).

Quick Reference

# Capture specific app window
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --app Ghostty

# Capture window by title match
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --app Chrome --title "LinkedIn"

# Capture full screen
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --screen

# List available windows
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --list

# List windows grouped by category
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --categories

# List only browser windows
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --category browsers

# Native resolution (skip resize)
~/.claude/.venv/bin/python ~/.claude/skills/screenshotting/scripts/look.py --app Safari --native

Categories: browsers, terminals, editors, communication, documents, media, other

When to Use

Reactive (user asks):

  • "Have a look at this"
  • "Can you see what's on screen?"
  • "What does it look like?"
  • "Check the browser"

Proactive (verify state):

  • After uncertain CLI operations (did it background?)
  • When tool prompt state is unclear
  • After browsermcp actions when snapshot isn't enough
  • To verify visual changes actually happened

Documentation:

  • Capture steps in a workflow
  • Before/after comparisons
  • Bug evidence with screenshots

When NOT to use:

  • For browser-only tasks where browsermcp snapshot suffices
  • When you just need to describe what's visible (use your existing context)
  • High-frequency captures that would clutter the directory

Resolution Strategy

Default: 1568px max dimension (~1,600 tokens, optimal for API)

Option Tokens Use case
Default (1568px) ~1,600 Full detail, no resize penalty
--max-size 735 ~500 Quick look, text readable
--native varies When original resolution needed

Why 1568px: Images larger than this get resized server-side anyway. Pre-resizing avoids upload latency while getting the same visual fidelity.

Output

Ephemeral (no path): Screenshots go to /tmp/claude-screenshots/ — auto-cleaned by OS, won't clutter project directories:

/tmp/claude-screenshots/2025-12-15-143022-chrome.png

Persistent (explicit path): For documentation workflows, specify where screenshots should live:

look.py --app Chrome ./docs/step3.png

Design rationale: Quick looks are ephemeral by default. Documentation requires intentional placement. If a subagent is documenting, it should think about where artifacts belong.

How It Works

  1. Window enumeration: Uses macOS CGWindowList API (pure Quartz, no AppleScript)
  2. Capture: Uses screencapture -l<windowid> for windows, screencapture -x for screen
  3. Resize: Uses sips --resampleHeightWidthMax for efficient scaling

Key capability: Can capture windows even when covered or minimized.

Limitations

Scrollback: Only captures visible viewport. If content scrolled off screen, it won't be in the screenshot. Workaround: increase window size or pipe output to file.

Multiple monitors: Untested. --screen with -m flag captures main monitor only.

Window selection: Takes first match when multiple windows match filters. No "frontmost" heuristic yet.

Integration with browsermcp

browsermcp's browser_screenshot injects images directly into context but doesn't persist them as files. Use this skill when you need:

  • Screenshots that persist beyond the conversation
  • Captures of non-browser apps
  • Captures of windows behind the browser
  • Files to upload to Drive or include in docs

Permissions

Requires Screen Recording permission in System Preferences > Privacy & Security.

If capture fails with "check Screen Recording permissions", the user needs to grant permission to the terminal app (Ghostty, Terminal, iTerm, etc.).