Skip to content

jacob-balslev/skill-graph / examples/projects/markdown-static-site/skills/image-optimization-pipeline-config

image-optimization-pipeline-config

Verified

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).

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

FilePurpose
lib/images/pipeline.config.tsThe canonical config: breakpoints, formats, quality settings, source-format allowlist
scripts/build-images.tsThe build entrypoint that reads the config and walks content/ — should be a thin runner with no embedded policy
lib/images/format-negotiation.tsThe 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 insteadWhen
(a frontend image-rendering skill)The task is choosing the right <picture> / <img srcset=...> markup at the component level
debuggingA specific image is failing to optimize and you need to reproduce from build logs
documentationThe task is writing a contributor doc explaining how the pipeline works
refactorThe task is restructuring the pipeline code without changing the config contract
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall