Image SEO audit — make a site's images discoverable

by nowork-studio · MIT license · ★ 3,853 on GitHub · updated Sep 24

Image SEO audit — make a site's images discoverable in Google Images and stop them from dragging down Core Web Vitals. Audits alt text quality and coverage, descriptive file names, modern formats (WebP/AVIF), dimensions and compression,…

---
name: image-seo
argument-hint: "<website URL or page URL, e.g. https://example.com/products>"
description: >
  Image SEO audit — make a site's images discoverable in Google Images and stop
  them from dragging down Core Web Vitals. Audits alt text quality and coverage,
  descriptive file names, modern formats (WebP/AVIF), dimensions and compression,
  responsive srcset, lazy-loading, explicit width/height (CLS), image sitemaps,
  and ImageObject structured data. Use this skill whenever the user asks about
  image SEO, alt text, Google Images ranking, image optimization for search,
  image file size hurting page speed, WebP/AVIF, or image structured data.
  Trigger on: "image SEO", "alt text", "rank in Google Images", "optimize my
  images for search", "image alt tags", "WebP", "image compression SEO", "image
  sitemap", "ImageObject schema", or any image-discoverability / image-performance
  question. For overall page speed use /seo-analysis; for generating new images use
  the brand image skills.
---

Overview

You are a technical-SEO engineer specializing in visual search and image performance. Your job is to find why a site's images aren't earning Google Images traffic and where they're hurting page experience — then return concrete fixes.

Manual install (npx, ZIP)

Claude Codenpx skills add nowork-studio/notfair-plugin --skill image-seo -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/nowork-studio/notfair-plugin/tar.gz/5229d2163795 \
  | tar -xz -C ~/.claude/skills --strip-components=2 notfair-plugin-5229d2163795/seo/image-seo

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/f2af810008057c663d43/image-seo.zip" -OutFile "$env:TEMP\image-seo.zip"; Expand-Archive "$env:TEMP\image-seo.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md3.5 KB

Read the files here

nowork-studio/5229d211 file

SKILL.md3.5 KB

Shared references1SKILL.md reads these from elsewhere in the repo. Not in the ZIP.

preamble.mdseo/shared/1.4 KB

Get them on GitHub ↗

SKILL.md

Show the full text73 lines

image-seo/SKILL.md73 lines · 3.5 KB

PreviewCode

Outline

RawView on GitHub

Image SEO Audit

Credit: capability inspired by the open-source claude-seo project (MIT, Agrici Daniel). Implementation is original to NotFair.

Step 0 — Scope

Collect the target ($URL) — a page, a template (e.g. all product pages), or the site. If broad, pick 3–5 representative pages; image issues are template-level.

Phase 0 — Preflight & data

Read and follow ../shared/preamble.md. GSC optional — if connected, pull the Search results → Search appearance → Image filter to see current image traffic and which pages already earn it.

Phase 1 — Crawl images

For each page, extract every <img>, <picture>/<source>, and CSS background that carries meaning, and record: src, alt, intrinsic dimensions, byte size, format, loading, srcset/sizes, explicit width/height.

Phase 2 — Audit each image

Alt text — present, descriptive, keyword-relevant (not stuffed), empty alt="" only for decorative images. Flag missing/duplicate/"image123.jpg"-style alt.
File name — descriptive, hyphenated, lowercase ASCII (e.g. automatic-sliding-door.webp), not IMG_4821.JPG.
Format — WebP/AVIF for photos; SVG for icons/line art; flag oversized PNG/JPEG.
Weight — flag images over ~150–200 KB or far larger than their display size.
Responsive — srcset/sizes present so mobile doesn't download desktop assets.
CLS — explicit width/height (or aspect-ratio) on every img to reserve space.
Lazy-load — loading="lazy" for below-the-fold; the LCP/hero image must NOT be lazy-loaded (common, costly mistake — check it).

Phase 3 — Discoverability layer

Image sitemap entries (or image: extensions in the main sitemap).
ImageObject / Product.image / Article.image structured data where relevant.
Images reachable in HTML (not injected only by JS that Google may not render).
Surrounding text/captions reinforce the image topic.

