images

name	images
description	Umbrella coordinator for image handling. Coordinates responsive-images, placeholder-images, and automation scripts. Use when adding images to any page, optimizing existing images, or setting up image pipelines.
allowed-tools	Read, Write, Edit, Bash

Images Skill

This skill coordinates all image-related functionality in the project. It delegates to specialized skills for detailed patterns while providing automation and validation.

Philosophy

1. Automation first - Modern formats (WebP, AVIF) generated automatically via hooks
2. Delegate to specialists - Detailed patterns live in sub-skills
3. Validation built-in - Hooks catch common issues early
4. Performance by default - Optimal loading strategies applied automatically

---

Quick Decision Guide

Task	Go To	Why
Add real images to a page	This skill	Coordinates optimization + markup
Write responsive <picture> markup	responsive-images	Detailed srcset/sizes patterns
Create prototype placeholders	placeholder-images	SVG placeholder generation
Optimize LCP/hero images	performance	fetchpriority, preload details
Fix image validation errors	This skill	Commands and checklist below

---

Automation Pipeline

On Image File Write

When you write a JPEG or PNG file, the PostToolUse hook automatically:

1. Checks if WebP/AVIF variants already exist
2. Generates .webp variant using Sharp
3. Generates .avif variant using Sharp
4. Reports what was created

Skipped files:

• Files matching -\d+ pattern (already a srcset variant)
• Files with existing .webp and .avif siblings
• Non-source formats (already WebP, AVIF, GIF, SVG)

On HTML File Write

When you add or edit HTML files, existing hooks check for:

• Missing loading attribute on images
• Missing decoding attribute
• Missing alt text
• Images without width/height (causes layout shift)

---

Manual Commands

# Generate WebP/AVIF for all images in directory
node .claude/scripts/optimize-images.js src/images

# Also generate srcset variants (400w, 800w, 1200w)
node .claude/scripts/optimize-images.js src/images --sizes

# Preview what would be done
node .claude/scripts/optimize-images.js src/images --dry-run

# Validate image file sizes and dimensions
node .claude/scripts/image-check.js src/images

# Validate HTML image markup
node .claude/scripts/image-html-check.js src/**/*.html

---

Image Workflow

Adding a New Image

1. Add source image (JPEG or PNG) to appropriate directory
2. Hook auto-generates WebP and AVIF variants
3. Write HTML using <picture> pattern from responsive-images skill
4. Validate with node .claude/scripts/image-html-check.js

Example Flow

# 1. You write: src/images/hero.jpg
# 2. Hook creates: src/images/hero.webp, src/images/hero.avif

# 3. Use in HTML:

<picture>
  <source type="image/avif" srcset="images/hero.avif"/>
  <source type="image/webp" srcset="images/hero.webp"/>
  <img src="images/hero.jpg"
       alt="Hero banner description"
       loading="eager"
       fetchpriority="high"
       decoding="async"
       width="1200"
       height="400"/>
</picture>

Optimizing Existing Images

# Generate modern formats only
node .claude/scripts/optimize-images.js src/images

# Generate srcset variants too
node .claude/scripts/optimize-images.js src/images --sizes

---

File Organization

src/
  images/
    hero.jpg            # Source (keep for editing)
    hero.webp           # Auto-generated
    hero.avif           # Auto-generated
    hero-400.jpg        # Srcset variant (--sizes)
    hero-400.webp       # Srcset variant (--sizes)
    hero-400.avif       # Srcset variant (--sizes)
    hero-800.jpg        # Srcset variant (--sizes)
    ...
  placeholder/
    *.svg               # Placeholder images (see placeholder-images skill)

Naming conventions:

• Source files: name.jpg or name.png
• Format variants: name.webp, name.avif
• Size variants: name-{width}.{format} (e.g., hero-800.webp)

---

Format Recommendations

Format	Use For	Quality Setting
AVIF	Primary modern format	65
WebP	Fallback for AVIF	82
JPEG	Universal fallback	85
PNG	Transparency, screenshots	85
SVG	Icons, logos, placeholders	N/A

Browser fallback order: AVIF > WebP > JPEG/PNG

---

Srcset Width Guidelines

Image Context	Recommended Widths
Hero/full-width	800, 1200, 1920
Content images	400, 800, 1200
Card thumbnails	300, 450
Gallery images	220, 330, 440
Avatars	48, 96, 128

Generate with: node .claude/scripts/optimize-images.js --sizes

---

Checklist

When adding images:

• Source image in correct directory
• WebP variant exists (auto-generated by hook)
• AVIF variant exists (auto-generated by hook)
• HTML uses <picture> with format fallbacks
• loading attribute set (eager for LCP, lazy for others)
• decoding="async" present
• fetchpriority="high" for hero/LCP images
• width and height attributes prevent layout shift
• alt text is descriptive (or empty for decorative)
• sizes calculated based on rendered width

---

Troubleshooting

Hook didn't generate variants

Check that:

1. File is JPEG or PNG (not already WebP/AVIF)
2. File doesn't match -\d+ pattern (srcset variant)
3. Sharp is installed: npm ls sharp

Images too large

Run the check script:

node .claude/scripts/image-check.js src/images

Recommended maximums:

• Hero images: < 200KB (AVIF), < 300KB (WebP)
• Content images: < 100KB
• Thumbnails: < 30KB

Missing srcset variants

Generate manually:

node .claude/scripts/optimize-images.js src/images --sizes

---

Related Skills

• responsive-images - Detailed srcset, sizes, and picture patterns
• placeholder-images - SVG placeholders for prototypes
• performance - LCP optimization, fetchpriority, lazy loading
• accessibility-checker - Alt text and image accessibility
• xhtml-author - Valid HTML5 markup for images