Why 'Optimize Your Images' Is Bad Advice

Source: Dev.to

I think a lot of founders hear “optimize your images” and still don’t know what that means in practice.

Usually it’s a mix of wrong format, wrong dimensions, duplicate exports, or a hero image that’s 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 need manual review, and which 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

• 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.
• Flags anything over 500 KB 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 blind list of commands. The plan 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 incorrectly.

I intentionally made this conservative. I’d 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:

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.