← All skills

🧰 Image Alt Text Audit

Scans a site's local HTML, Markdown or MDX files for images with missing, empty or useless alt text and returns a fix list with suggested alt text drawn from the surrounding copy.

Site auditsBeginner · Copy and use. No edits needed.FreePublished Nov 1, 2026
Tested on✓ CodexSee test log
Free download

ZIP with SKILL.md and any reference files.

Download ZIP

What it does

Run it inside a site repo or a folder of built HTML. It finds every image, sorts the alt text into missing, empty, filename-style or fine, and writes suggested alt text based on the caption and nearby paragraph. It does not look at the pixels, so it says when it is guessing from context.

Use it when: you want a quick accessibility pass on a blog or landing page before launch, or after a batch of new posts.

Works with: Claude Code, Cursor and Codex. Install the ZIP into your agent’s skills folder, open the repo and ask for an alt text audit.

Output preview

Task given to the agent: “Read and follow .agents/skills/image-alt-text-audit/SKILL.md before you answer. Use that skill's output format. Audit image alt text under the site/ folder in this workspace. Read-only; do not edit files. Return the skill's summary table and flag MISSING, EMPTY, FILENAME, LONG and OK.”

AFTER · with the skill
Alt text audit: `site/`
Summary: 5 images | MISSING 1 | EMPTY 1 | FILENAME 2 | LONG 1 | OK 1
| File:line | Image src | Status | Current alt | Suggested alt |
| `site/index.html:6` | `/img/hero-final-v2.jpg` | MISSING | — | `Hero image of a matte white ceramic mug on a table` |
| `site/index.html:7` | `/img/mug.jpg` | FILENAME | `IMG_4401.jpg` | `Matte white ceramic mug on a wooden table` |
| `site/index.html:8` | `/img/box.png` | EMPTY | `` | `Needs a human look` |
| `site/index.html:10` | `/img/glaze-detail.jpg` | LONG | `A close-up photograph of the matte white glaze on the ceramic mug rim showing the slightly speckled texture under soft daylight near a kraft gift box on a wooden table in a bright studio setting with extra words that make this alt text far too long for accessibility guidelines and screen readers` | `Close-up of the matte white glaze on the mug rim` |
| `site/index.html:14` | `/img/logo.svg` | OK | `Demo shop logo` | — |
| `site/about.html:7` | `/img/kiln.jpg` | FILENAME | `kiln-shot-final.png` | `Kiln interior with stacked ceramic pieces` |

Real, unedited output from recorded runs on Nov 1, 2026 · Codex (codex-cli 0.163.0) · model gpt-5.4-mini. Test inputs are fixtures (fictional brand, example.com links). AI output can be wrong: check facts before you publish anything like it.

Install

Unzip first. You get a folder named image-alt-text-audit containing SKILL.md.

Claude Code

Put the folder in your personal skills directory, or in the project to share it with your team.

~/.claude/skills/image-alt-text-audit/SKILL.md.claude/skills/image-alt-text-audit/SKILL.md

Claude Code picks up new skills in the current session (run /reload-skills if the skills folder didn't exist when the session started). The skill loads when a task matches its description.

Claude.ai

Turn on code execution (Settings → Capabilities), then go to Customize → Skills, click +, then Create skill → Upload a skill, and select the ZIP. Full guide.

Cursor

Put the folder in your user or project skills directory. Cursor also reads .claude/skills.

~/.cursor/skills/image-alt-text-audit/SKILL.md.cursor/skills/image-alt-text-audit/SKILL.md

Codex

Put the folder in your user or repository skills directory, then restart Codex or run /skills to check it is listed.

~/.agents/skills/image-alt-text-audit/SKILL.md.agents/skills/image-alt-text-audit/SKILL.md

These are the standard skill locations for each tool. The tools a skill is verified on are listed under “Tested on” above, if any.

Test log

Date (UTC)ToolModelRunResultChecksTokens in / out
Nov 1, 2026Codexgpt-5.4-miniTestPassed
4/4
  • ✓ codex exited cleanly
  • ✓ skill was loaded (SKILL.md read)
  • ✓ output has substance (80+ words) (189 words)
  • ✓ no obvious secret leak
51,303 / 657
Nov 1, 2026Codexgpt-5.4-miniTestFailed
3/4
  • ✓ codex exited cleanly
  • ✗ skill was loaded (SKILL.md read)
  • ✓ output has substance (80+ words) (125 words)
  • ✓ no obvious secret leak
36,926 / 469
Nov 1, 2026Codexgpt-5.4-miniTestFailed
3/4
  • ✓ codex exited cleanly
  • ✓ skill was loaded (SKILL.md read)
  • ✗ output has substance (80+ words) (71 words)
  • ✓ no obvious secret leak
84,523 / 725

Each row is a real run recorded by our test runner. For each tool, the latest test run decides whether it appears under “Tested on”. Baseline runs do the same task with no skill installed and never count.