Fast, SEO-Friendly Website Images: By Hand, or With One Claude Code Skill

A client sends a folder of photos from a professional shoot. On the restaurant site I built for Café des Artistes that was 70 files, 36 megapixels each, 12–20 MB apiece, 1 GB in total, named Cafe de Artistes 07.02.26-17.jpg — with two spaces in the middle. Dropping them into public/ as they are means every visitor downloads far more pixels than any screen can show, and search engines learn nothing from the file names.

The fix is a short pipeline. Done once, the same photos ended up at 42 KB for a phone-sized AVIF and 225 KB for a full-width 2400 px hero, answered in 14 ms, with names like pizza-margherita-top and alt text that says what is in the frame.

Make contact sheets — many small thumbnails on one image, each labelled with its file name — and go through all of them. Note the subject, whether it is portrait or landscape, whether someone’s face is visible, and which shots are near-duplicates.

mkdir -p sheets
magick montage -label '%f' raw/*.jpg \
  -tile 6x -geometry 300x300+6+6 -pointsize 14 sheets/sheet-%02d.jpg

-label has to come before the input files, or the tiles get no captions. With 40 MP originals this is slow; the skill in Way 2 decodes each file at reduced size first, which is many times faster.

Google reads image file names as a light hint about the content, and a developer reads them every day. Use a category prefix, then the subject, then the variant:

• Lowercase kebab-case, English, ASCII — no spaces, dates or camera numbers.
• Variants of one subject get a suffix: -top, -close-up, -hand, -steam.
• People get their own prefix (team-, guest-), so they are easy to leave out when a client prefers no faces on the site.
• Honest names: if you are not sure what a dish is, use the safest accurate description and ask.

Write the decisions into a two-column CSV, original,name. It drives the next step and doubles as a record of which original became which file.

A master is the single high-quality copy every web size is made from. 2400 px on the long edge covers a full-width image on a 1440 px retina screen. JPEG at quality 92 with 4:4:4 chroma keeps saturated reds — tomato, wine — from smearing.

mkdir -p assets/photos
magick "raw/DSC_0042.jpg" -auto-orient -colorspace sRGB -filter Lanczos \
  -resize '2400x2400>' -strip -interlace JPEG \
  -sampling-factor 4:4:4 -quality 92 assets/photos/pizza-margherita-top.jpg

• -auto-orient applies the camera’s rotation flag before it is stripped, so portrait shots stay portrait.
• -strip removes camera metadata (often 50–100 KB of it, and sometimes GPS coordinates).
• assets/photos/ is not served — masters are inputs, not something visitors download.

Never delete the originals. Move them out of public/ (everything there is deployed and bloats the repository) into a folder outside the project, and back it up. They are the only copy at full resolution.

Compare a master with a lossless resize of its original. PSNR (peak signal-to-noise ratio) gives one number in decibels:

magick "raw/DSC_0042.jpg" -auto-orient -filter Lanczos -resize '2400x2400>' -depth 8 ref.ppm
magick compare -metric PSNR ref.ppm assets/photos/pizza-margherita-top.jpg null:

• 40 dB and above — visually lossless. Most photos land at 42–46 dB.
• 35–40 dB — normal for very fine texture (wood grain, pizza crust). Put a 100 % crop of both side by side; on the café set the 36 dB pizza was indistinguishable.
• Under 15 dB — the comparison is wrong, not the image: a rotated reference or a mismatched pair.

AVIF came out 25–50 % smaller than WebP at the same measured quality on these photos; WebP covers the few browsers without AVIF. Render both at every width the site asks for, and put a hash of the master in the file name so a changed photo gets a new URL:

// scripts/build-images.mjs — run with: node scripts/build-images.mjs
import { createHash } from 'node:crypto';
import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import sharp from 'sharp';

const WIDTHS = [256, 384, 640, 828, 1200, 1600, 2048, 2400];
const SRC = 'assets/photos';
const OUT = 'public/images/opt';
const manifest = {};

rmSync(OUT, { recursive: true, force: true });
mkdirSync(OUT, { recursive: true });

for (const file of readdirSync(SRC).filter((f) => f.endsWith('.jpg'))) {
  const name = file.replace(/\.jpg$/, '');
  const input = readFileSync(`${SRC}/${file}`);
  const hash = createHash('sha256').update(input).digest('hex').slice(0, 8);
  const { width } = await sharp(input).metadata();
  const widths = [...new Set([...WIDTHS.filter((w) => w < width), width])];
  for (const w of widths) {
    const img = sharp(input).resize({ width: w });
    const stem = `${OUT}/${name}.${hash}.${w}`;
    await img.clone().avif({ quality: 64, effort: 5, chromaSubsampling: '4:4:4' }).toFile(`${stem}.avif`);
    await img.clone().webp({ quality: 82, effort: 6, smartSubsample: true }).toFile(`${stem}.webp`);
  }
  manifest[name] = { v: hash, widths };
}
writeFileSync('data/image-manifest.json', JSON.stringify(manifest, null, 2));

Add it to package.json as "images": "node scripts/build-images.mjs". 56 photos took about six minutes. Commit the output instead of building it on every deploy — it only changes when a photo does.

Why not let next/image convert to AVIF on the fly?

Next.js can serve AVIF with one line, images.formats: ["image/avif", "image/webp"]. It encodes each image the first time a size is requested — and AVIF is slow to encode. Measured on the café site:

The site had a preloader that waited for the hero image, so every cold view started with a second of nothing, and it happened again for every new screen width and after every cache expiry. Encoding once, before deploy, removes the wait entirely. Keep on-the-fly optimisation for images you cannot know at build time, such as user uploads.

Keep <Image> everywhere — fill, sizes, lazy loading and preload all still work — and give it a custom loader that points at the pre-rendered files. In the code, a photo is referred to by name: <Image src="/img/pizza-margherita-top" … />.

// lib/image-loader.ts
'use client';

import manifest from '@/data/image-manifest.json';

const photos: Record<string, { v: string; widths: number[] }> = manifest;

export default function imageLoader({ src, width }: { src: string; width: number }) {
  if (!src.startsWith('/img/')) return `${src}?w=${width}`; // logos, SVGs
  const name = src.slice('/img/'.length);
  const photo = photos[name];
  if (!photo) return src;
  const w = photo.widths.find((x) => x >= width) ?? photo.widths.at(-1);
  return `/img/${name}.${photo.v}.${w}`;
}

In next.config.ts, rewrite /img/… to the AVIF file when the browser’s Accept header lists AVIF and to the WebP file otherwise, and cache both for a year — the hash in the name makes that safe:

images: {
  loader: 'custom',
  loaderFile: './lib/image-loader.ts',
  deviceSizes: [640, 828, 1200, 1600, 2048, 2400], // same widths as the script
  imageSizes: [256, 384],
},
async rewrites() {
  return [
    { source: '/img/:file', has: [{ type: 'header', key: 'accept', value: '.*image/avif.*' }], destination: '/images/opt/:file.avif' },
    { source: '/img/:file', destination: '/images/opt/:file.webp' },
  ];
},
async headers() {
  return [{
    source: '/img/:file',
    headers: [
      { key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
      { key: 'Vary', value: 'Accept' },
    ],
  }];
},

One trap: anything that loads a photo without <Image> — a canvas animation calling new Image(), a CSS background-image, a hand-written <img> — skips the loader and asks for /img/name, which does not exist. On the café site that was a scroll scene drawn on a canvas; it showed up as three 404s. Search for those and pass them through imageLoader({ src, width }).

Without Next.js: the picture element

On a plain HTML site, Vite, WordPress or anything else, let the browser choose the format itself. No server rules are needed, which also makes this the right choice behind a CDN that ignores Vary: Accept:

<picture>
  <source type="image/avif" sizes="(min-width: 768px) 50vw, 100vw"
          srcset="/images/opt/pizza-margherita-top.3af62bcf.640.avif 640w,
                  /images/opt/pizza-margherita-top.3af62bcf.1200.avif 1200w,
                  /images/opt/pizza-margherita-top.3af62bcf.2400.avif 2400w">
  <img src="/images/opt/pizza-margherita-top.3af62bcf.1200.webp"
       srcset="/images/opt/pizza-margherita-top.3af62bcf.640.webp 640w,
               /images/opt/pizza-margherita-top.3af62bcf.1200.webp 1200w,
               /images/opt/pizza-margherita-top.3af62bcf.2400.webp 2400w"
       sizes="(min-width: 768px) 50vw, 100vw"
       width="2400" height="1600" alt="Pizza Margherita from above"
       loading="lazy" decoding="async">
</picture>

Generate this markup from the manifest with a small helper in your templates rather than typing hashes by hand. Serve /images/opt/ with Cache-Control: public, max-age=31536000, immutable.

• Alt text in the site’s language, describing the frame — “Pizza Margherita von oben”, not “food image”. Leave alt="" only on purely decorative backgrounds.
• A separate Open Graph image: 1200×630 JPEG, around 120 KB. Facebook, LinkedIn and WhatsApp do not reliably show AVIF or WebP link previews.
• The hero is preloaded, everything below the fold is lazy. The hero is usually the Largest Contentful Paint.
• `sizes` matches the layout. A 300 px card with sizes="100vw" downloads a 2400 px file on a retina screen.
• Every image has dimensions or an aspect-ratio box, so the page does not jump while it loads.
• Photos fit their slots: portrait shots in tall frames, landscape in full-width ones, and an image that matches the text beside it.

Everything in Way 1 — including the mistakes I hit along the way — is packaged as a Claude Code skill called web-image-pipeline. It holds the instructions and five scripts: contact sheets, masters, the quality check, the AVIF/WebP build, and a page checker that requests every image URL on your pages.

web-image-pipeline/
├── SKILL.md                  # the workflow and the reasons behind each step
├── references/
│   ├── nextjs.md             # loader, rewrites, cache headers, canvas pitfall
│   └── static-html.md        # <picture>, CSS image-set, CDN cache headers
├── scripts/
│   ├── contact_sheet.py      # numbered sheets of every photo
│   ├── prepare_masters.py    # rename + 2400 px masters from a CSV
│   ├── quality_check.py      # PSNR against the originals
│   ├── build_images.mjs      # AVIF + WebP at fixed widths, hashed names
│   └── check_pages.py        # every image URL on your pages answers 200
├── README.md
├── LICENSE                   # MIT
└── CITATION.cff

The skill is open source under the MIT licence: github.com/sabbirsami/web-image-pipeline. First check the three things it needs — ImageMagick 7, Python 3 and Node:

magick -version | head -1   # ImageMagick 7.x
python3 --version           # Python 3.x
node --version              # any current LTS

Then clone it into your personal skills folder, which makes it available in every project:

git clone https://github.com/sabbirsami/web-image-pipeline.git ~/.claude/skills/web-image-pipeline

Or install it for one project only, so everyone who clones the project gets it too:

git clone https://github.com/sabbirsami/web-image-pipeline.git .claude/skills/web-image-pipeline
rm -rf .claude/skills/web-image-pipeline/.git
git add .claude/skills/web-image-pipeline && git commit -m "Add web-image-pipeline skill"

Restart Claude Code, type / and web-image-pipeline is in the list. In each project that uses it, add sharp once with npm i -D sharp. To update a personal install later: git -C ~/.claude/skills/web-image-pipeline pull.