agentleFS
martinbattaglia-commitsmartinbattaglia-commits/Claude-skills/skills/seo-images/SKILL.md

seo-images

Skill0 starsChanged 5 months agoMITView on GitHub

Image optimization analysis for SEO and performance. Checks alt text, file sizes, formats, responsive images, lazy loading, CLS prevention, image SERP rankings (via DataForSEO), and image file optimization (WebP/AVIF conversion, IPTC/XMP metadata injection). Use when user says "image optimization", "alt text", "image SEO", "image size", "image audit", "optimize images", "image metadata", "image SERP", "convert to webp", or "image file optimize".

  • Installs packages

32 other projects use a version of this, 24 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use seo-agentic.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AgriciDanielSkill

    seo-agentic

    Audit and fix agent readiness: the Lighthouse Agentic Browsing fraction, accessibility tree for agents, robots.txt and Content-Signal for AI agents, WAF treatment of agent traffic, llms.txt, Markdown delivery, ai-catalog.json, /.well-known discovery files, and WebMCP tools. Use when the user asks whether AI agents can use or browse the site, or about llms.txt or WebMCP. Exclude AI citability and brand signals (seo-geo) and commerce protocol depth (seo-ecommerce).

    Also in 5 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 7 are common, 2 are distinctive, and 6 are very specific to this project.

  • 7

    Common

    Most of the 27 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Use progressive enhancement with the most efficient format first:

    line 64
  2. Common:

    Do NOT lazy-load above-fold/hero images (hurts LCP)

    line 96
  3. Common:

    Check for native vs JavaScript-based lazy loading

    line 97
  4. Very specific:

    When auditing image SEO, report lazy_method alongside loading so users know whether their site is using a JS-driven lazy-loader (in which …

    line 120
  5. Very specific:

    Add fetchpriority="high" to your hero/LCP image to prioritize its download in the browser's network queue:

    line 126
  6. Very specific:

    Critical: Do NOT lazy-load above-the-fold/LCP images.

    line 132
  7. Very specific:

    Add decoding="async" to non-LCP images to prevent image decoding from blocking the main thread:

    line 136
  8. Common:

    Check if images served from CDN (different domain, CDN headers)

    line 164
  9. Common:

    Check for edge caching headers

    line 166
  10. Common:

    Add alt text to X images

    line 191
  11. Common:

    Add dimensions to X images

    line 192
  12. Distinctive:

    When DataForSEO MCP is available, enhance the image audit with competitive data.

    line 200
  13. Distinctive:

    If DataForSEO MCP is not available, inform user and suggest installing the extension.

    line 223
  14. Very specific:

    Before running: Check which tools are available with which exiftool cwebp convert ffmpeg.

    line 242
  15. Very specific:

    When /seo images optimize is run on AI-generated assets, prompt the user to confirm the source type and inject the matching IPTC value …

    line 357

“Common” is measured: kept by at least 6 in 10 of the 27 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Image Optimization Analysis

Checks

Alt Text

  • Present on all <img> elements (except decorative: role="presentation")
  • Descriptive: describes the image content, not "image.jpg" or "photo"
  • Includes relevant keywords where natural, not keyword-stuffed
  • Length: 10-125 characters

Good examples:

  • "Professional plumber repairing kitchen sink faucet"
  • "Red 2024 Toyota Camry sedan front view"
  • "Team meeting in modern office conference room"

Bad examples:

  • "image.jpg" (filename, not description)
  • "plumber plumbing plumber services" (keyword stuffing)
  • "Click here" (not descriptive)

File Size

Tiered thresholds by image category:

Image CategoryTargetWarningCritical
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

FormatBrowser SupportUse Case
WebP97%+Default recommendation
AVIF92%+Best compression, newer
JPEG100%Fallback for photos
PNG100%Graphics with transparency
SVG100%Icons, logos, illustrations

Recommend WebP/AVIF over JPEG/PNG. Check for <picture> element with format fallbacks.

Recommended <picture> Element Pattern

Use 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%.

JPEG XL: Emerging Format

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.

Responsive Images

  • srcset attribute for multiple sizes
  • sizes attribute matching layout breakpoints
  • Appropriate resolution for device pixel ratios
<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"
>

Lazy Loading

  • loading="lazy" on below-fold images
  • Do NOT lazy-load above-fold/hero images (hurts LCP)
  • Check for native vs JavaScript-based lazy loading
<!-- Below fold - lazy load -->
<img src="photo.jpg" loading="lazy" alt="Description">

<!-- Above fold - eager load (default) -->
<img src="hero.jpg" alt="Hero image">

Detected lazy-loader methods (lazy_method field)

scripts/parse_html.py classifies each image's lazy-loading mechanism via the lazy_method field on every image entry. Five values:

lazy_methodSignal detectedCommon stack
nativeloading="lazy" HTML attributeModern browsers, plain HTML
perfmattersdata-perfmatters-src/-srcset OR class perfmatters-lazyWordPress + Perfmatters plugin
ewwwdata-ewww-src / data-eio OR class lazyload-eioWordPress + EWWW Image Optimizer
js-genericdata-src / data-lazy-src / data-original / data-srcset OR class lazyload/lazyloaded/lazyLazysizes, vanilla-lazyload, jQuery plugins
noneNeither attribute nor class signalPage is not lazy-loading this image

When auditing image SEO, report lazy_method alongside loading so users know whether their site is using a JS-driven lazy-loader (in which case the native loading="lazy" attribute is intentionally absent — that is not a regression).

fetchpriority="high" for LCP Images

Add 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 Images

Add 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">

CLS Prevention

  • width and height attributes set on all <img> elements
  • aspect-ratio CSS as alternative
  • Flag images without dimensions
<!-- 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">

File Names

  • Descriptive: blue-running-shoes.webp not IMG_1234.jpg
  • Hyphenated, lowercase, no special characters
  • Include relevant keywords

CDN Usage

  • Check if images served from CDN (different domain, CDN headers)
  • Recommend CDN for image-heavy sites
  • Check for edge caching headers

Output

Image Audit Summary

MetricStatusCount
Total Images-XX
Missing Alt Text❌XX
Oversized (>200KB)⚠️XX
Wrong Format⚠️XX
No Dimensions⚠️XX
Not Lazy Loaded⚠️XX

Prioritized Optimization List

Sorted by file size impact (largest savings first):

ImageCurrent SizeFormatIssuesEst. Savings
...............

Recommendations

  1. Convert X images to WebP format (est. XX KB savings)
  2. Add alt text to X images
  3. Add dimensions to X images
  4. Enable lazy loading on X below-fold images
  5. Compress X oversized images

Image SERP Analysis

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:

  1. Fetch Google Images results via serp_google_images_live_advanced (depth=100)
  2. Extract: top domains, image types, alt text patterns
  3. Output competitor image SERP landscape

Output:

RankDomainTitle/AltImage URLPage URL
1example.com"Blue running shoes...".../shoes.webp/products/...

Analysis includes:

  • Domain dominance: which sites own the most image positions (top 10 by count)
  • Alt text patterns: common title/alt patterns in top-ranking images
  • Format distribution: WebP vs JPEG vs PNG in top results
  • Opportunity score: keywords where you have page rankings but no image presence

If DataForSEO MCP is not available, inform user and suggest installing the extension.


Image File Optimization

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)
  • ImageMagick convert -- Format conversion, resizing (pre-installed on most systems)
  • FFmpeg -- Fallback for format conversion (pre-installed)

