Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill responsive-images -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/responsive-images/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/responsive-images/

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

Similar skills

All skills for Frontend and UI →

From the same set106

The whole set →
api-testing api-testing is a Claude Code skill for writing REST API integration tests and checking endpoint responses. It activates for HTTP mocking, response validation, and API error tests. CX Codex +1 149installs github-actions Create and configure GitHub Actions workflows, from event triggers and build matrices to caching and authentication. Useful for automating tests, releases, and deployments. CX Codex +1 149installs git-workflow git-workflow guides AI coding agents through trunk-based development, conventional commits, reusable GitHub Actions workflows, and Git history repair. CX Codex +1 149installs ux-designer ux-designer is a Claude Code skill that guides AI agents from information architecture to developer handoff, with usability and accessibility checks. CX Codex +1 148installs tanstack-virtual Teaches the agent to virtualize long lists, grids and tables with TanStack Virtual, so only visible rows stay in the DOM. CX Codex +1 148installs de-slopify The de-slopify skill for Claude Code flags stock phrases, excess em dashes, and AI traces in comments while editing LLM-touched text and code. CX Codex +1 146installs docker Skill for building Docker images, configuring Compose stacks, and preparing containers for production. CX Codex +1 145installs chrome-devtools chrome-devtools is a Claude Code skill that controls a real Chrome session through an extension or DevTools MCP to fill forms, inspect pages, and debug web apps. It works with an existing browser session. CX Codex +1 145installs

Project sponsors

Companies that keep this analytics open