SEO Images

Image SEO Audit

A focused, page-level (or domain-sample) audit of every <img> and <picture> on the target. Surfaces alt-text issues, format gaps (WebP/AVIF coverage), responsive-image gaps (srcset / sizes), LCP and CLS risk, and missing ImageObject markup. Output is a prioritised remediation list plus paste-ready <picture> and JSON-LD snippets.

Adapted from AgriciDaniel/claude-seo's seo-images skill (MIT). Rubric, lazy-loader taxonomy, and severity ladder track the upstream implementation; data sources are wired to this catalogue's SE Ranking / Firecrawl / Google APIs stack.

Prerequisites

• Required for inventory: mcp__firecrawl-mcp__firecrawl_scrape (raw HTML access). WebFetch returns markdown only — every <img> attribute (srcset, sizes, loading, fetchpriority, width, height, data-src* lazy variants) is stripped before the skill ever sees it. Without Firecrawl the audit cannot run. Install via bash extensions/firecrawl/install.sh.
• Optional (PSI byte-saving estimates): google-api.json configured (Tier 0 — API key only). When present, step 9 runs and adds real Lighthouse wastedBytes per image to the remediation list.
• Optional (SE Ranking audit cross-reference): SE Ranking MCP server connected and a recent audit for the domain. When present, step 10 elevates image-related audit issues onto the same remediation list.
• User provides: a target URL (single-page audit) or a domain (sampled audit). For domains, the skill confirms how many pages to sample before spending Firecrawl credits.

Process

1. Validate target & preflight. Normalise the URL (strip trailing slash, decode IDN). Resolve mode:

   • URL mode (default for inputs that look like a single page): the target is one URL. Cost: 1 Firecrawl credit + optional PSI calls.
   • Domain mode (input is a bare domain or the user explicitly asks for a domain-wide audit): map first, then scrape a sample.
   • Preflight checks (mirror skills/seo-firecrawl/references/preflight.md where it applies):
     • Confirm Firecrawl is connected. If not, abort with the install command and stop.
     • If Google APIs are wired up (~/.config/seo-skills/google-api.json present), record the detected tier; step 9 will use it. If not, mark step 9 as skipped.
     • If SE Ranking MCP is connected and a recent audit exists for the domain, record the audit ID; step 10 will use it. If not, mark step 10 as skipped.

