Image Optimization Stinger
The image-optimization-stinger encodes the complete 2026 image delivery playbook: format selection, responsive delivery, placeholder strategies, framework integration, and tooling. Its primary audience is React/Next.js developers shipping web products where images are a material fraction of page weight and LCP candidates.
The non-negotiables (detailed in guides/00-principles.md):
- AVIF first, WebP fallback: never JPEG as primary for new raster content.
width + height always: missing dimensions cause CLS.- LCP images get
priority (Next.js <16) or preload (Next.js 16+) / fetchpriority="high" (native): never loading="lazy".
sizes must match the CSS layout: the default 100vw is wrong for most components.- Placeholders must be chosen deliberately: LQIP via Sharp is the default; BlurHash/ThumbHash for color-faithful scenarios.
When to use this skill
Trigger on:
- "optimize my images" / "convert to AVIF" / "switch to AVIF"
- "set up srcset and sizes" / "responsive images"
- "add blur placeholders" / "BlurHash" / "LQIP" / "ThumbHash"
- "next/image remote patterns" / "next/image config" / "Image component"
- "my LCP image is slow" / "images causing layout shift" / "CLS from images"
- "AVIF vs WebP" / "which image format should I use"
- "audit our images" / "image optimization report"
- "Squoosh" / "Sharp" / "ImageOptim" (in web context)
Do NOT trigger on:
- SVG icon library selection →
icon-system-worker-bee
- Lighthouse score interpretation / CWV remediation beyond images →
lighthouse-pagespeed-worker-bee
- CDN cache TTL / Cache-Control strategy →
devops-worker-bee
- CI build pipelines beyond per-image squash →
devops-worker-bee
Quick-reference decision table
| Scenario |
Recommendation |
| New raster content (photo, hero, product) |
AVIF primary, WebP fallback, <picture> or next/image |
| Transparency needed |
WebP (or PNG for lossless): AVIF supports alpha but WebP encodes faster |
| Simple logo / diagram |
SVG preferred; PNG fallback if SVG not available |
| LCP image above the fold |
priority (Next.js <16) / preload (Next.js 16+) / fetchpriority="high" (HTML) |
| Image below the fold |
loading="lazy" (HTML) / default lazy in next/image |
| Placeholder: simplest |
LQIP via Sharp (16px WebP + CSS filter: blur) |
| Placeholder: color-faithful no-JS |
BlurHash as CSS gradient via @unpic/placeholder |
| Placeholder: alpha channel support |
ThumbHash |
| Next.js with Vercel hosting |
next/image with formats: ['image/avif', 'image/webp'] in next.config |
| Teams on Cloudflare / Imgix / Fastly CDN |
Enable CDN-level format negotiation: no code changes needed |
Guide map
Read guides in order for a full orientation. Jump directly to the relevant guide for targeted work.
guides/00-principles.md: The five non-negotiables and why they exist. Read first on every invocation.guides/01-format-selection.md: AVIF vs WebP vs JPEG vs PNG vs SVG decision tree; 2026 browser support matrix; CDN-level negotiation.guides/02-srcset-sizes.md: How to calculate srcset variant sets and correct sizes values; the 100vw fallacy; art direction with <picture>.guides/03-placeholders.md: LQIP via Sharp, BlurHash-as-CSS-gradient, ThumbHash, solid-color from dominant palette. Tradeoff matrix.guides/04-next-image.md: next/image API, remote patterns config, priority vs preload (Next.js 16+), custom loaders, fill vs responsive vs fixed.guides/05-tooling.md: Sharp Node API (primary), Squoosh CLI (one-offs), ImageOptim (macOS lossless), and build pipeline integration.
Example map
examples/nextjs-avif-with-lqip.md: Happy path: Next.js <Image> with AVIF/WebP formats, correct sizes, LQIP blur placeholder, and LCP priority.examples/html-picture-srcset-art-direction.md: Edge case: native <picture> + <source> for art-direction responsive images in a non-Next.js context.
Template
templates/image-audit-report.md: The report stub the Bee fills in per audit run. Sections: inventory, format breakdown, srcset/sizes audit, placeholder audit, LCP candidates, remediation checklist.
Research trail
Populated by scripture-historian on 2026-05-20 (normal depth, 6-month window, 32 source files).
research/research-summary.md: executive summary, 5 most influential sources, 5 open questions.research/index.md: full manifest of all 32 source files.research/external/: 32 source notes from official docs, practitioner blogs, GitHub READMEs, and specs.
Key sources: caniuse.com/avif (browser support), Mux blog (LQIP/BlurHash tradeoff), Next.js official docs (next/image API + Next.js 16 changes), web.dev/articles/optimize-lcp (LCP priority framing), krunkit.me (DPR-aware srcset algorithm).
Paired with: ../../agents/image-optimization-worker-bee.md
Command Brief: ai-tools/command-briefs/image-optimization-command-brief.md
1---2name: image-optimization-stinger3description: Image optimization specialist for React/Next.js and HTML contexts: AVIF/WebP format selection (AVIF is the 2026 production default), responsive srcset/sizes calculus, blur placeholders (LQIP via Sharp, BlurHash-as-CSS-gradient, ThumbHash), next/image remote patterns and the Next.js 16 priority→preload shift, and CLI tooling (Sharp Node API, Squoosh CLI for one-offs). Use when the user says \\\"optimize my images\\\", \\\"convert to AVIF\\\", \\\"set up srcset\\\", \\\"add blur placeholders\\\", \\\"next/image remote patterns\\\", \\\"LCP image is slow\\\", \\\"fix layout shift from images\\\", \\\"AVIF vs WebP\\\", or when auditing a codebase for unoptimized image delivery. Do NOT use for SVG icon systems (icon-system-worker-bee), general Lighthouse audits beyond image-specific findings (lighthouse-pagespeed-worker-bee), CDN/caching architecture beyond image Cache-Control (devops-worker-bee), or CSS animation performance (ux-ui-svelte-worker-bee).4license: MIT5---67# Image Optimization Stinger89The `image-optimization-stinger` encodes the complete 2026 image delivery playbook: format selection, responsive delivery, placeholder strategies, framework integration, and tooling. Its primary audience is React/Next.js developers shipping web products where images are a material fraction of page weight and LCP candidates.1011**The non-negotiables (detailed in `guides/00-principles.md`):**121. AVIF first, WebP fallback: never JPEG as primary for new raster content.132. `width` + `height` always: missing dimensions cause CLS.143. LCP images get `priority` (Next.js <16) or `preload` (Next.js 16+) / `fetchpriority="high"` (native): never `loading="lazy"`.154. `sizes` must match the CSS layout: the default `100vw` is wrong for most components.165. Placeholders must be chosen deliberately: LQIP via Sharp is the default; BlurHash/ThumbHash for color-faithful scenarios.1718---1920## When to use this skill2122**Trigger on:**23- "optimize my images" / "convert to AVIF" / "switch to AVIF"24- "set up srcset and sizes" / "responsive images"25- "add blur placeholders" / "BlurHash" / "LQIP" / "ThumbHash"26- "next/image remote patterns" / "next/image config" / "Image component"27- "my LCP image is slow" / "images causing layout shift" / "CLS from images"28- "AVIF vs WebP" / "which image format should I use"29- "audit our images" / "image optimization report"30- "Squoosh" / "Sharp" / "ImageOptim" (in web context)3132**Do NOT trigger on:**33- SVG icon library selection → `icon-system-worker-bee`34- Lighthouse score interpretation / CWV remediation beyond images → `lighthouse-pagespeed-worker-bee`35- CDN cache TTL / Cache-Control strategy → `devops-worker-bee`36- CI build pipelines beyond per-image squash → `devops-worker-bee`3738---3940## Quick-reference decision table4142| Scenario | Recommendation |43|---|---|44| New raster content (photo, hero, product) | AVIF primary, WebP fallback, `<picture>` or `next/image` |45| Transparency needed | WebP (or PNG for lossless): AVIF supports alpha but WebP encodes faster |46| Simple logo / diagram | SVG preferred; PNG fallback if SVG not available |47| LCP image above the fold | `priority` (Next.js <16) / `preload` (Next.js 16+) / `fetchpriority="high"` (HTML) |48| Image below the fold | `loading="lazy"` (HTML) / default lazy in `next/image` |49| Placeholder: simplest | LQIP via Sharp (16px WebP + CSS `filter: blur`) |50| Placeholder: color-faithful no-JS | BlurHash as CSS gradient via `@unpic/placeholder` |51| Placeholder: alpha channel support | ThumbHash |52| Next.js with Vercel hosting | `next/image` with `formats: ['image/avif', 'image/webp']` in `next.config` |53| Teams on Cloudflare / Imgix / Fastly CDN | Enable CDN-level format negotiation: no code changes needed |5455---5657## Guide map5859Read guides in order for a full orientation. Jump directly to the relevant guide for targeted work.6061- `guides/00-principles.md`: The five non-negotiables and why they exist. Read first on every invocation.62- `guides/01-format-selection.md`: AVIF vs WebP vs JPEG vs PNG vs SVG decision tree; 2026 browser support matrix; CDN-level negotiation.63- `guides/02-srcset-sizes.md`: How to calculate `srcset` variant sets and correct `sizes` values; the 100vw fallacy; art direction with `<picture>`.64- `guides/03-placeholders.md`: LQIP via Sharp, BlurHash-as-CSS-gradient, ThumbHash, solid-color from dominant palette. Tradeoff matrix.65- `guides/04-next-image.md`: `next/image` API, remote patterns config, `priority` vs `preload` (Next.js 16+), custom loaders, `fill` vs responsive vs fixed.66- `guides/05-tooling.md`: Sharp Node API (primary), Squoosh CLI (one-offs), ImageOptim (macOS lossless), and build pipeline integration.6768---6970## Example map7172- `examples/nextjs-avif-with-lqip.md`: Happy path: Next.js `<Image>` with AVIF/WebP formats, correct `sizes`, LQIP blur placeholder, and LCP priority.73- `examples/html-picture-srcset-art-direction.md`: Edge case: native `<picture>` + `<source>` for art-direction responsive images in a non-Next.js context.7475---7677## Template7879- `templates/image-audit-report.md`: The report stub the Bee fills in per audit run. Sections: inventory, format breakdown, srcset/sizes audit, placeholder audit, LCP candidates, remediation checklist.8081---8283## Research trail8485Populated by `scripture-historian` on 2026-05-20 (normal depth, 6-month window, 32 source files).8687- `research/research-summary.md`: executive summary, 5 most influential sources, 5 open questions.88- `research/index.md`: full manifest of all 32 source files.89- `research/external/`: 32 source notes from official docs, practitioner blogs, GitHub READMEs, and specs.9091Key sources: caniuse.com/avif (browser support), Mux blog (LQIP/BlurHash tradeoff), Next.js official docs (next/image API + Next.js 16 changes), web.dev/articles/optimize-lcp (LCP priority framing), krunkit.me (DPR-aware srcset algorithm).9293---9495*Paired with: [`../../agents/image-optimization-worker-bee.md`](../../agents/image-optimization-worker-bee.md)*96*Command Brief: [`ai-tools/command-briefs/image-optimization-command-brief.md`](../../command-briefs/image-optimization-command-brief.md)*
legioncodeinc