# Image Optimization Pipeline Config

> Use when authoring or reviewing the build-time image pipeline config — defining responsive srcset breakpoints, picking output formats (AVIF / WebP / JPEG fallback), tuning compression quality per format, and ensuring the pipeline never produces a lossy artifact for source PNGs with transparency. Activate this skill whenever the task touches `lib/images/pipeline.config.ts`, `scripts/build-images.ts`, or any code path that resizes or recompresses content images. Do NOT use for runtime image rendering choices (use a frontend skill) or for chasing a specific build failure (use debugging).

- Skill: `jacob-balslev/image-optimization-pipeline-config` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jacob-balslev/image-optimization-pipeline-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jacob-balslev/image-optimization-pipeline-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: jacob-balslev (https://skillmd.com/u/jacob-balslev)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jacob-balslev/image-optimization-pipeline-config

---


# Image Optimization Pipeline Config

## Concept of the skill

**What it is:** The build-time contract for turning source images into responsive, compressed, format-specific outputs.
**Mental model:** The pipeline is a deterministic compiler stage: source image plus config produces a known set of artifacts.
**Why it exists:** Image quality, file size, and fallback support have to be reviewed before they become user-visible performance or fidelity regressions.
**What it is NOT:** It is not runtime `<picture>` markup, layout design, or incident debugging after a build fails.
**Adjacent concepts:** Responsive breakpoints, format negotiation, compression quality, transparency preservation.
**One-line analogy:** It is the recipe card the image build step follows for every asset.
**Common misconception:** Smaller output is always better; preserving transparency, fallback coverage, and layout fit are part of correctness.

## Coverage

- The format-negotiation table — which output formats the pipeline produces (AVIF + WebP + JPEG fallback is the canonical shape) and the priority order browsers should request
- Srcset breakpoints — the widths the pipeline emits per image role (hero, content, thumbnail) and how those align with the site's CSS layout breakpoints
- Per-format compression quality — JPEG at 80, WebP at 75, AVIF at 65 is a defensible default; anything more aggressive needs visual A/B verification
- Transparency preservation — the pipeline must detect alpha channels in source PNGs and disable lossy formats (or fall back to lossless WebP / AVIF) for those specific images
- Idempotency — the pipeline must not reprocess already-optimized outputs on every build (cache invalidation by source-file hash, not timestamp)
- Source-format coverage — what the pipeline accepts as input (PNG, JPEG, WebP source) and what it explicitly rejects (HEIC, RAW, video formats)

## Philosophy of the skill

A build-time image pipeline is a config-defined contract between the source-of-truth images in `content/` and the bandwidth-optimized variants the browser receives. Bugs here are silent: a misconfigured srcset doesn't crash the build, it just sends a 4MB hero image to a phone. The discipline is to encode every choice — breakpoints, formats, quality, transparency rules — explicitly in the config, with a comment naming the constraint that drove each choice. Pipeline behavior should be derivable from the config without reading the build script.

## Key Files

| File | Purpose |
|---|---|
| `lib/images/pipeline.config.ts` | The canonical config: breakpoints, formats, quality settings, source-format allowlist |
| `scripts/build-images.ts` | The build entrypoint that reads the config and walks `content/` — should be a thin runner with no embedded policy |
| `lib/images/format-negotiation.ts` | The runtime helper that maps a request's `Accept:` header to the right pre-built variant |

## Verification

Before merging any change to the pipeline config:

- [ ] Every output format has an explicit quality setting; no relying on library defaults
- [ ] Srcset breakpoints match (or are a documented superset of) the site's CSS layout breakpoints
- [ ] PNG sources with an alpha channel route to lossless or alpha-preserving lossy formats (WebP-lossless, AVIF) — never to JPEG
- [ ] The pipeline skips already-optimized outputs by source-hash comparison; running the build twice in a row is a no-op on the second run
- [ ] An end-to-end test under `__tests__/images/` exercises a fixture image of each accepted format and asserts the expected variant set is produced
- [ ] The format-negotiation helper has a fallback path for clients that send no `Accept:` header (or one that lists no supported format)

## Do NOT Use When

| Use instead | When |
|---|---|
| (a frontend image-rendering skill) | The task is choosing the right `<picture>` / `<img srcset=...>` markup at the component level |
| `debugging` | A specific image is failing to optimize and you need to reproduce from build logs |
| `documentation` | The task is writing a contributor doc explaining how the pipeline works |
| `refactor` | The task is restructuring the pipeline code without changing the config contract |