# Image Seo Audit

> Audit a website's images for SEO and Core Web Vitals. Crawls pages to find images with missing or empty alt text, missing width/height (layout shift), no lazy loading, oversized files, legacy formats (no WebP/AVIF), generic filenames, and broken image URLs. Use when the user asks to audit, analyze, check, or improve image SEO, alt text, image accessibility, image file sizes, image formats, or ima…

- **Type:** Skill
- **Install:** `agentstack add skill-jakelabate-claude-seo-skills-image-seo-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JakeLabate](https://agentstack.voostack.com/s/jakelabate)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JakeLabate](https://github.com/JakeLabate)
- **Source:** https://github.com/JakeLabate/Claude-SEO-Skills/tree/main/skills/image-seo-audit
- **Website:** https://www.jakelabate.com/claude-seo-skills/

## Install

```sh
agentstack add skill-jakelabate-claude-seo-skills-image-seo-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Image SEO Audit

Audit the images of a website and produce an actionable SEO and performance report.

## When to use this skill

Use this skill when the user asks to:

- Audit or analyze the images on a website for SEO or accessibility
- Find images with missing, empty, or poor `alt` text
- Find images that cause layout shift (missing `width`/`height`) or load slowly (no lazy loading, oversized files)
- Identify images served in legacy formats instead of WebP/AVIF
- Find broken images or generic, uninformative filenames

## Inputs to collect

Before starting, confirm with the user:

1. **Site URL or local files** — a live site root URL (e.g., `https://example.com`), a sitemap URL, a list of URLs, or a local folder of HTML files.
2. **Scope** — full site, a specific section (e.g., `/blog/`), or a list of URLs.
3. **Crawl limits** — max pages (default 500) for live crawls.
4. **File checks** — whether to fetch each image to measure byte size and detect broken images (the `--check-files` flag; slower but enables the oversized-file and broken-image checks).
5. **Size budget** — the byte threshold above which an image is "oversized" (default 200 KB).

## Workflow

### Step 1: Gather the page set and extract images

- If a sitemap is available (`/sitemap.xml`), it is used to get the canonical page list.
- Otherwise, the crawler starts from the homepage following only same-host links.
- For local HTML folders, all `.html` files are enumerated.

Use `scripts/extract_images.py` to build an image inventory:

```bash
python3 scripts/extract_images.py https://example.com --max-pages 500 --check-files --output image_inventory.json
# already crawled once (e.g. in a full SEO audit)? skip the crawl and reuse the shared cache:
# python3 scripts/fetch_pages.py https://example.com --output page_cache.json
# python3 scripts/extract_images.py --from-cache page_cache.json --check-files --output image_inventory.json
```

For every `` the inventory records: absolute `src`, `alt` (null if the attribute is absent vs. empty string if `alt=""`), `width`/`height` attributes, `loading`, whether it has a `srcset`, whether it sits inside a ``, and its position in the page. With `--check-files`, each unique image URL is HEAD-requested to record HTTP status, content type, and byte size.

### Step 2: Run the audit checks

Use `scripts/audit_images.py` to run all audit checks against the inventory:

```bash
python3 scripts/audit_images.py image_inventory.json --max-bytes 200000 --output audit_report.json
```

The oversized-file and broken-image checks only run if the inventory was built with `--check-files`.

### Step 3: Evaluate the audit checks

Evaluate each check defined in `references/audit-checks.md`. The core checks are:

| Check | Severity |
|---|---|
| Missing `alt` attribute | High |
| Broken image (non-200 URL) | High |
| Missing `width`/`height` (layout shift) | Medium |
| Oversized file (> size budget) | Medium |
| Not lazy-loaded (below the fold) | Low |
| Legacy format with no modern `` source | Low |
| Generic filename | Low |
| Alt text too long (> 125 chars) | Low |
| Redundant alt prefix ("image of…") | Low |
| Empty `alt=""` (decorative — confirm intent) | Informational |
| Duplicate alt reused across many images | Informational |

### Step 4: Produce the report

Write a report following the structure in `references/report-template.md`:

1. **Summary** — pages crawled, images found, alt-text coverage %, issue counts by severity
2. **Issues** — one section per failing check, listing the page, the image, and a specific fix
3. **Prioritized action list** — ordered by severity and estimated impact

### Step 5: Recommend fixes

For each issue, give a concrete, copy-pasteable recommendation. When drafting alt text:

- Describe what the image shows and its purpose on the page, in roughly 5–15 words
- Never start with "image of" or "picture of" — screen readers already announce it as an image
- Use `alt=""` only for purely decorative images; never invent details not visible in the image
- For dimensions, recommend the exact `width`/`height` attributes (or CSS `aspect-ratio`) that match the rendered size
- For oversized or legacy images, recommend compressing and serving WebP/AVIF via `` with a fallback

Example recommendations:

- Add alt text to the hero image on `/`: `alt="Team of nurses reviewing a patient chart at a bedside"`
- Add `width` and `height` to the 6 product thumbnails on `/shop` to stop layout shift
- Convert `/images/hero.png` (1.4 MB) to WebP and serve it through ``; this image loads on every page

## Optional: export the report

### As a Word document (.docx)

If the user wants the report as a `.docx` (for example, to share with stakeholders or attach to a ticket), save the Markdown report to a file and convert it:

```bash
python3 scripts/md_to_docx.py report.md --output report.docx
```

`scripts/md_to_docx.py` uses only the Python standard library (no `pip install`) and renders headings, tables, lists, links, bold/italic, and code blocks. Offer this whenever a user asks for a Word doc, a `.docx`, or a shareable/downloadable report.

### As a CSV of findings (.csv)

If the user wants the raw findings as a spreadsheet (for filtering, sorting, or triage in Sheets or Excel), convert the audit's `audit_report.json` directly:

```bash
python3 scripts/findings_to_csv.py audit_report.json --output findings.csv
```

`scripts/findings_to_csv.py` is also standard-library only. It writes one row per finding, with `check` and `severity` columns prepended and list fields (e.g. the pages sharing a duplicate value) joined with `; `. Unlike the `.docx`, which reformats the written report, the CSV is a direct dump of the structured findings — offer it whenever a user wants the data itself, a spreadsheet, or to slice findings by check or severity.

## Resources

- `scripts/md_to_docx.py` — convert the Markdown report into a Word (.docx) document (standard library only)
- `scripts/findings_to_csv.py` — flatten the audit findings JSON into a CSV, one row per finding (standard library only)
- `references/audit-checks.md` — full definitions, thresholds, and rationale for every audit check
- `references/report-template.md` — report output structure
- `scripts/extract_images.py` — crawl a site and build the image inventory (add `--check-files` for size/format checks)
- `scripts/audit_images.py` — run audit checks against an image inventory JSON file

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JakeLabate](https://github.com/JakeLabate)
- **Source:** [JakeLabate/Claude-SEO-Skills](https://github.com/JakeLabate/Claude-SEO-Skills)
- **License:** MIT
- **Homepage:** https://www.jakelabate.com/claude-seo-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jakelabate-claude-seo-skills-image-seo-audit
- Seller: https://agentstack.voostack.com/s/jakelabate
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.