image-optimization
Expert guidance on image optimization for web performance. Use when auditing or improving image delivery, Core Web Vitals (LCP/CLS/INP), responsive images (srcset/sizes), lazy loading, preloading, image CDN pipelines (Sirv, Cloudinary, imgix, Vercel, Cloudflare), format choice (AVIF, WebP, JPEG XL, SVG, HDR), compression and quality settings, placeholders, image alt text, or image-heavy frontend code. For Sirv URL parameters, Sirv REST API calls, Sirv Media Viewer galleries, or video, the sibling skills own the details.
How do I install this agent skill?
npx skills add https://github.com/igorvaryvoda/image-optimization-skill --skill image-optimizationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides expert guidance and tooling for image optimization. It includes a Node.js script for auditing HTML files and URLs, along with comprehensive reference documentation for formats and performance. No security issues or malicious patterns were identified.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
2/6 files flagged
What does this agent skill do?
Image Optimization Expert
Default Workflow
- Inspect the real surface before prescribing changes: rendered HTML, framework image components, network waterfall, build output, CDN URLs, and asset inventory.
- Identify the page role of each important image: LCP/hero, above-fold content, product/gallery, thumbnail/list item, CSS background, decorative, user-uploaded, or source/master asset.
- Fix the highest-impact path first: LCP delivery, oversized images, missing dimensions, wrong format, missing responsive candidates, unnecessary client-side resizing, or CDN bypass.
- Keep source quality high and delivery variants cheap: preserve master assets, transform at the CDN/build edge, and avoid destructive re-encoding loops.
- Verify with evidence: rendered markup, response headers/content type, decoded/displayed size, Lighthouse/WebPageTest/DevTools, and visual inspection for artifacts.
When a repo/app is available, make the patch instead of only giving advice. Prefer local framework conventions over generic snippets.
Fast Audit Checklist
- LCP: Hero image is not lazy loaded, has
fetchpriority="high"or framework priority, is preloaded when appropriate, comes from a fast origin/CDN, and is right-sized for the rendered slot. - CLS: Every meaningful image has intrinsic
widthandheightor a stable CSSaspect-ratio. - Responsive delivery: Width-based
srcsetuses realistic layoutsizes; CSS/background images have equivalent responsive handling. - Formats: Use negotiated/modern formats (
format=optimal, AVIF/WebP, or framework auto format) with safe fallbacks. - Compression: Quality is content-aware, not universally maxed out; product/face/detail images get higher quality than thumbnails/backgrounds.
- Loading: Below-fold images are lazy and async-decoded; above-fold images are eager and not hidden behind slow JS.
- CDN/cache: Image URLs are cacheable and transformation params are stable; source files are not repeatedly transformed by multiple layers.
- Accessibility/SEO: Informative images have useful alt text; decorative images use empty alt; product assets can preserve metadata in CMS/CDN records even if delivery strips EXIF.
Use The Audit Script
For HTML files or public URLs, run the bundled no-dependency audit before and after changes. The script lives in this skill's own scripts/ directory — resolve it from the skill's base directory (shown when this skill loads), not the target project:
node <skill-base-dir>/scripts/audit-images.mjs ./dist/index.html
node <skill-base-dir>/scripts/audit-images.mjs --head https://example.com/
node <skill-base-dir>/scripts/audit-images.mjs --json https://example.com/ > image-audit.json
The script checks image markup, srcset/sizes, preload hints, likely LCP mistakes, oversized CDN widths, CSS background images, known image CDNs (Sirv, Cloudinary, imgix, Cloudflare, Next.js, and others), and optional HTTP headers/content length. It reads the server HTML only; images that client-side JS injects do not appear, so compare with DevTools for SPAs.
Decision Matrix
| Situation | Preferred Action |
|---|---|
| Static/project-owned images | Generate responsive variants at build time or move masters to an image CDN. |
| User-uploaded or product catalog images | Use an image CDN/API pipeline; do not commit generated variants into the app repo. |
| Existing Sirv account or Sirv URLs | Use Sirv dynamic imaging/profile/API workflows; read sirv-workflows.md. |
| Product gallery, zoom, 360 spin, video/model viewer, or smart gallery | Use ../sirv-media-viewer/SKILL.md before hand-building gallery behavior. |
| Next.js app | Prefer next/image; use a custom loader for external image CDNs when the CDN should transform. In Next.js 16+, priority is deprecated: use fetchPriority="high" (or preload for exactly one LCP image), and add every quality value to images.qualities. |
| CSS background hero | Consider replacing with semantic <img>/picture; if it must remain CSS, use image-set() with type() and preload carefully. |
| Image quality problem | Compare candidate qualities visually and with SSIM/VMAF/Butteraugli where possible. |
| Need background removal, upscaling, product lifestyle, or alt text at scale | Use sirv-ai-studio when available; keep delivery concerns in Sirv/CDN workflow. |
When To Read References
- Sirv implementation workflows: CDN migration, dynamic URLs, profiles, REST inventory/upload/search, Next.js loader, verification: sirv-workflows.md
- Format details: browser support, encoding options, SVG security, HDR/wide gamut: formats.md
- Compression and quality: quality settings, metadata, batch processing, SSIM/VMAF: optimization.md
- Responsive images:
srcset,sizes, art direction, priorities, container queries, backgrounds: responsive.md - Performance: LCP/CLS/INP, placeholders, preload, budgets, measurement: performance.md
- Tools and services: image CDN URL syntax, Next.js/Astro/Vite/Eleventy integration, encoder flags, Sharp: tools.md
Also load sibling skills when the task crosses into their specialty:
../video-optimization/SKILL.mdfor hero/background video, GIF-to-video, streaming, and video embeds.../sirv-dynamic-imaging/SKILL.mdfor Sirv URL parameters, profiles, crops, overlays, and caching.../sirv-api/SKILL.mdfor Sirv auth, file upload/fetch, search, metadata, jobs, usage limits.../sirv-media-viewer/SKILL.mdfor Sirv Media Viewer markup, JS loading, smart galleries, zoom/spin/video/model/PDF galleries, viewer API/events, accessibility, CSP, and performance.../sirv-ai-studio/SKILL.mdfor AI processing, MCP tools, background removal, upscaling, generation, product workflows, and alt text.
Default Recommendations
| Use Case | Format/Delivery Default |
|---|---|
| Photos and product images | AVIF/WebP via auto negotiation; JPEG fallback when needed. |
| Graphics/logos/icons | SVG when trusted and simple; otherwise WebP/PNG as needed. |
| Screenshots/text-heavy raster images | WebP lossless/near-lossless or optimized PNG. |
| Short animations | Animated WebP or video; avoid large GIFs. |
| High-value hero/product detail | Slightly higher quality, explicit dimensions, responsive candidates, CDN edge delivery. |
| Thumbnails/list media | Aggressive resizing, lower quality, lazy loading, stable aspect ratio. |
Quality starting points:
| Format | Starting Quality |
|---|---|
| JPEG | 75-85, higher for product/detail |
| WebP | 75-85 lossy; lossless for sharp graphics |
| AVIF | 60-75 for most photos |
| PNG | Lossless, then optimize or convert when safe |
Common Mistakes To Catch
- Lazy-loading the LCP image, or hiding it behind JS (
data-srcswaps, client-only rendering). - Missing dimensions/aspect ratio.
- Serving a 2-4K image into a small card or mobile slot.
- Writing
sizes="100vw"for images that render in a 33-50vw grid. - Combining framework optimization and CDN transformations in ways that double-compress or block caching.
- Hard-coding AVIF/WebP without a fallback or content negotiation path.
- Using PNG for photos or JPEG for transparency/sharp text.
- Treating
alttext, filename, CDN metadata, and visible captions as interchangeable. - Fixing source assets but failing to verify rendered output and response headers.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/igorvaryvoda/image-optimization-skill/image-optimization">View image-optimization on skillZs</a>