responsive-images — Claude Code skill: what it does, how to install
Implements performant responsive images with srcset, modern formats like AVIF and WebP, CLS prevention, and LCP prioritization.
MIT 148 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill responsive-images -a claude-codeWhat responsive-images does
This skill guides coding agents in setting up responsive images across web pages. It defines concrete rules for srcset, sizes, loading attributes, and <picture> chains ordering AVIF, WebP, and JPEG fallbacks. The patterns cut image payloads by 50-70% and optimize Core Web Vitals.
The reference details width sets for common layouts: full-width hero sections (800w, 1200w, 1600w, 2400w), main content columns, 3-column cards, and sidebar thumbnails. For hero assets driving LCP, it enforces loading="eager" combined with fetchpriority="high", deferring below-the-fold assets with lazy loading.
Inline SVG icons, CSS background patterns, and canvas-rendered graphics are explicitly marked as outside the scope of these rules.
What it helps with
- Prevent layout shifts (CLS) by enforcing explicit width and height dimensions
- Serve modern AVIF and WebP variants using the picture element fallback chain
- Prioritize hero image loading to improve Largest Contentful Paint (LCP)
- Calculate correct srcset widths and sizes queries for responsive layouts
Example prompts for the agent
- Convert the product gallery images to picture elements with AVIF and WebP fallbacks
- Audit the landing page HTML for missing image dimensions and improper loading strategies
- Generate responsive srcset and sizes rules for a 3-column card grid
How to install responsive-images
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill responsive-images -a claude-code2Manually: put the files in place
~/.claude/skills/responsive-images/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/responsive-images/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill responsive-images -a codex2Manually: put the files in place
.agents/skills/responsive-images/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill responsive-images -a cursor2Manually: put the files in place
.cursor/skills/responsive-images/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/responsive-images2Manually: put the files in place
.github/skills/responsive-images/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill responsive-images -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/responsive-imagesManually: put the files in place
.devin/skills/responsive-images/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill responsive-images -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about responsive-images
How to install responsive-images in Claude Code?
Run npx skills add oakoss/agent-skills --skill responsive-images -a claude-code. The file will be placed in ~/.claude/skills/responsive-images/SKILL.md.
What does responsive-images do?
It gives coding agents standard patterns for markup sizing, WebP and AVIF modern formats, art direction, and loading strategies.
When should this skill not be applied?
It should not be applied to inline SVG icons, CSS background patterns, or canvas-rendered graphics.
Source text
SKILL.md · MIT
--- name: responsive-images description: | Implement performant responsive images with srcset, sizes, lazy loading, and modern formats (WebP, AVIF). Covers aspect-ratio for CLS prevention, picture element for art direction, and fetchpriority for LCP optimization. Use when adding images to pages, optimizing Core Web Vitals, preventing layout shift, implementing art direction, or converting to modern formats. license: MIT metadata: author: oakoss version: '1.0' user-invocable: false --- # Responsive Images ## Overview Responsive images serve the right image size and format based on viewport, device pixel ratio, and browser capabilities. Proper implementation prevents layout shift (CLS), optimizes Largest Contentful Paint (LCP), and reduces bandwidth by 50-70% with modern formats. **When to use:** Any page with images, especially content images, hero images, product photos, and gallery layouts. **When NOT to use:** Inline SVG icons, CSS background patterns, or canvas-rendered graphics. ## Quick Reference | Pattern | Approach | Key Points | | ----------------- | --------------------------------------------- | -------------------------------------------------- | | Responsive sizing | `srcset` with width descriptors (w) + `sizes` | Browser selects optimal image for viewport and DPR | | Modern formats | `<picture>` with AVIF, WebP, JPEG sources | AVIF saves 70%, WebP saves 50% vs JPEG | | Art direction | `<picture>` with `media` queries | Different crops per viewport | | LCP hero image | `loading="eager"` + `fetchpriority="high"` | Prioritize download for Core Web Vitals | | Below-fold images | `loading="lazy"` | Defer until near viewport | | Prevent CLS | `width` + `height` attributes | Browser reserves space before load | | Fixed containers | `object-fit: cover` or `contain` | Maintain aspect ratio in constrained space | | Format fallback | AVIF, WebP, JPEG source order | Best compression first, universal fallback last | ## Recommended Image Sizes | Use Case | Widths to Generate | Sizes Attribute | | ------------------ | ------------------------- | --------------------------------- | | Full-width hero | 800w, 1200w, 1600w, 2400w | `100vw` | | Content width | 400w, 800w, 1200w | `(max-width: 768px) 100vw, 800px` | | Grid cards (3-col) | 300w, 600w, 900w | `(max-width: 768px) 100vw, 33vw` | | Sidebar thumbnail | 150w, 300w | `150px` | ## Loading Strategy | Image Position | loading | fetchpriority | Why | | -------------------- | ------- | ------------- | --------------------------------- | | Hero/LCP | `eager` | `high` | Optimize LCP, prioritize download | | Above fold (not LCP) | `eager` | omit | Load normally | | Below fold | `lazy` | omit | Defer until near viewport | | Off-screen carousel | `lazy` | omit | Defer until interaction | ## Format Comparison | Format | Quality | File Size | Browser Support | Use Case | | ------ | --------- | --------- | --------------- | -------------------------------- | | JPEG | Good | Medium | 100% | Photos, complex images | | PNG | Lossless | Large | 100% | Logos, transparency | | WebP | Excellent | Small | 96%+ | Modern browsers, photos | | AVIF | Excellent | Smallest | 93%+ | Newest format, fallback required | ## Common Mistakes | Mistake | Correct Pattern | | ------------------------------------------------------------ | --------------------------------------------------------------------- | | Omitting width and height attributes on img elements | Always include `width` and `height` to prevent CLS layout shift | | Lazy loading the LCP hero image | Use `loading="eager"` and `fetchpriority="high"` for LCP images | | Using density descriptors (1x, 2x) for variable-width images | Use width descriptors (400w, 800w) with a `sizes` attribute | | Missing alt text on content images | Provide descriptive alt text; use `alt=""` only for decorative images | | Serving only JPEG without modern format fallbacks | Use `<picture>` with AVIF and WebP sources falling back to JPEG | ## Delegation - **Audit a page for responsive image issues and CLS problems**: Use `Explore` agent to scan HTML for missing attributes, incorrect loading strategies, and format gaps - **Convert all images on a page to use picture element with modern formats**: Use `Task` agent to rewrite img tags with AVIF/WebP/JPEG fallback chain - **Plan an image optimization pipeline for a multi-page site**: Use `Plan` agent to design srcset breakpoints, format conversion workflow, and CDN integration ## References - [srcset, sizes, and width descriptor patterns](references/srcset-sizes.md) - [Picture element and art direction](references/picture-element.md) - [Modern image formats: WebP, AVIF, and conversion tools](references/modern-formats.md) - [Lazy loading, fetchpriority, and LCP optimization](references/lazy-loading.md) - [Aspect ratio, object-fit, and CLS prevention](references/aspect-ratio.md)
© oakoss · MIT · oakoss/agent-skills