How to Set Up Codex for Image SEO (Full SKILL.md Included)

---
name: codex-seo-images
description: Use when the user gives a URL or image directory and asks about image SEO, image audit, alt text, image size, WebP/AVIF conversion, image format, lazy loading, CLS from images, image metadata, or optimizing images for Google Images. Triggers on "check my images", "image optimization", "alt text audit", "images too big".
---
# Image Optimization Analysis

Audit and improve image assets for search, image SERP, and Core Web Vitals.
The scanner collects per-image signals; you rate against the tables and write
the fix list.

## Run

```bash
python3 ~/.codex/skills/codex-seo-images/scripts/image_scan.py <url> [--json]
```

The scanner reports total images, picture elements, and a summary of missing
alt, missing dimensions, lazy-load hints, oversized files, and non-WebP/AVIF
formats, then one line per image with its flags.

## Checks

### Alt text

- Present on every `<img>`, including images inside a `<picture>`'s `<img>` tag
- Descriptive: tells a human what the image shows, not the filename
- Length 10-125 characters
- Keyword use natural, not stuffed; decorative images use `alt=""` or
  `role="presentation"`

Good: "Professional plumber repairing kitchen sink faucet"
Bad: "image.jpg" (filename, not a description)
Bad: "plumber plumbing plumber services" (stuffing)
Bad: "Click here" (not descriptive)

### File size

| Image category | Target | Warning | Critical |
|----------------|--------|---------|----------|
| Thumbnails | < 50 KB | > 100 KB | > 200 KB |
| Content images | < 100 KB | > 200 KB | > 500 KB |
| Hero / banner | < 200 KB | > 300 KB | > 700 KB |

Compress to target without visible quality loss; the scanner flags anything
over 200 KB as heavy and over 500 KB as oversized.

### Format

| Format | Browser support | Use case |
|--------|-----------------|----------|
| WebP | 97%+ | Default recommendation |
| AVIF | 92%+ | Best compression, newer |
| JPEG | 100% | Photo fallback |
| PNG | 100% | Graphics with transparency |
| SVG | 100% | Icons, logos, illustrations |

Serve AVIF or WebP with a JPEG fallback:

```html
<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>
```

JPEG XL: a decoder shipped in Chrome 145 (Feb 2026) behind a flag, not on by
default. No confirmed production standard yet; keep AVIF/WebP plus JPEG.

### Responsive images

- `srcset` with multiple widths and `sizes` matching breakpoints
- Not the same width served to desktop and mobile

