From claude-seo
Analyzes images for SEO and performance: alt text quality, file sizes by category, formats (WebP/AVIF/JPEG/PNG/SVG), responsive images with srcset/sizes, lazy loading, CLS prevention, SERP rankings via DataForSEO, WebP/AVIF conversion, IPTC/XMP metadata.
npx claudepluginhub agricidaniel/claude-seo --plugin claude-seoThis skill uses the workspace's default tool permissions.
- Present on all `<img>` elements (except decorative: `role="presentation"`)
Guides strict Test-Driven Development (TDD): write failing tests first for features, bugfixes, refactors before any production code. Enforces red-green-refactor cycle.
Guides systematic root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Guides A/B test setup with mandatory gates for hypothesis validation, metrics definition, sample size calculation, and execution readiness checks.
<img> elements (except decorative: role="presentation")Good examples:
Bad examples:
Tiered thresholds by image category:
| Image Category | Target | Warning | Critical |
|---|---|---|---|
| Thumbnails | < 50KB | > 100KB | > 200KB |
| Content images | < 100KB | > 200KB | > 500KB |
| Hero/banner images | < 200KB | > 300KB | > 700KB |
Recommend compression to target thresholds where possible without quality loss.
| Format | Browser Support | Use Case |
|---|---|---|
| WebP | 97%+ | Default recommendation |
| AVIF | 92%+ | Best compression, newer |
| JPEG | 100% | Fallback for photos |
| PNG | 100% | Graphics with transparency |
| SVG | 100% | Icons, logos, illustrations |
Recommend WebP/AVIF over JPEG/PNG. Check for <picture> element with format fallbacks.
<picture> Element PatternUse progressive enhancement with the most efficient format first:
<picture>
<source srcset="image.avif" type="image/avif">
<source srcset="image.webp" type="image/webp">
<img src="image.jpg" alt="Descriptive alt text" width="800" height="600" loading="lazy" decoding="async">
</picture>
The browser will use the first supported format. Current browser support: AVIF 93.8%, WebP 95.3%.
In November 2025, Google's Chromium team reversed its 2022 decision and announced it will restore JPEG XL support in Chrome using a Rust-based decoder. The implementation is feature-complete but not yet in Chrome stable. JPEG XL offers lossless JPEG recompression (~20% savings with zero quality loss) and competitive lossy compression. Not yet practical for web deployment, but worth monitoring for future adoption.
srcset attribute for multiple sizessizes attribute matching layout breakpoints<img
src="image-800.jpg"
srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
alt="Description"
>
loading="lazy" on below-fold images<!-- Below fold - lazy load -->
<img src="photo.jpg" loading="lazy" alt="Description">
<!-- Above fold - eager load (default) -->
<img src="hero.jpg" alt="Hero image">
fetchpriority="high" for LCP ImagesAdd fetchpriority="high" to your hero/LCP image to prioritize its download in the browser's network queue:
<img src="hero.webp" fetchpriority="high" alt="Hero image description" width="1200" height="630">
Critical: Do NOT lazy-load above-the-fold/LCP images. Using loading="lazy" on LCP images directly harms LCP scores. Reserve loading="lazy" for below-the-fold images only.
decoding="async" for Non-LCP ImagesAdd decoding="async" to non-LCP images to prevent image decoding from blocking the main thread:
<img src="photo.webp" alt="Description" width="600" height="400" loading="lazy" decoding="async">
width and height attributes set on all <img> elementsaspect-ratio CSS as alternative<!-- Good - dimensions set -->
<img src="photo.jpg" width="800" height="600" alt="Description">
<!-- Good - CSS aspect ratio -->
<img src="photo.jpg" style="aspect-ratio: 4/3" alt="Description">
<!-- Bad - no dimensions -->
<img src="photo.jpg" alt="Description">
blue-running-shoes.webp not IMG_1234.jpg| Metric | Status | Count |
|---|---|---|
| Total Images | - | XX |
| Missing Alt Text | ❌ | XX |
| Oversized (>200KB) | ⚠️ | XX |
| Wrong Format | ⚠️ | XX |
| No Dimensions | ⚠️ | XX |
| Not Lazy Loaded | ⚠️ | XX |
Sorted by file size impact (largest savings first):
| Image | Current Size | Format | Issues | Est. Savings |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |
When DataForSEO MCP is available, enhance the image audit with competitive data.
/seo images serp <keyword>Cross-reference on-page images with Google Images SERP rankings.
Workflow:
serp_google_images_live_advanced (depth=100)Output:
| Rank | Domain | Title/Alt | Image URL | Page URL |
|---|---|---|---|---|
| 1 | example.com | "Blue running shoes..." | .../shoes.webp | /products/... |
Analysis includes:
If DataForSEO MCP is not available, inform user and suggest installing the extension.
Optimize image files for SEO: format conversion, metadata injection, compression.
/seo images optimize <path>Optimize image file(s) for web and SEO. Converts to WebP/AVIF, injects IPTC metadata, compresses, and generates responsive variants.
Tools used (in order of preference):
exiftool -- EXIF/IPTC/XMP read/write (install: sudo apt install libimage-exiftool-perl)cwebp -- WebP conversion (install: sudo apt install webp)convert -- Format conversion, resizing (pre-installed on most systems)Before running: Check which tools are available with which exiftool cwebp convert ffmpeg.
Convert images to modern formats with metadata preservation:
# WebP (recommended default) - with metadata preserved
cwebp -q 82 -metadata all input.jpg -o output.webp
# WebP via ImageMagick (fallback if cwebp not installed)
convert input.jpg -quality 82 output.webp
# AVIF via FFmpeg (slower encode, best compression)
ffmpeg -i input.jpg -c:v libaom-av1 -crf 30 -still-picture 1 output.avif
# Responsive variants (400w, 800w, 1200w)
convert input.jpg -resize 400x -quality 82 image-400.webp
convert input.jpg -resize 800x -quality 82 image-800.webp
convert input.jpg -resize 1200x -quality 82 image-1200.webp
Google Images displays IPTC Creator, Credit Line, and Copyright in search results. This is NOT a ranking factor but improves rich result display and brand attribution.
With exiftool (preferred):
# Read all metadata
exiftool image.jpg
# Inject IPTC + XMP metadata for Google Images rich results
exiftool \
-IPTC:ObjectName="Product Photo Description" \
-IPTC:Caption-Abstract="Detailed image description" \
-IPTC:By-line="Brand Name Photography" \
-IPTC:Credit="Brand Name" \
-IPTC:CopyrightNotice="Copyright 2026 Brand Name" \
-IPTC:Source="brandname.com" \
-XMP:Title="Product Photo Description" \
-XMP:Description="Detailed image description" \
-XMP:Creator="Brand Name Photography" \
-XMP:Rights="Copyright 2026 Brand Name" \
image.jpg
# Batch inject to all images in directory
exiftool -overwrite_original \
-IPTC:By-line="Brand Name" \
-IPTC:CopyrightNotice="Copyright 2026 Brand Name" \
*.jpg *.webp *.png
With ImageMagick (fallback):
identify -verbose image.jpg | head -50
convert input.jpg \
-set comment "Product Photo Description" \
-set IPTC:2:80 "Brand Name Photography" \
-set IPTC:2:116 "Copyright 2026 Brand Name" \
output.jpg
IMPORTANT: WebP supports EXIF and XMP but NOT IPTC natively. For WebP files, use XMP fields instead of IPTC. exiftool handles this conversion automatically.
# Quick audit with exiftool
exiftool -IPTC:all -XMP:all -EXIF:ImageDescription image.jpg
# Batch audit - find images missing IPTC Creator
exiftool -if 'not $IPTC:By-line' -filename *.jpg *.webp *.png
For maximum image SEO, run this pipeline on each image:
exiftool -IPTC:all -XMP:all image.jpgcwebp -q 82 -metadata all image.jpg -o image.webpexiftool image.webp<picture> HTML: AVIF > WebP > JPEG fallback chain| Factor | Impact | Where to Set |
|---|---|---|
| Alt text | CRITICAL (ranking) | HTML <img alt=""> |
| Filename | HIGH (ranking) | File system (descriptive, hyphenated) |
| Page context | HIGH (ranking) | Surrounding HTML content |
| File size/speed | MEDIUM (indirect via CWV) | Compression + format conversion |
| IPTC Creator/Copyright | LOW (display only) | Image file metadata |
| EXIF camera data | NONE | Irrelevant for SEO |
| IPTC Keywords | NONE | Google ignores these |
| Scenario | Action |
|---|---|
| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if site requires authentication. |
| No images found on page | Report that no <img> elements were detected. Suggest checking if images are loaded via JavaScript or CSS background-image. |
| Images behind CDN or authentication | Note that image files could not be directly accessed for size analysis. Report available metadata (alt text, dimensions, format from markup) and flag inaccessible resources. |
| exiftool not installed | Fall back to ImageMagick for metadata. Recommend: sudo apt install libimage-exiftool-perl |
| cwebp not installed | Fall back to ImageMagick or FFmpeg for WebP conversion. Recommend: sudo apt install webp |
| DataForSEO MCP not available | Skip Image SERP Analysis section. Note extension is not installed. |