using-screenshots

name	Using Screenshots
description	This snippet should be used when reading, organizing, and naming screenshots with date prefixes.

When this skill is in your context, you should base your answer from the newest screenshots.

Analyze what screenshots you should read implicitly by getting the current time via date. Or explicitly, if the user says HEAD~{n}, which is the top n screenshots, or N, which is the nth screenshot, or [1, 3, 5] which is the 1, 3rd, and 5th screenshot, and other similar notation. Where the screenshots are ordered by time from newest to oldest.

Screenshot Workflow

Reading Screenshots

When you need to analyze screenshots or images provided by the user:

1. Default Location: Screenshots are typically saved to ~/Desktop
2. Read the screenshot: Use the Read tool to view screenshots from the Desktop

   Read tool: ~/Desktop/Screenshot_*.png
   

Organizing Screenshots After Reading

CRITICAL: After reading any screenshot, you MUST:

1. Rename descriptively based on the content
2. Add date prefix in format: YYYY-MM-DD
3. Move to organized location: ~/Desktop/claude_screenshots/

Naming Convention

YYYY-MM-DD-{descriptive-name}.{extension}

Examples:

• 2025-10-13-login-page-error.png
• 2025-10-13-dashboard-layout.png
• 2025-10-13-api-response-json.jpg

Organization Workflow

# After reading a screenshot from Desktop:
# 1. Determine descriptive name based on content
# 2. Create directory if needed
mkdir -p ~/Desktop/claude_screenshots

# 3. Move and rename with date prefix
mv ~/Desktop/Screenshot_2023-10-13_at_10.30.45.png \
   ~/Desktop/claude_screenshots/2025-10-13-user-profile-page.png

Handling Filenames with Spaces

CRITICAL: macOS screenshot filenames contain spaces (e.g., Screenshot 2025-10-13 at 11.07.11 PM.png)

Best practice - Use glob pattern with variable in loop:

# ✅ CORRECT - Glob pattern handles spaces automatically
cd /Users/wz/Desktop && for f in Screenshot*11.07.11*.png; do
    mv "$f" claude_screenshots/2025-10-13-descriptive-name.png
done

Why this works:

• Shell expands glob pattern correctly without manual escaping
• Variable $f is quoted to preserve spaces
• Works reliably with all special characters

Alternative methods (less reliable):

# ⚠️  Escaping spaces - error-prone with multiple spaces
mv Screenshot\ 2025-10-13\ at\ 11.07.11\ PM.png destination.png

# ⚠️  Quotes - can fail with nested quotes or special chars
mv "Screenshot 2025-10-13 at 11.07.11 PM.png" destination.png

Lesson learned: When moving files with complex filenames (spaces, special chars), prefer glob patterns with loops over manual escaping.

Extreme Special Characters

Problem: Read tool fails on complex filenames (parentheses, Spanish characters, multiple periods)

Solution: Move → Rename → Read

mkdir -p ~/Desktop/claude_screenshots
cd ~/Desktop
i=1
for f in "Captura de pantalla 2025-10-23 a la(s) 8.20"*.png; do
  [ -f "$f" ] && mv "$f" "claude_screenshots/2025-10-23-temp-$i.png" && i=$((i+1))
done
# Read from ~/Desktop/claude_screenshots/2025-10-23-temp-*.png
# Then rename descriptively after analysis

Use when: Glob finds files but Read fails, Spanish macOS, parentheses, multiple periods

Playwright & Extension Screenshots

When taking screenshots with Playwright or other automation tools:

ALWAYS save directly to the organized location:

// Playwright example
await page.screenshot({
  path: `~/Desktop/claude_screenshots/${date}-${descriptiveName}.png`,
});

Python example:

from datetime import datetime
date = datetime.now().strftime('%Y-%m-%d')
screenshot_path = f'~/Desktop/claude_screenshots/{date}-{descriptive_name}.png'
driver.save_screenshot(screenshot_path)

Complete Workflow Summary

1. User shares screenshot → Usually in ~/Desktop
2. Claude reads it → Use Read tool
3. Claude analyzes → Understand the content
4. Claude organizes → Move to ~/Desktop/claude_screenshots/YYYY-MM-DD-description.ext (use glob pattern for files with spaces)
5. Any new screenshots taken → Save directly to ~/Desktop/claude_screenshots/ with date-description format

Directory Structure

~/Desktop/
├── claude_screenshots/
│   ├── 2025-10-13-login-error.png
│   ├── 2025-10-13-api-response.png
│   ├── 2025-10-14-dashboard-view.png
│   └── 2025-10-14-test-failure.jpg
└── [other desktop files]

Benefits

• Easy to find: Date prefix allows chronological sorting
• Descriptive: Know what the screenshot contains without opening
• Organized: All Claude-related screenshots in one place
• Consistent: Same format for manual and automated screenshots