Before running: Check which tools are available with which exiftool cwebp convert ffmpeg.

Format Conversion

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

Metadata Injection (IPTC for Google Rich Results)

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.

AI-Generated Images: DigitalSourceType (Merchant Center requirement)

For product images produced by generative AI, Google Merchant Center requires IPTC DigitalSourceType: TrainedAlgorithmicMedia metadata. This is an operational policy requirement, not a ranking factor — feeds missing this label on AI-generated imagery can be disapproved.

Primary source: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide (references the underlying Merchant Center policy on AI media labeling).

Audit command:

# Audit a directory for the IPTC label (counts: missing, ai, captured, etc.)
python3 scripts/iptc_ai_label.py audit ./images/ --json

# Audit a single image
python3 scripts/iptc_ai_label.py audit ./hero.webp --json

# Inject the AI label into an image
python3 scripts/iptc_ai_label.py inject ./ai-hero.webp \
    --source-type trainedAlgorithmicMedia

# Other vocabulary values:
#   compositeSynthetic  (mix of captured + AI elements)
#   digitalCapture      (fully captured photograph)

Raw exiftool equivalents (for ad-hoc usage):

# Inject manually
exiftool \
  -XMP-iptcExt:DigitalSourceType="https://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia" \
  ai-generated-product.jpg

# Audit: find images missing the label across a directory
exiftool -if 'not $XMP-iptcExt:DigitalSourceType' \
  -filename -DigitalSourceType *.jpg *.webp *.png

The IPTC vocabulary also defines:

  • trainedAlgorithmicMedia — fully AI-generated (use this for diffusion-model product imagery)
  • compositeSynthetic — mixes captured + AI-generated elements
  • digitalCapture — fully captured photograph (no AI element)

When /seo images optimize is run on AI-generated assets, prompt the user to confirm the source type and inject the matching IPTC value automatically.

For AI-generated product titles and descriptions, Google Merchant Center also requires the AI-generated text to be separately specified and labeled in the feed. This is enforced at the feed layer, not the page layer — flag this in cross-reference with seo-ecommerce.

Metadata Audit

# 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

Full Optimization Pipeline

For maximum image SEO, run this pipeline on each image:

  1. Audit existing metadata: exiftool -IPTC:all -XMP:all image.jpg
  2. Inject IPTC/XMP metadata: Creator, Copyright, Description
  3. Convert to WebP: cwebp -q 82 -metadata all image.jpg -o image.webp
  4. Generate responsive variants: 400w, 800w, 1200w
  5. Verify metadata preserved: exiftool image.webp
  6. Generate <picture> HTML: AVIF > WebP > JPEG fallback chain

What Matters vs What Doesn't for Google Images

FactorImpactWhere to Set
Alt textCRITICAL (ranking)HTML <img alt="">
FilenameHIGH (ranking)File system (descriptive, hyphenated)
Page contextHIGH (ranking)Surrounding HTML content
File size/speedMEDIUM (indirect via CWV)Compression + format conversion
IPTC Creator/CopyrightLOW (display only)Image file metadata
EXIF camera dataNONEIrrelevant for SEO
IPTC KeywordsNONEGoogle ignores these

Error Handling

ScenarioAction
URL unreachableReport connection error with status code. Suggest verifying URL and checking if site requires authentication.
No images found on pageReport that no <img> elements were detected. Suggest checking if images are loaded via JavaScript or CSS background-image.
Images behind CDN or authenticationNote 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 installedFall back to ImageMagick for metadata. Recommend: sudo apt install libimage-exiftool-perl
cwebp not installedFall back to ImageMagick or FFmpeg for WebP conversion. Recommend: sudo apt install webp
DataForSEO MCP not availableSkip Image SERP Analysis section. Note extension is not installed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.