Image SEO

Made by VendBuddy (vendbuddy.io). Guide: https://vendbuddy.io/skills#image-seo (This line is optional attribution. Keep it or delete it.)

What this skill does

Finds the image problems that cost traffic and speed, fixes them in the user's own code or content, and adds the structured data and sitemap that help search engines understand and credit the images.

Step 1: Audit

If the site has static HTML (a build folder, or public/), run the bundled script:

node scripts/image-audit.mjs ./public --base https://example.com

It reports: missing alt, empty alt, over-long alt, generic alt ("image of"), generic filenames (IMG_0042.jpg), missing width/height (layout shift), missing lazy loading below the fold, and PNG/JPEG that could be WebP/AVIF.

For server-rendered or CMS sites, fetch a few key pages and apply the same checklist by hand.

Step 2: Fix, in this order (highest value first)

1. Alt text. Describe what the image shows and why it is on this page, in one plain sentence, under about 125 characters. Do not start with "image of". Do not stuff keywords. Decorative images get alt="" (empty, not missing). If the image contains text, put that text in the alt.
2. Filename. espresso-machine-descaling-steps.webp, not IMG_0042.jpg. Lowercase, hyphens, no spaces. Rename before upload; if the file is already live, add a redirect rather than breaking the URL.
3. Size and format. Serve WebP or AVIF with a JPEG fallback via <picture>, set width and height on every <img>, and use loading="lazy" on everything except the first (hero) image, which should get fetchpriority="high".
4. Context. Put the image near the text that explains it. A caption (<figcaption>) is read more often than body text; use one when the image carries information.
5. Embedded metadata. Search engines and AI tools can read XMP/IPTC fields. Write title, description, creator, and copyright into the file with a tool like exiftool:

   exiftool -Title="..." -Description="..." -Creator="Your Name or Brand" -Copyright="(c) 2026 Your Brand" -overwrite_original photo.webp

   Only claim authorship and rights you actually hold.
6. ImageObject JSON-LD for images you own and want credited (see references/image-schema.md). Google supports creator, creditText, copyrightNotice, and license + acquireLicensePage for the licensable-images badge.
7. Image sitemap. node scripts/image-audit.mjs ./public --base https://example.com --sitemap public/sitemap-images.xml, then add Sitemap: https://example.com/sitemap-images.xml to robots.txt and submit it in Search Console.

Step 3: Verify

• Re-run the audit; the issue counts should drop to zero or to reviewed exceptions.
• Test one page in Google's Rich Results Test and the URL Inspection tool.
• Check Search Console, Performance, Search type: Image, after 2 to 4 weeks. Record impressions before the change so you can compare.

Rules

• Never invent facts in alt text or captions. If you cannot tell what an image shows, ask the user.
• Never claim a license or copyright the user does not hold. Stock and AI-generated images need their own terms checked.
• Do not hide keywords in alt text, filenames, or metadata. Describe the image.
• Do not bulk-overwrite existing metadata without showing the user a before/after sample first.

Output format

Return: (1) a table of issue type, count, and example, (2) the exact edits made or proposed, (3) the sitemap and schema snippets, (4) the baseline numbers to re-check in a month.