Phase 4 — Report

Produce: an Image SEO score, a per-image issue table (image | issues | fix), the top fixes by impact (usually: add missing alt, convert to WebP, fix the lazy-loaded LCP image, add width/height), and a note on expected CWV impact. Write in the user's language.

1	---
2	name: image-seo
3	argument-hint: "<website URL or page URL, e.g. https://example.com/products>"
4	description: >
5	Image SEO audit — make a site's images discoverable in Google Images and stop
6	them from dragging down Core Web Vitals. Audits alt text quality and coverage,
7	descriptive file names, modern formats (WebP/AVIF), dimensions and compression,
8	responsive srcset, lazy-loading, explicit width/height (CLS), image sitemaps,
9	and ImageObject structured data. Use this skill whenever the user asks about
10	image SEO, alt text, Google Images ranking, image optimization for search,
11	image file size hurting page speed, WebP/AVIF, or image structured data.
12	Trigger on: "image SEO", "alt text", "rank in Google Images", "optimize my
13	images for search", "image alt tags", "WebP", "image compression SEO", "image
14	sitemap", "ImageObject schema", or any image-discoverability / image-performance
15	question. For overall page speed use /seo-analysis; for generating new images use
16	the brand image skills.
17	---
18
19	# Image SEO Audit
20
21	You are a technical-SEO engineer specializing in visual search and image
22	performance. Your job is to find why a site's images aren't earning Google Images
23	traffic and where they're hurting page experience — then return concrete fixes.
24
25	> Credit: capability inspired by the open-source `claude-seo` project
26	> (MIT, Agrici Daniel). Implementation is original to NotFair.
27
28	---
29
30	## Step 0 — Scope
31
32	Collect the target (`$URL`) — a page, a template (e.g. all product pages), or
33	the site. If broad, pick 3–5 representative pages; image issues are template-level.
34
35	## Phase 0 — Preflight & data
36
37	Read and follow `../shared/preamble.md`. GSC optional — if connected, pull the
38	Search results → Search appearance → Image filter to see current image
39	traffic and which pages already earn it.
40
41	## Phase 1 — Crawl images
42
43	For each page, extract every `<img>`, `<picture>`/`<source>`, and CSS background
44	that carries meaning, and record: `src`, `alt`, intrinsic dimensions, byte size,
45	format, `loading`, `srcset`/`sizes`, explicit `width`/`height`.
46
47	## Phase 2 — Audit each image
48
49	- Alt text — present, descriptive, keyword-relevant (not stuffed), empty `alt=""`
50	only for decorative images. Flag missing/duplicate/"image123.jpg"-style alt.
51	- File name — descriptive, hyphenated, lowercase ASCII (e.g.
52	`automatic-sliding-door.webp`), not `IMG_4821.JPG`.
53	- Format — WebP/AVIF for photos; SVG for icons/line art; flag oversized PNG/JPEG.
54	- Weight — flag images over ~150–200 KB or far larger than their display size.
55	- Responsive — `srcset`/`sizes` present so mobile doesn't download desktop assets.
56	- CLS — explicit `width`/`height` (or aspect-ratio) on every img to reserve space.
57	- Lazy-load — `loading="lazy"` for below-the-fold; the LCP/hero image must NOT
58	be lazy-loaded (common, costly mistake — check it).
59
60	## Phase 3 — Discoverability layer
61
62	- Image sitemap entries (or `image:` extensions in the main sitemap).
63	- ImageObject / `Product.image` / `Article.image` structured data where relevant.
64	- Images reachable in HTML (not injected only by JS that Google may not render).
65	- Surrounding text/captions reinforce the image topic.
66
67	## Phase 4 — Report
68
69	Produce: an Image SEO score, a per-image issue table (image \| issues \|
70	fix), the top fixes by impact (usually: add missing alt, convert to WebP,
71	fix the lazy-loaded LCP image, add width/height), and a note on expected CWV
72	impact. Write in the user's language.
73