Image Compression Skill

Auto-compress oversized images for Claude Code upload

🚨 Now Automatic via Hooks (2026-03-05)

Images are now compressed BEFORE they can cause errors! You no longer need to manually trigger this skill. The hooks handle it.

When to Use Manually

Only needed if:

• Error still occurs (legacy image in conversation) → Use /clear
• You want to compress a specific file manually
• Hooks somehow missed an image

What This Skill Does

1. Finds latest image - Automatically locates the most recent screenshot/image
2. Smart compression - Resizes to max 3500px (safe margin under 8000px limit)
3. Handles Unicode filenames - Works with macOS screenshots that have special characters
4. Preserves quality - Uses LANCZOS resampling for best quality
5. Auto-display - Shows compressed image immediately

Manual Usage

# Only needed if hooks fail
cd ~/.claude/skills/playwright-skill && node -e "require('./lib/helpers').compressImage()"

How It Works

# 1. Find latest image (handles Unicode filenames)
import glob, os
files = glob.glob('~/Desktop/Screenshot')
latest = max(files, key=os.path.getmtime)

2. Compress with PIL
from PIL import Image
img = Image.open(latest)
max_dim = 3500
if max(img.size) > max_dim:
    ratio = min(max_dim/img.size[0], max_dim/img.size[1])
    new_size = (int(img.size[0]ratio), int(img.size[1]*ratio))
    img = img.resize(new_size, Image.Resampling.LANCZOS)

3. Save to /tmp and display
img.save('/tmp/compressed.png', 'PNG', optimize=True)

Technical Details

• Max dimension: 3500px (safe margin)
• Format: PNG with optimization
• Resampling: LANCZOS (high quality) / sips (macOS built-in)
• Output: /tmp/compressed_screenshot.png or in-place

Edge Cases Handled

✅ Unicode characters in filenames (macOS \u202f narrow no-break space) ✅ Multiple images - picks latest by modification time ✅ Already small images - skips resize ✅ File permissions - copies to /tmp first if needed

🚨 If Error Still Occurs (Infinite Loop)

If you see 8000 pixels error, the image is already in conversation context.

Fix:

/clear   ← Clear conversation (recommended)

Or:

Ctrl+C → claude   ← Start new session

The hooks prevent NEW images from causing this. The error only happens with legacy images.

Example Output

🔄 [Auto-compress] Image 5000x5000px → compressing...
✅ [Auto-compress] → 3500x3500px

---

Installed: 2026-03-01 Upgraded: 2026-03-05 (Hook-based auto-prevention) Location: ~/.claude/skills/compress-image/ Auto-trigger: Yes (via hooks, before errors can occur)