image-optimization-pipeline-config

schema_version	4
name	image-optimization-pipeline-config
description	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).
version	0.1.0
type	capability
category	content
domain	content/build/images
scope	codebase
owner	markdown-static-site-maintainer
freshness	2026-05-06
drift_check	{"last_verified":"2026-05-06"}
eval_artifacts	none
eval_state	unverified
routing_eval	absent
stability	experimental
license	MIT
compatibility	{"runtimes":["node"],"node":">=20","notes":"sharp ^0.33 or equivalent; output formats AVIF / WebP / JPEG."}
allowed-tools	Read Grep Bash
keywords	["image optimization","image pipeline","srcset breakpoints","responsive images","AVIF WebP fallback","sharp config","PNG transparency","compression quality","image build pipeline","format negotiation","image resize"]
triggers	["image-optimization-pipeline-config"]
paths	["lib/images/pipeline.config.ts","scripts/build-images.ts","lib/images/format-negotiation.ts","!**/*.test.ts"]
examples	["configure srcset breakpoints for hero images and thumbnails differently","review the image pipeline — does it preserve transparency on PNG sources?","add AVIF output to the pipeline alongside WebP and JPEG","tune JPEG quality without breaking the AVIF pass"]
anti_examples	["pick the right <picture> element markup at runtime","the build is OOM-killed on the 10MB hero image","rewrite the pipeline in a different image library"]
relations	{"boundary":[{"skill":"documentation","reason":"documentation writes prose about the image pipeline; this skill enforces the config contract in code"},{"skill":"debugging","reason":"debugging chases a specific build-time pipeline failure; this skill is the authoring/review primitive applied before failure"},{"skill":"refactor","reason":"refactor changes pipeline code shape; this skill enforces a specific config contract that must survive any refactor"}],"verify_with":["testing-strategy"]}
grounding	{"domain_object":"Build-time image pipeline configuration — the resize/compress/format-negotiation rules that turn source images in `content/` into the responsive variants under `public/images/`","grounding_mode":"repo_specific","truth_sources":["lib/images/pipeline.config.ts","scripts/build-images.ts","lib/images/format-negotiation.ts"],"failure_modes":["lossy_compression_on_png_with_transparency","missing_avif_fallback_for_unsupported_clients","srcset_breakpoints_dont_match_layout_breakpoints","quality_setting_too_aggressive_visible_artifacts","pipeline_doesnt_skip_already_optimized_outputs"],"evidence_priority":"repo_code_first"}
portability	{"readiness":"scripted","targets":["skill-md"]}
workspace_tags	["content","static-site","build-pipeline"]
lifecycle	{"stale_after_days":90,"review_cadence":"quarterly"}

Image Optimization Pipeline Config

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

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