Alt Text And Caption Pass
Alt text serves screen readers first and image search second, and the two goals mostly agree. Bulk generation ignores the surrounding copy and produces descriptions that repeat what the paragraph already said, which helps neither. The opposite failure is as common: descriptive alt on every icon and divider, so a screen reader user hears noise between paragraphs. Sort the images that carry meaning from the ones that do not before writing anything.
FORMAT
image-alt-and-caption-pass.md
WHEN TO REACH FOR THIS
Use when a page set has alt text that was generated in bulk, left empty, or filled with file names.
The skill file
image-alt-and-caption-pass.md
---
name: image-alt-and-caption-pass
description: Use when a page set has alt text that was generated in bulk, left empty, or filled with file names.
---
# Alt Text And Caption Pass
Alt text serves screen readers first and image search second, and the two goals mostly agree. Bulk generation ignores the surrounding copy and produces descriptions that repeat what the paragraph already said, which helps neither. The opposite failure is as common: descriptive alt on every icon and divider, so a screen reader user hears noise between paragraphs. Sort the images that carry meaning from the ones that do not before writing anything.
## What you need first
- Every image on the page set with its surrounding paragraph, current alt, caption and file name
- A decision on which images are decorative, which needs whoever chose them
- Image-search impressions from Search Console for any images already earning traffic
## Method
1. List each image next to the sentence it sits beside. Alt written without the surrounding copy is what produces duplicates of the body text, the standard bulk-tool output.
2. Split into three groups: images carrying information not in the text, images illustrating text already present, and decorative images. Mixing these is what produces bad alt at scale.
3. Give informational images alt that states the information rather than the appearance. For a chart, that is the finding, not the words "bar chart".
4. Give decorative images an empty alt attribute rather than no attribute. Empty alt tells assistive technology to skip the image; a missing attribute can make it read the file name aloud.
5. Write captions for the images people will actually stop at. Captions are read far more than body copy and, unlike alt, they are visible to every reader.
6. Rename meaningful files to describe the content in words, but restrict renames to new images or a deliberate batch, since renaming a file that already earns image-search traffic resets its history.
7. Check the result with a screen reader or the accessibility tree on the two or three most image-heavy pages. Counting alt attributes tells you nothing about whether the page is listenable.
## What this produces
Per page: revised alt for informational images, empty alt on decorative ones, captions where they earn attention, and a rename list scoped to new files.
## Where this goes wrong
- Generating alt in bulk without the surrounding paragraph, producing text that duplicates the copy for both readers and image search
- Adding descriptive alt to icons and dividers, which makes the page slower and more confusing to listen to
- Renaming image files that already rank, which discards their history for a cosmetic gain
- Treating alt as a place for keywords, which reads as spam to a person listening and does not help the ranking it was meant to
---
From the QuQi skill library - https://www.quqi.io/skills/image-alt-and-caption-pass
Free to download · no account, no email
What you need first
-
Every image on the page set with its surrounding paragraph, current alt, caption and file name
-
A decision on which images are decorative, which needs whoever chose them
-
Image-search impressions from Search Console for any images already earning traffic
Method
-
01
List each image next to the sentence it sits beside. Alt written without the surrounding copy is what produces duplicates of the body text, the standard bulk-tool output.
-
02
Split into three groups: images carrying information not in the text, images illustrating text already present, and decorative images. Mixing these is what produces bad alt at scale.
-
03
Give informational images alt that states the information rather than the appearance. For a chart, that is the finding, not the words "bar chart".
-
04
Give decorative images an empty alt attribute rather than no attribute. Empty alt tells assistive technology to skip the image; a missing attribute can make it read the file name aloud.
-
05
Write captions for the images people will actually stop at. Captions are read far more than body copy and, unlike alt, they are visible to every reader.
-
06
Rename meaningful files to describe the content in words, but restrict renames to new images or a deliberate batch, since renaming a file that already earns image-search traffic resets its history.
-
07
Check the result with a screen reader or the accessibility tree on the two or three most image-heavy pages. Counting alt attributes tells you nothing about whether the page is listenable.
What this produces
Per page: revised alt for informational images, empty alt on decorative ones, captions where they earn attention, and a rename list scoped to new files.
Where this goes wrong
-
Generating alt in bulk without the surrounding paragraph, producing text that duplicates the copy for both readers and image search
-
Adding descriptive alt to icons and dividers, which makes the page slower and more confusing to listen to
-
Renaming image files that already rank, which discards their history for a cosmetic gain
-
Treating alt as a place for keywords, which reads as spam to a person listening and does not help the ranking it was meant to
Use this skill in your own AI
The download is a plain markdown file with the name and trigger in its frontmatter. Where an assistant supports skills it can load itself, that frontmatter is what it reads to decide this one applies.
Claude Code
Save it as ~/.claude/skills/image-alt-and-caption-pass/SKILL.md and Claude loads it on its own when what you are doing matches the trigger line. Put it in .claude/skills inside a project instead if the whole team should have it.
Claude
Upload the file in the skills section of your settings. Once it is there it applies itself in any conversation where the trigger fits, so you do not have to remember it exists.
ChatGPT
There is no skills format to install into, so paste the file contents into a Project instruction or a Custom GPT instead. It then applies to every chat in that project rather than only the one you paste it into.
Anything else
Paste the markdown into the chat before your question. It works in any assistant, it just has to be pasted again each time.
Questions about this skill
When is a manual pass worth it rather than generating alt in bulk?
When a page set has alt generated in bulk, left empty, or filled with file names. Bulk generation is the obvious alternative and it writes without the surrounding paragraph, so it describes what the copy already said. That helps neither a screen reader user nor image search. Sort images by whether they carry information before writing a word.
What do I need in hand before starting?
Every image with the sentence it sits beside, its current alt, caption and file name, a decision on which images are decorative, and image-search impressions for any already earning traffic. The decorative call needs whoever chose the images. Without the impressions you cannot see which files are worth leaving alone, and a rename resets that history.
What do I end up with, and which part gets used?
Revised alt on informational images, empty alt on decorative ones, captions where readers stop, and a rename list scoped to new files. The empty alt is the part people skip and it matters most: an empty attribute tells assistive technology to skip the image, while a missing attribute can have the file name read aloud instead.
What most often ruins this?
Putting descriptive alt on icons and dividers, so a page becomes slow and confusing to listen to. Counting alt attributes will call that a success, which is why it survives audits. Check with a screen reader or the accessibility tree on the two or three most image-heavy pages, and never rename a file that already earns image traffic.
More in On-page SEO