2. Gather image inventory mcp__firecrawl-mcp__firecrawl_scrape (URL mode) or firecrawl_map + firecrawl_scrape (domain mode)

   • URL mode: scrape the target with formats: ["html", "markdown"] and onlyMainContent: false (we want nav/footer images too — hero logo, footer trust badges, decorative imagery all matter for the audit). For SPAs, pass waitFor: 2000 so lazy-injected images appear in the rendered DOM. Parse every <img> and every <picture> from the returned html. Capture per image:
     • src, srcset, sizes, alt, loading, fetchpriority, decoding, width, height, role, aria-hidden
     • Lazy-loader attributes: data-src, data-srcset, data-lazy-src, data-original, data-perfmatters-src, data-perfmatters-srcset, data-ewww-src, data-eio
     • Class signals: lazyload, lazyloaded, lazy, perfmatters-lazy, lazyload-eio
     • Parent <picture> <source> entries: type, srcset, media
     • Resolved absolute URL (for cross-origin / CDN detection)
   • Domain mode: run firecrawl_map (default limit: 500, hard cap; cost: ~0.5 credit per discovered URL — surface the estimate before running). From the URL list, select a sample of up to 10 pages: homepage, plus the top traffic landing pages (from DATA_getDomainKeywords's page aggregation if SE Ranking is connected, otherwise the deepest-nested URLs found in the sitemap — these are usually the content pages, not category indexes). Confirm the sample list and credit cost before scraping. Then scrape each (1 credit per page). Inventory is the union of every image on the sampled pages.
   • CSS background-images: flag as a known blind spot. We don't audit background-image: url(...) in stylesheets — those are not crawlable as content images by Google and don't get image-search visibility. Surface "{n} likely background-images detected (computed style references) — out of scope for this audit; review separately if hero/feature images are CSS-based" in the synthesis.

3. Alt-text audit

   • Load references/image-checks.md § Alt text. For each image:
     • Presence: missing alt (not alt="" — the empty-string form is valid for purely decorative images). Severity High.
     • Decorative-but-not-marked: alt="" is fine only if the image is genuinely decorative. Flag images with alt="" that also have a non-decorative src (e.g. product photo path, hero image path) as "verify decorative intent" (Medium).
     • Generic text: alt value matches a generic pattern — bare filename (image.jpg, IMG_1234.png), single generic noun (photo, picture, image, banner), CTA copy (click here, read more, learn more). Severity High.
     • Length: alt outside the 10–125 character window. Below 10 → Medium (probably not descriptive). Above 125 → Low (likely too verbose; screen readers truncate around there).
     • Keyword stuffing: the same keyword token appears 3+ times in the alt, or the alt is >50% keyword tokens. Severity Medium.
     • Identical alt across multiple images on the page: flag as a templating bug (Medium) — every product photo on a PDP should not share the same alt.

4. Format coverage (WebP / AVIF)

   • For each image, classify its served format from src extension (.webp, .avif, .jpg/.jpeg, .png, .gif, .svg) and <picture> <source> type attributes (image/avif, image/webp).
   • Compute three coverage metrics for the page (or domain sample):
     • % images served as WebP or AVIF directly (via the chosen <img src> or chosen <picture> <source>).
     • % images wrapped in <picture> with at least one modern-format <source> (progressive enhancement — fallback chain).
     • % images stuck on legacy formats (JPEG / PNG / GIF) with no modern alternative.
   • Per-image flags:
     • Legacy format with no <picture> modern alternative → image_legacy_format (Medium).
     • Animated GIF over 500 KB → recommend video (<video autoplay muted loop playsinline>) instead (Medium — performance + LCP impact). Source: Google PSI efficient-animated-content audit.
     • SVG used for photographic content → image_svg_misuse (Low — file size will be enormous; SVG is for icons/illustrations).
   • JPEG XL note. Chromium announced restoration of JPEG XL decoding (Rust-based) in November 2025 but it's not yet in Chrome stable. Surface as a Tips note: not actionable today, monitor for 2026.

5. Responsive coverage (srcset / sizes)

   • For each non-SVG raster image:
     • Missing srcset → image_no_srcset (Medium). Browser cannot pick a size-appropriate file; mobile users download desktop-sized images.
     • srcset present but no sizes and not inside <picture> → image_no_sizes (Medium). Browser falls back to viewport width assumptions and can pick the wrong candidate.
     • srcset declared but all candidates are the same width descriptor (1x only, or all w values within 100 px of each other) → image_srcset_useless (Low).

6. Lazy loading & LCP signals

   • For each image, classify the lazy-loading mechanism using references/lazy-loaders.md's taxonomy: native / perfmatters / ewww / js-generic / none. Report lazy_method alongside loading so a JS-loader-driven page isn't mis-flagged for missing loading="lazy" (the native attribute is intentionally absent there — the loader handles it).
   • LCP-candidate heuristic. The LCP image is typically the first <img> that:
     • Appears above the fold on a typical mobile viewport (no exact viewport without rendering; heuristic = first <img> in the rendered DOM that is not inside a <header> / <nav> / <aside> and has no loading="lazy" ancestor),
     • Has a large rendered area (width × height attributes both ≥ 300, or <picture> <source> with viewport-spanning sizes).
   • For the LCP candidate:
     • loading="lazy" set → image_lcp_lazy (High). Lazy-loading the LCP image directly harms LCP.
     • No fetchpriority="high" → image_lcp_no_fetchpriority (Medium). Lighthouse's prioritize-lcp-image audit; setting fetchpriority="high" moves the LCP image to the front of the browser's network queue.
   • For below-fold images (not the LCP candidate, not inside the first viewport):
     • Neither native loading="lazy" nor any JS-loader signal → image_below_fold_eager (Medium). Below-fold images should defer.
     • Missing decoding="async" → image_no_decoding_async (Low). Async decode prevents image decoding from blocking the main thread for non-LCP images.

7. CLS dimensions

   • For each image:
     • Missing both width and height attributes AND no inline aspect-ratio style → image_unsized (High). The browser cannot reserve space; the image will shift content when it loads. Matches Lighthouse unsized-images.
     • width and height present but the ratio mismatches the actual displayed ratio by >5% → image_aspect_mismatch (Low). Layout will shift on load.
   • The fix for both is the same: set width and height attributes to the image's intrinsic dimensions, and let CSS handle responsive scaling.

8. File-name quality

   • For each image's resolved URL, extract the filename. Flag:
     • Camera-default names (IMG_xxxx, DSC_xxxx, DSCN_xxxx, P_xxxx, Photo_xx) → image_camera_filename (Low).
     • Random-hash names (a3f9b2c.jpg, 0e8d1f7.webp — hex/base64 patterns with no human-readable tokens) → image_hash_filename (Low). Common with image CDNs; verify there's no SEO-friendly version available.
     • All-uppercase or all-underscore filenames → image_filename_style (Low). Convention is lowercase + hyphens.
   • Don't flag every CDN-served image as a problem — many CMSes hash filenames for cache busting and that's fine. The signal is meaningful when paired with a missing or generic alt on the same image (the page has no signal at all about what the image depicts).

9. ImageObject JSON-LD: detect, validate, generate

   • Detect: parse every <script type="application/ld+json"> block returned by Firecrawl. Find existing ImageObject blocks — either top-level (for image-search rich results) or nested under Article.image, Product.image, Recipe.image, etc.
   • Validate against Google Images' guidelines (see references/image-checks.md § ImageObject for the field list). For a top-level ImageObject:
     • Required: @context, @type: ImageObject, contentUrl (the image URL), creator or copyrightHolder.
     • Recommended for licensable-images rich results: license (URL to the license terms), acquireLicensePage (URL where users can buy/license the image), creditText (how the creator should be credited).
     • Common mistakes: url instead of contentUrl, author as a bare string instead of a Person / Organization object, dimensions as strings instead of Number.
   • Generate: for each image that doesn't already have an ImageObject block AND that meets the "worth marking up" threshold (the image is the page's hero / first-fold and the page has a clear creator/owner), produce a paste-ready block from templates/image-object.json, filling in fields from the live HTML. Mark unresolved fields as {REPLACE: ...}. The generated file is emitted as 02-remediation/image-object.jsonld (the .jsonld extension marks it as a deliverable for <script type="application/ld+json">).
   • Don't generate ImageObject for every <img>. It's noise. Limit to the hero image and any image that should be eligible for licensable-images rich results.

