How to use the Image SEO Auditor agent skill (seo-images)

What an agent skill is and what seo-images makes the agent do

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When a request matches the skill's description, the agent follows those instructions. The seo-images skill is one of these, and its task is image analysis for SEO and performance.

The skill checks whether each image has descriptive alt text, whether files are too large for their role, whether modern formats such as WebP or AVIF are used, whether width and height are set to prevent layout jumps, and whether lazy loading is applied correctly. It also covers responsive images with srcset and sizes, file names, and CDN usage.

• Alt text: present, descriptive, not keyword-stuffed, 10-125 characters long
• File size: tiered thresholds for thumbnails, content images and hero/banner images
• Format: recommends WebP or AVIF over JPEG or PNG and checks for a picture element with fallbacks
• Dimensions: width and height on every img element, or CSS aspect-ratio as an alternative
• Lazy loading: loading="lazy" on below-the-fold images, not on hero or LCP images
• Output: an image audit summary, a prioritized optimization list sorted by file size impact, and recommendations

Install the seo-images skill

Download the ZIP for the skill from this page and unzip it. The package contains LICENSE.txt and SKILL.md. You can install the skill for yourself or for a single project.

For a personal install, place the unzipped skill folder in ~/.claude/skills/. For a project install, place it in the project's .claude/skills/ folder. Alternatively, in the Claude apps you can upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/ (available across your projects)
• Project: .claude/skills/ inside the project folder (shared with anyone who works in that project)
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill's description lists phrases that should activate it, such as "image optimization", "alt text", "image SEO", "image audit", "optimize images", "image metadata", "image SERP", "convert to webp" and "image file optimize". Describe what you want in plain language and include the page URL, since the skill's argument is a URL.

The skill also accepts an argument-hint of [url], so a request that names the page is the most direct way to start an audit.

• Audit this page for image problems: https://example.com/services
• Check alt text and file sizes on my homepage images at https://example.com
• Which images on this product page should be converted to WebP?
• Run an image audit on https://example.com/blog/post and prioritize the fixes

Read the audit output

The audit returns a summary table with counts for total images, missing alt text, oversized images (over 200KB), wrong format, missing dimensions and images not lazy loaded. Below it, a prioritized table lists each image with its current size, format, issues and estimated savings, largest savings first.

Where the page uses a JavaScript lazy loader, the skill reports a lazy_method value next to loading so you can tell an intentional setup from a missing attribute. The values are native, perfmatters, ewww, js-generic and none.

• native: loading="lazy" attribute in the HTML
• perfmatters: WordPress with the Perfmatters plugin
• ewww: WordPress with EWWW Image Optimizer
• js-generic: common JavaScript lazy-loaders such as Lazysizes or vanilla-lazyload
• none: the image is not lazy loaded

Use the optional image SERP analysis

The skill can also compare your images with image results in Google for a keyword, using DataForSEO. The command form is /seo images serp <keyword>. This part needs the DataForSEO MCP server and your DataForSEO account credentials. The skill notes that the pinned MCP server has no dedicated Google Images SERP tool, so it uses the images element of the organic SERP results where one exists, and it says plainly when no image data is available.

The analysis covers top domains by image position, common title and alt text patterns, the format mix of top results (WebP, JPEG, PNG), and an opportunity score for keywords where you already rank.

• Requires DataForSEO MCP server and account credentials
• Without them, the core page audit still works

Example workflow for a WordPress or static site

A typical session starts with an audit of one page. Fix the highest-savings items first, then ask the agent to plan a batch conversion for the remaining oversized images. The skill's picture element pattern lists AVIF first, then WebP, then a JPEG img fallback with width, height, loading and decoding attributes.

• Audit the page and note the top five items in the prioritized list
• Add width and height to images that lack them to reduce layout shift
• Keep loading="lazy" off the hero image and set fetchpriority="high" on it
• Convert photos in a copy of your image folder, not the originals, then re-audit

Safety notes: scripts and network access

This skill runs scripts and uses the network. The SKILL.md refers to a helper script, parse_html.py, which is part of a larger claude-seo plugin. Running the skill's lazy-load check depends on that script being present at its referenced path, so a standalone copy may be incomplete. The image SERP feature sends requests through DataForSEO.

The skill describes WebP and AVIF conversion and IPTC/XMP metadata injection. These change files and can lose information if run carelessly, so work on copies. The SKILL.md does not name specific image conversion software, so the agent may need tools that you have to provide.

• Read the SKILL.md and any scripts before running them in a sensitive environment
• Make a backup of original image files before any conversion or metadata edit
• Check that the page HTML or URL is accessible to the agent; the checks are incomplete without it