Why "Optimize Your Images" Is Bad Advice

I think a lot of founders hear "optimize your images" and still do not know what that means in practice.

Usually it is some mix of wrong format, wrong dimensions, duplicate exports, hero image too heavy. Not bad code, just bad file decisions that nobody thought about at launch.

I kept hitting the same cleanup on different projects. The steps were always the same: find the bloated images, figure out which ones are safe to convert, which ones need manual review, and which ones you should not touch at all.

So I turned it into a Claude Code skill.

What Image Audit does

The skill runs two audits.

Repo audit. It walks through your codebase looking for PNG, JPG, and other image files. For each one, it checks file size, format, and how it is referenced in your code. It flags anything over 500KB and identifies images that could safely be converted to WebP.

Supabase audit. If you have a Supabase storage bucket, it scans that too. Same checks: format, size, duplicates, and whether the image is actually referenced anywhere.

After both audits, you get a migration plan. Not a list of commands to run blindly. A plan that separates:

• Safe WebP wins (images that can be converted without risk)
• Manual review items (screenshots, logos, transparent assets, UI elements)
• Leave-alone items (already optimized, or too risky to touch)

Why audit-first matters

The obvious approach is to just convert everything to WebP and call it done. That breaks things.

Screenshots with text get blurry. Logos with transparency lose quality. UI assets with precise pixel borders get artifacts. Hero images that were carefully exported at specific dimensions get resized wrong.

I intentionally made this conservative. I would rather have a tool people trust than an "optimizer" that silently damages assets.

The skill checks references before changing anything. If an image is imported in your code, it updates the references too. If it cannot verify the reference chain, it puts the image in manual review instead of guessing.

Install

Ask your coding agent to install it:

npx image-audit-skill install --claude

Or grab it from the repo: github.com/Saamael/image-audit-skill

How it works

The current version supports Supabase storage out of the box, but the concept is flexible. It can do the same for other platforms. The idea is simple: find the images that are costing you performance, convert them to an optimized format, and leave the risky ones alone.