10. Optional: PageSpeed Insights byte savings (only if ~/.config/seo-skills/google-api.json is present, Tier ≥ 0)

    • Run python3 scripts/pagespeed_check.py "{url}" --strategy=mobile --json and --strategy=desktop --json (2 API calls per target URL — within PSI's 25k/day free quota).
    • Pull the following audits from the JSON response and merge per-image wastedBytes into the remediation list:
      • modern-image-formats — bytes savable by serving WebP/AVIF (overlaps with step 4; PSI's number is authoritative).
      • uses-optimized-images — bytes savable by re-compressing.
      • uses-responsive-images — bytes savable by serving size-appropriate files (overlaps with step 5).
      • offscreen-images — bytes deferrable by lazy-loading below-fold images (overlaps with step 6).
      • unsized-images — page elements missing dimensions (cross-checks step 7).
      • prioritize-lcp-image — confirms or contradicts the step-6 LCP-candidate heuristic and gives PSI's authoritative LCP element.
      • efficient-animated-content — confirms animated-GIF flagging from step 4.
    • Each PSI audit returns details.items[] with url and wastedBytes. Join on image URL (resolved absolute) and tag each remediation row with psi_wasted_bytes so the prioritised list orders by real savings, not heuristic severity alone.
    • If PSI is configured but returns no audits (likely a 4xx — usually a private/protected URL Lighthouse can't load): note "PSI: could not analyse {url} ({reason})" and continue with non-PSI signals.

11. Optional: SE Ranking audit cross-reference (only if SE Ranking MCP is connected and a recent audit exists)

    • DATA_listAudits → find the most recent audit for the domain. If none exists or it's >30 days old, skip this step (don't trigger a new audit from the image skill — that's seo-technical-audit's call to make).
    • For each image-related audit code, DATA_getAuditPagesByIssue:
      • images_oversized (or whatever SE Ranking's current code is for "uncompressed images")
      • images_no_alt
      • images_broken (404 / 5xx image URLs)
      • images_no_dimensions (CLS)
    • Merge findings: for any image flagged by both the audit and this skill, elevate severity by one step. For any audit-flagged URL that the Firecrawl sample didn't include, list it under "Audit-flagged pages not in this sample" with a recommendation to re-run on those URLs specifically.

12. Synthesise IMAGES.md. Build the remediation table sorted by:

    1. Severity (Critical → High → Medium → Low),
    2. Within severity: PSI wastedBytes descending (when PSI ran), else affected-image count descending,
    3. Then alphabetical by issue code.