Agent-Skills.md

Agent Skills: Image Optimization Expert

Expert guidance on image optimization for web performance. Use when working with image formats (WebP, AVIF, JPEG, PNG, GIF, SVG, HEIC, JPEG XL), compression settings, responsive images, lazy loading, CDNs, Core Web Vitals, or any image-related web development task. Covers format selection, quality settings, srcset/sizes, picture element, art direction, fetchpriority, placeholder strategies (LQIP, blur-up, blurhash), container queries, HDR/wide color gamut, AI-powered image tools, edge/serverless processing, and performance optimization.

UncategorizedID: igorvaryvoda/image-optimization-skill/image-optimization

Install this agent skill to your local

pnpm dlx add-skill https://github.com/IgorVaryvoda/image-optimization-skill/tree/HEAD/skills/image-optimization

Skill Files

Browse the full folder contents for image-optimization.

Download Skill

Loading file tree…

skills/image-optimization/SKILL.md

Skill Metadata

Name
image-optimization
Description
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, CDN delivery, Sirv/Cloudinary/imgix/Vercel/Cloudflare image pipelines, format conversion, compression, alt text, product media, Sirv dynamic imaging/API/Media Viewer workflows (galleries, zoom, spins, videos), or image-heavy frontend code. Covers AVIF, WebP, JPEG, PNG, GIF, SVG, HEIC, JPEG XL, HDR/wide gamut, quality settings, placeholders, image audits, and implementation verification.

Image Optimization Expert

Default Workflow

  1. Inspect the real surface before prescribing changes: rendered HTML, framework image components, network waterfall, build output, CDN URLs, and asset inventory.
  2. 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.
  3. Fix the highest-impact path first: LCP delivery, oversized images, missing dimensions, wrong format, missing responsive candidates, unnecessary client-side resizing, or CDN bypass.
  4. Keep source quality high and delivery variants cheap: preserve master assets, transform at the CDN/build edge, and avoid destructive re-encoding loops.
  5. 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 width and height or a stable CSS aspect-ratio.
  • Responsive delivery: Width-based srcset uses realistic layout sizes; 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, Sirv URL usage, and optional HTTP headers/content length.

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. | | CSS background hero | Consider replacing with semantic <img>/picture; if it must remain CSS, use image-set() 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: Sirv, Cloudinary, imgix, CLI/build tools, Sharp/libvips: tools.md

Also load sibling skills when the task crosses into their specialty:

  • ../video-optimization/SKILL.md for hero/background video, GIF-to-video, streaming, and video embeds.
  • ../sirv-dynamic-imaging/SKILL.md for Sirv URL parameters, profiles, crops, overlays, and caching.
  • ../sirv-api/SKILL.md for Sirv auth, file upload/fetch, search, metadata, jobs, usage limits.
  • ../sirv-media-viewer/SKILL.md for 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.md for 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.
  • 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 alt text, filename, CDN metadata, and visible captions as interchangeable.
  • Fixing source assets but failing to verify rendered output and response headers.