```html
<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-the-fold images
- Never lazy-load the hero/LCP image - that directly harms LCP
- JS-driven lazy loaders are common; the scanner reports `lazy_method`:

| `lazy_method` | Signal | Stack |
|---|---|---|
| native | `loading="lazy"` attribute | modern browsers |
| perfmatters | `data-perfmatters-src` / class `perfmatters-lazy` | WordPress + Perfmatters |
| ewww | `data-ewww-src` / `data-eio` / class `lazyload-eio` | WordPress + EWWW |
| js-generic | `data-src` / `data-lazy-src` / `data-original` / class `lazyload` | Lazysizes, vanilla lazyload, jQuery |
| none | no attribute or class signal | page is not lazy-loading |

If `lazy_method` is a JS loader, the missing native attribute is not a
regression - say so in the report instead of flagging it.

### LCP and CLS

- Hero image gets `fetchpriority="high"`:
  `<img src="hero.webp" fetchpriority="high" alt="..." width="1200" height="630">`
- Non-LCP images get `decoding="async"` so decode does not block the main thread
- Every image carries `width` and `height` (or CSS `aspect-ratio`) or the page
  gets layout shift: the scanner flags `no-dimensions(CLS)`
- Prefer real dimensions over hard-coded CSS that lies about the real ratio

### Filenames

- Descriptive and hyphenated, lowercase: `blue-running-shoes.webp`, not `IMG_1234.jpg`
- No spaces, no special characters

### CDN

- Images on a separate CDN hostname with edge caching headers is fine and
  expected for image-heavy sites; only flag if origin serves images and the
  site has no cache layer at all

## Output

### Image audit summary

| Metric | Status |
|--------|--------|
| Total images | XX |
| Missing alt text | XX |
| Oversized (>200 KB) | XX |
| Wrong format (not WebP/AVIF) | XX |
| No dimensions | XX |
| Not lazy-hinted | XX |

### Prioritized optimization list

Sorted by largest file-size savings first, each row: image, current size,
format, issues, estimated savings. Then recommendations in this priority
order: convert to WebP/AVIF, add alt text, add dimensions, enable lazy load
below fold, compress oversize, fix filenames.

## Local file optimization (optional, no installs promised)

If the user hands you image files instead of a URL, check `which exiftool
cwebp convert ffmpeg` first. Use whatever exists:

```bash
cwebp -q 82 -metadata all input.jpg -o output.webp          # WebP
convert input.jpg -resize 800x -quality 82 image-800.webp   # responsive variant
ffmpeg -i input.jpg -c:v libaom-av1 -crf 30 -still-picture 1 output.avif  # AVIF
```

Two things to know:

- IPTC Creator/Copyright/By-line can show in Google Images display and brand
  attribution; it is display only, not a ranking factor. WebP carries EXIF/XMP
  but not IPTC; use XMP fields for WebP.
- If images are AI-generated product photos, Google Merchant Center requires
  the IPTC `DigitalSourceType: TrainedAlgorithmicMedia` label on feed imagery;
  unlabeled AI imagery can be disapproved. That is a feed-layer policy, not a
  ranking factor - flag it for Merchant Center feeds, not for the page.

## What matters vs what doesn't

| Factor | Impact | Where to set |
|--------|--------|--------------|
| Alt text | Critical (ranking) | HTML `<img alt="">` |
| Filename | High (ranking) | descriptive, hyphenated |
| Page context | High (ranking) | surrounding HTML content |
| File size / speed | Medium (via CWV) | compression + format |
| IPTC Creator/Copyright | Low (display only) | image metadata |
| EXIF camera data | None | irrelevant |
| IPTC keywords | None | Google ignores |

## Errors

| Scenario | Action |
|---|---|
| URL unreachable | Report connection error and status; check auth |
| No images found | Report none detected; suggest JS/CSS background images and asking for rendered HTML |
| Images behind CDN/auth | Report markup signals only; note sizes could not be fetched |
| No conversion tools | Skip local optimization; give online converters or design feedback instead |

#!/usr/bin/env python3
"""Collect per-image signals from a page: alt, size, format, lazy loading, CLS.
Standard library only. Usage:
  python3 image_scan.py <url> [--json]
"""
import json
import html as htmlmod
import re
import sys
import urllib.error
import urllib.request
import urllib.parse

TIMEOUT = 12
UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
      "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36 "
      "codex-seo-images/1.0")


def fetch(url, timeout=TIMEOUT):
    req = urllib.request.Request(url, headers={"User-Agent": UA})
    try:
        resp = urllib.request.urlopen(req, timeout=timeout)
        return resp.status, resp.geturl(), resp.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        return e.code, url, ""
    except Exception as e:
        return "ERR:" + str(e)[:120], url, ""


def header(url):
    """HEAD or ranged GET for size/type; returns (size, ctype) or (None, None)."""
    req = urllib.request.Request(url, method="HEAD", headers={"User-Agent": UA})
    try:
        resp = urllib.request.urlopen(req, timeout=TIMEOUT)
        ct = resp.headers.get("content-type", "")
        sl = resp.headers.get("content-length")
        size = int(sl) if sl and sl.isdigit() else None
        return size, ct
    except Exception:
        return None, None


def lazy_method(img, lower_src):
    cls = img.get("class", "")
    srcs = lower_src
    if '"perfmatters' in srcs or "data-perfmatters" in lower_src:
        return "perfmatters (JS plugin)"
    if "data-ewww" in lower_src or "data-eio" in lower_src or "lazyload-eio" in cls:
        return "ewww (JS plugin)"
    if "data-src" in lower_src or "data-lazy-src" in lower_src or "data-original" in lower_src or \
            "lazyload" in cls or re.search(r'\bdata-srcset', lower_src):
        return "js-generic (lazy loader)"
    if "loading=\"lazy\"" in json.dumps(img) or 'loading="lazy"' in json.dumps(img):
        return "native"
    return "none (not lazy-loaded)"


def main():
    url = sys.argv[1] if len(sys.argv) > 1 else ""
    if not url:
        print("usage: python3 image_scan.py <url> [--json]")
        sys.exit(1)
    want_json = "--json" in sys.argv
    if not url.startswith("http"):
        url = "https://" + url
    status, final, html = fetch(url)
    if not html:
        print({"url": url, "status": status, "error": "no HTML body"})
        sys.exit(0 if status == 200 else 1)
    base = final
    # strip <script>/<style> contents before extracting <img> to avoid false hits
    html = re.sub(r"<(script|style)[^>]*>.*?</\1>", " ", html, flags=re.S | re.I)

    imgs = []
    for m in re.finditer(r"<img\b[^>]*>", html, re.I):
        tag = m.group(0)
        attrs = {}
        for a in re.finditer(r'([\w-]+)\s*=\s*"([^"]*)"', tag, re.I):
            attrs[a.group(1).lower()] = htmlmod.unescape(a.group(2))
        src = attrs.get("src", "")
        abs_src = urllib.parse.urljoin(base, src) if src else ""
        alt = attrs.get("alt", "")
        imgs.append({
            "src": abs_src,
            "alt": alt,
            "alt_len": len(alt),
            "has_width": "width" in attrs,
            "has_height": "height" in attrs,
            "loading": attrs.get("loading", ""),
            "fetchpriority": attrs.get("fetchpriority", ""),
            "decoding": attrs.get("decoding", ""),
            "srcset": attrs.get("srcset", ""),
            "lazy_method": lazy_method(attrs, json.dumps(attrs).lower()),
        })

    picture_count = len(re.findall(r"<picture[^>]*>", html, re.I))

    # size/format from HEAD on first 25 images (progress: 1 per image, sequential)
    for img in imgs[:25]:
        if not img["src"].startswith("http"):
            img["size_kb"] = None
            img["ctype"] = ""
            continue
        size, ct = header(img["src"])
        img["size_kb"] = round(size / 1024, 1) if size else None
        img["ctype"] = ct.split(";")[0] if ct else ""

    def flag(img):
        f = []
        if img["src"].startswith("data:"):
            f.append("inline-base64:" + str(len(img["src"]))[:3] + "KB")
        if not img["alt"]:
            f.append("missing-alt")
        elif not img["alt"].startswith(("image", "pict", "photo")):
            if img["alt_len"] < 6:
                f.append("alt-too-short(%d)" % img["alt_len"])
        if img["alt"].lower().endswith((".jpg", ".jpeg", ".png", ".gif", ".webp", ".avif")):
            f.append("alt-is-filename")
        if img["alt_len"] > 125:
            f.append("alt-too-long(%d)" % img["alt_len"])
        if not img["has_width"] and not img["has_height"]:
            f.append("no-dimensions(CLS)")
        if img["loading"] == "lazy" and (img["alt"] or "") and img.get("src", ""):
            pass  # lazy is fine; above-fold flags are for humans + see note
        if img["loading"] not in ("lazy", "eager"):
            f.append("no-loading-hint")
        if img["fetchpriority"] not in ("high", "low"):
            f.append("no-fetchpriority")
        if img["size_kb"] is not None:
            if img["size_kb"] > 500:
                f.append("oversized-%dkb" % img["size_kb"])
            elif img["size_kb"] > 200:
                f.append("heavy-%dkb" % img["size_kb"])
        if img["ctype"] and img["ctype"] not in ("image/webp", "image/avif", "image/svg+xml"):
            f.append("format-" + img["ctype"].replace("image/", ""))
        return "; ".join(f)

    for img in imgs:
        img["flags"] = flag(img)

    r = {
        "url": url, "status": status,
        "total_images": len(imgs),
        "picture_elements": picture_count,
        "summary": {
            "missing_alt": sum(1 for i in imgs if not i["alt"]),
            "no_dimensions": sum(1 for i in imgs if not i["has_width"] and not i["has_height"]),
            "no_lazy_hint": sum(1 for i in imgs if i["loading"] not in ("lazy", "eager")),
            "oversized_over_200kb": sum(1 for i in imgs if (i["size_kb"] or 0) > 200),
            "not_webp_avif": sum(1 for i in imgs if i["ctype"] and i["ctype"] not in ("image/webp", "image/avif", "image/svg+xml")),
        },
        "images": imgs,
    }

    if want_json:
        print(json.dumps(r, indent=2))
        return
    print("image_scan %s  status %s  images %d  picture %d" % (r["url"], r["status"], r["total_images"], r["picture_elements"]))
    print("  summary: %d missing alt / %d no dimensions / %d not lazy-hinted / %d >200KB / %d not webp-avif" % (
        r["summary"]["missing_alt"], r["summary"]["no_dimensions"],
        r["summary"]["no_lazy_hint"], r["summary"]["oversized_over_200kb"],
        r["summary"]["not_webp_avif"]))
    for i, img in enumerate(imgs[:15], 1):
        size = "%skb" % img["size_kb"] if img["size_kb"] is not None else "-"
        short = (img["src"][:70] or "(empty)")
        print("  %2d. %-72s %-8s %s" % (i, short, size, img["flags"] or "ok"))


if __name__ == "__main__":
    main()

mkdir -p ~/.codex/skills/codex-seo-images/scripts
# save the two files above at:
#   ~/.codex/skills/codex-seo-images/SKILL.md
#   ~/.codex/skills/codex-seo-images/scripts/image_scan.py
python3 ~/.codex/skills/codex-seo-images/scripts/image_scan.py https://example.com

python3 ~/.codex/skills/codex-seo-images/scripts/image_scan.py https://yoursite.com/blog/your-article

image_scan https://auspia.ai/blog/codex-seo-technical-audit  status 200  images 16  picture 0
  summary: 14 missing alt / 3 no dimensions / 2 not lazy-hinted / 1 >200KB / 1 not webp-avif
   1. https://auspia.ai/blog/auspia-logo.svg                  11.3kb   no-dimensions(CLS); no-loading-hint; no-fetchpriority
   2. https://auspia.ai/_image?href=https%3A%2F%2Fauspia.ai%2F_emdash...   60.2kb   missing-alt
   3. https://auspia.ai/_emdash/api/media/file/01M13Y5HP...jpg           267.7kb  alt-too-long(213); no-dimensions(CLS); no-fetchpriority; heavy-267kb; format-jpeg
   4. https://auspia.ai/_image?href=https%3A%2F%2Fauspia.ai%2F_emdash...  -        missing-alt; no-fetchpriority

Read this message. Create the skill below at
~/.codex/skills/codex-seo-images/ by following the two code blocks in it:
1. The markdown block is SKILL.md.
2. The python block is scripts/image_scan.py.
Then run python3 ~/.codex/skills/codex-seo-images/scripts/image_scan.py
https://example.com as a self-test and report the output (or the error) back
to me, along with what you would fix first if I point you at my own site.
Do not run any other commands. Do not modify any other files.