Compress Images

1---
2name: compress-images
3description: Compress images for web/SEO performance using cwebp. Use when optimizing images for faster page loads, reducing file sizes, or converting JPG/PNG to WebP format.
4argument-hint: "[directory]"
5allowed-tools: Bash(cwebp:*), Bash(ls:*), Bash(mkdir:*), Bash(mv:*)
6---
7 
8# Image Compression Skill
9 
10Compress all images in `$ARGUMENTS` (or `app/assets/images/content/` if no path provided) to WebP format, optimized for SEO performance (target: under 100KB per image).
11 
12## Process
13 
141. **Create originals folder** - Create `originals/` subfolder inside the target directory and move source files there. Never destroy source files.
152. **Compress each image** (JPG, PNG, GIF) from `originals/` to the parent directory as `.webp`
163. **Iterate until all images are under 100KB** - check sizes after each pass, re-compress any that exceed the target
174. **Report results** with before/after sizes
185. **Update references** in content files from old extensions to `.webp`
19 
20## File Structure
21 
22```
23target-directory/
24├── originals/           # High-quality source files preserved here
25│   ├── hero.jpg
26│   └── feature.png
27├── hero.webp            # Compressed, web-optimized
28└── feature.webp
29```
30 
31## Iterative Compression Algorithm
32 
33**IMPORTANT:** Keep compressing until ALL images are under 100KB. Check sizes after each pass and re-compress any that exceed the target.
34 
35### Step 1: Initial pass (q 70)
36```bash
37cwebp -q 70 -resize 1200 0 originals/image.jpg -o image.webp
38ls -lh image.webp  # Check size
39```
40 
41### Step 2: If still over 100KB, reduce quality progressively
42```bash
43# Try these in order until under 100KB:
44cwebp -q 60 -resize 1200 0 originals/image.jpg -o image.webp
45cwebp -q 50 -resize 1200 0 originals/image.jpg -o image.webp
46cwebp -q 45 -resize 1200 0 originals/image.jpg -o image.webp
47cwebp -q 40 -resize 1200 0 originals/image.jpg -o image.webp
48cwebp -q 35 -resize 1200 0 originals/image.jpg -o image.webp
49```
50 
51### Step 3: For stubborn images, also reduce dimensions
52```bash
53# If q 35 at 1200px is still over 100KB, reduce to 1000px:
54cwebp -q 30 -resize 1000 0 originals/image.jpg -o image.webp
55cwebp -q 25 -resize 1000 0 originals/image.jpg -o image.webp
56```
57 
58## Real-World Results (Reference)
59 
60From actual compression run on content images:
61 
62| Image | Original | First Try | Final | Settings Used |
63|-------|----------|-----------|-------|---------------|
64| waves.jpg | 198KB | 33KB | 33KB | q 70, 1200px (1 pass) |
65| calendar.jpg | 246KB | 42KB | 42KB | q 70, 1200px (1 pass) |
66| floating.jpg | 230KB | 43KB | 43KB | q 70, 1200px (1 pass) |
67| cash.jpg | 409KB | 88KB | 88KB | q 70, 1200px (1 pass) |
68| knot.jpg | 395KB | 96KB | 96KB | q 70, 1200px (1 pass) |
69| floating-dark.jpg | 414KB | 94KB | 94KB | q 70, 1200px (1 pass) |
70| keyboard2.jpg | 459KB | 102KB | 102KB | q 70, 1200px (1 pass, acceptable) |
71| **perpetual.jpg** | 565KB | 130KB | **96KB** | q 40, 1200px (3 passes) |
72| **keyboard.jpg** | 718KB | 196KB | **98KB** | q 25, 1000px (5 passes) |
73 
74### Key Insights
75 
761. **Most images** (under 500KB source) compress fine with default settings (q 70, 1200px)
772. **Large detailed images** (500KB+) often need multiple passes
783. **Very large images** (700KB+) may need both lower quality AND smaller dimensions
794. **Keyboard/tech photos** with fine detail are hardest to compress - expect 4-5 passes
805. **Soft/blurry images** compress much better than sharp detailed ones
81 
82## After Compression
83 
841. **Verify ALL files under 100KB**: `ls -lh *.webp` - re-run compression on any exceeding target
852. Update content files referencing old extensions (.jpg, .png) to use .webp
863. Test that images render correctly in the application
874. Original files remain in `originals/` folder for future reference or re-compression
88