Images

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

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

Browser fallback order: AVIF > WebP > JPEG/PNG

Srcset Width Guidelines

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