@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/gemini-cli/perf-query-optimization/SKILL.md

@@ -0,0 +1,203 @@
+# Query Optimization
+
+> Master database query optimization — EXPLAIN and EXPLAIN ANALYZE for query plan analysis, identifying sequential scans and inefficient joins, rewriting queries for index utilization, understanding the query optimizer's cost model, and diagnosing slow queries in PostgreSQL and MySQL.
+
+## When to Use
+
+- API endpoints have high p95 latency traced to database queries
+- EXPLAIN shows sequential scans on large tables instead of index scans
+- A query worked fine on small data but degrades at production scale
+- Dashboard or reporting queries take seconds instead of milliseconds
+- Database CPU is consistently high due to expensive query plans
+- ORM-generated queries are inefficient and need raw SQL alternatives
+- JOIN operations produce unexpected performance characteristics
+- A query uses a subquery where a JOIN or CTE would be faster
+- EXPLAIN output shows high row estimates versus actual rows (cardinality misestimation)
+- pg_stat_statements or slow query log highlights specific problematic queries
+
+## Instructions
+
+1. **Run EXPLAIN ANALYZE to see the actual execution plan.** EXPLAIN shows the planner's estimate; EXPLAIN ANALYZE executes the query and shows real timings:
+
+   ```sql
+   -- PostgreSQL: full execution analysis
+   EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+   SELECT o.id, o.total, u.name
+   FROM orders o
+   JOIN users u ON u.id = o.user_id
+   WHERE o.created_at > '2024-01-01'
+     AND o.status = 'completed'
+   ORDER BY o.created_at DESC
+   LIMIT 50;
+
+   -- MySQL: execution analysis
+   EXPLAIN ANALYZE
+   SELECT o.id, o.total, u.name
+   FROM orders o
+   JOIN users u ON u.id = o.user_id
+   WHERE o.created_at > '2024-01-01'
+     AND o.status = 'completed'
+   ORDER BY o.created_at DESC
+   LIMIT 50;
+   ```
+
+2. **Read the execution plan bottom-up.** Identify the most expensive operations:
+
+   ```
+   EXPLAIN ANALYZE output (PostgreSQL):
+
+   Limit  (cost=1234.56..1234.70 rows=50 actual time=2.1..2.2 rows=50)
+     -> Sort  (cost=1234.56..1267.89 rows=13333 actual time=2.1..2.1 rows=50)
+           Sort Key: o.created_at DESC
+           Sort Method: top-N heapsort  Memory: 32kB
+           -> Hash Join  (cost=45.00..987.65 rows=13333 actual time=0.5..1.8 rows=13333)
+                 Hash Cond: (o.user_id = u.id)
+                 -> Seq Scan on orders o  (cost=0.00..876.00 rows=13333 actual time=0.1..1.2 rows=13333)
+                       Filter: (created_at > '2024-01-01' AND status = 'completed')
+                       Rows Removed by Filter: 86667
+                 -> Hash  (cost=30.00..30.00 rows=1000 actual time=0.3..0.3 rows=1000)
+                       -> Seq Scan on users u  (cost=0.00..30.00 rows=1000 actual time=0.0..0.2 rows=1000)
+
+   -- Problem: Seq Scan on orders filtering 86,667 rows to get 13,333.
+   -- Solution: CREATE INDEX idx_orders_status_created ON orders(status, created_at DESC);
+   ```
+
+3. **Identify and fix sequential scans.** A sequential scan reads every row in the table. On large tables this is the primary performance problem:
+
+   ```sql
+   -- Bad: sequential scan on 1M row table
+   SELECT * FROM events WHERE user_id = 12345 AND type = 'purchase';
+   -- Seq Scan on events, Filter: user_id = 12345 AND type = 'purchase'
+   -- Rows Removed by Filter: 999,990
+
+   -- Fix: add a composite index matching the query
+   CREATE INDEX idx_events_user_type ON events(user_id, type);
+   -- Now: Index Scan using idx_events_user_type on events
+   -- Rows: 10  (only reads matching rows)
+   ```
+
+4. **Optimize JOINs for the query planner.** The order and type of join impacts performance:
+
+   ```sql
+   -- Inefficient: subquery forces materialization
+   SELECT * FROM orders
+   WHERE user_id IN (
+     SELECT id FROM users WHERE country = 'US'
+   );
+
+   -- Better: JOIN lets the planner choose the optimal strategy
+   SELECT o.* FROM orders o
+   JOIN users u ON u.id = o.user_id
+   WHERE u.country = 'US';
+
+   -- Best when you need existence check only: EXISTS
+   SELECT * FROM orders o
+   WHERE EXISTS (
+     SELECT 1 FROM users u
+     WHERE u.id = o.user_id AND u.country = 'US'
+   );
+   ```
+
+5. **Use CTEs wisely.** In PostgreSQL 12+, CTEs are inlined by default (optimizable). Use `MATERIALIZED` only when you explicitly want to prevent optimization:
+
+   ```sql
+   -- PostgreSQL 12+: CTE is inlined, planner can optimize
+   WITH recent_orders AS (
+     SELECT * FROM orders WHERE created_at > now() - interval '7 days'
+   )
+   SELECT * FROM recent_orders WHERE status = 'pending';
+
+   -- Force materialization when the CTE is referenced multiple times
+   -- or when you want to force a specific execution boundary:
+   WITH recent AS MATERIALIZED (
+     SELECT * FROM orders WHERE created_at > now() - interval '7 days'
+   )
+   SELECT * FROM recent r1
+   JOIN recent r2 ON r1.user_id = r2.user_id;
+   ```
+
+6. **Paginate efficiently with keyset pagination.** OFFSET-based pagination degrades linearly with page number:
+
+   ```sql
+   -- Bad: OFFSET scans and discards rows (page 1000 reads 50,000 rows)
+   SELECT * FROM products ORDER BY created_at DESC LIMIT 50 OFFSET 49950;
+
+   -- Good: keyset pagination (constant time regardless of page)
+   SELECT * FROM products
+   WHERE created_at < '2024-03-15T10:30:00Z'
+   ORDER BY created_at DESC
+   LIMIT 50;
+   -- Requires an index on created_at and passing the last seen value
+   ```
+
+7. **Monitor query performance in production.** Use built-in tooling to find slow queries:
+
+   ```sql
+   -- PostgreSQL: enable pg_stat_statements
+   CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+   -- Find top 10 slowest queries by total time
+   SELECT
+     round(total_exec_time::numeric, 2) AS total_ms,
+     calls,
+     round(mean_exec_time::numeric, 2) AS mean_ms,
+     round((100 * total_exec_time / sum(total_exec_time) OVER ())::numeric, 2) AS pct,
+     query
+   FROM pg_stat_statements
+   ORDER BY total_exec_time DESC
+   LIMIT 10;
+   ```
+
+## Details
+
+### Understanding Cost Numbers
+
+PostgreSQL's cost numbers are in arbitrary units relative to `seq_page_cost` (default 1.0). A cost of 1000 means roughly 1000 sequential page reads worth of work. The two cost numbers (e.g., `cost=0.42..1234.56`) represent startup cost (before first row) and total cost (all rows). Index scans have higher startup cost but lower total cost on selective queries. The planner chooses the plan with the lowest total cost (or lowest startup cost when LIMIT is present).
+
+### Cardinality Estimation
+
+The optimizer estimates how many rows each operation will produce (cardinality). When estimates are wrong (e.g., estimated 100 rows, actual 100,000), the planner chooses a suboptimal strategy. Common causes: stale statistics (`ANALYZE` not run), correlated columns (planner assumes independence), non-uniform distribution, or values outside the histogram range. Run `ANALYZE tablename` to update statistics after bulk data changes.
+
+### Worked Example: Stripe Payment Queries
+
+Stripe processes billions of payment records. Their query optimization strategy uses composite indexes that match their most common query patterns: `(merchant_id, created_at DESC)` for merchant dashboards, `(status, created_at)` for operations monitoring. They use keyset pagination exclusively (no OFFSET) and pre-compute aggregations for dashboard summaries rather than running real-time GROUP BY queries on the payments table. Result: merchant dashboard queries complete in <10ms at p99 regardless of merchant size.
+
+### Worked Example: Figma File Versioning
+
+Figma's file versioning system queries a table with billions of rows (file versions across all users). Their initial query for "show version history of file X" used a sequential scan filtered by file_id. Adding a composite index `(file_id, created_at DESC)` reduced the query from 2 seconds to 3ms. For their "recently modified files across team" query, they added a partial index `CREATE INDEX ON files(team_id, modified_at DESC) WHERE deleted_at IS NULL` that is 60% smaller than a full index because it excludes soft-deleted files.
+
+### Anti-Patterns
+
+**SELECTing columns you do not need.** `SELECT *` reads all columns from disk, even when you need only 2-3. This increases I/O and prevents covering index scans. Always select only the columns needed.
+
+**Using DISTINCT to mask duplicate JOIN results.** If a JOIN produces duplicates, adding DISTINCT is a symptom fix. The root cause is usually a missing GROUP BY, an incorrect JOIN condition, or a missing WHERE clause. DISTINCT sorts or hashes the entire result set.
+
+**Ignoring EXPLAIN ANALYZE warnings.** When actual rows are 100x the estimate, the optimizer chose a suboptimal plan. Run `ANALYZE` on the affected tables and consider creating statistics objects for correlated columns.
+
+**Not parameterizing queries.** Hard-coded values in queries (`WHERE id = 12345`) bypass the prepared statement cache, forcing the planner to re-plan on every execution. Use parameterized queries (`WHERE id = $1`) for plan caching.
+
+## Source
+
+- PostgreSQL: EXPLAIN — https://www.postgresql.org/docs/current/using-explain.html
+- PostgreSQL: pg_stat_statements — https://www.postgresql.org/docs/current/pgstatstatements.html
+- Use The Index, Luke — https://use-the-index-luke.com/
+- MySQL: EXPLAIN Output — https://dev.mysql.com/doc/refman/8.0/en/explain-output.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Critical queries have been profiled with EXPLAIN ANALYZE.
+- No sequential scans exist on large tables for frequently-executed queries.
+- Composite indexes match the most common query patterns.
+- Pagination uses keyset (cursor) strategy instead of OFFSET.
+- pg_stat_statements or equivalent is enabled for ongoing query monitoring.

package/dist/agents/skills/gemini-cli/perf-query-optimization/skill.yaml

@@ -0,0 +1,39 @@
+name: perf-query-optimization
+version: '1.0.0'
+description: Query optimization — EXPLAIN analysis, query plans, index usage, optimizer hints, and slow query diagnosis
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-n-plus-one
+  - perf-index-strategies
+  - perf-connection-pooling
+  - prisma-performance-patterns
+  - drizzle-performance-patterns
+stack_signals: []
+keywords:
+  - query optimization
+  - EXPLAIN
+  - query plan
+  - slow query
+  - sequential scan
+  - index scan
+  - query cost
+  - optimizer
+  - execution plan
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-resource-hints/SKILL.md

@@ -0,0 +1,167 @@
+# Resource Hints
+
+> Use preload, prefetch, preconnect, dns-prefetch, modulepreload, fetchpriority, and 103 Early Hints to inform the browser about resources needed soon — eliminating discovery latency and accelerating critical resource delivery.
+
+## When to Use
+
+- LCP is delayed because the browser discovers the hero image or critical font late during HTML parsing
+- Third-party origins (fonts, analytics, CDN) add visible connection establishment delay
+- Navigation to a likely next page is slow and could benefit from prefetching key resources
+- ES module loading creates a waterfall as the browser discovers import dependencies sequentially
+- The browser prioritizes a non-critical resource over a critical one (e.g., fetching below-fold images before hero image)
+- 103 Early Hints is available on your server and you want to send preload hints before the full response
+- A Single Page Application can predict the next route and prefetch its JavaScript chunks
+- Fonts are discovered late (during CSS parsing) and cause FOIT or FOUT
+- WebPageTest shows a "gap" in the waterfall where the browser has idle network capacity
+- You need a systematic approach to resource loading prioritization
+
+## Instructions
+
+1. **Audit resource discovery timing.** Open Chrome DevTools Network panel and look for resources that start loading late despite being needed early. The "Initiator" column shows what triggered each request. Late-discovered resources are candidates for resource hints.
+
+2. **Add preconnect for critical third-party origins.** Preconnect performs DNS + TCP + TLS ahead of time, saving 100-300ms per origin:
+
+   ```html
+   <head>
+     <!-- Preconnect to critical third-party origins -->
+     <link rel="preconnect" href="https://fonts.googleapis.com" />
+     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+     <link rel="preconnect" href="https://cdn.example.com" />
+
+     <!-- dns-prefetch as fallback for older browsers -->
+     <link rel="dns-prefetch" href="https://fonts.googleapis.com" />
+   </head>
+   ```
+
+   Limit preconnect to 4-6 origins maximum. Each preconnect consumes a socket and CPU for the TLS handshake.
+
+3. **Use preload for late-discovered critical resources.** Preload tells the browser to fetch a resource immediately at high priority, even before it would normally be discovered:
+
+   ```html
+   <head>
+     <!-- Preload LCP hero image (browser would discover it late in body) -->
+     <link
+       rel="preload"
+       href="/images/hero.webp"
+       as="image"
+       type="image/webp"
+       fetchpriority="high"
+     />
+
+     <!-- Preload critical font (browser discovers during CSS parsing) -->
+     <link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin />
+
+     <!-- Preload critical CSS that's loaded dynamically -->
+     <link rel="preload" href="/styles/above-fold.css" as="style" />
+   </head>
+   ```
+
+   **Critical rule:** Always include the `as` attribute. Without it, the browser cannot set the correct priority or content-security-policy check, and may double-fetch the resource.
+
+4. **Use modulepreload for ES module dependency chains.** Standard preload does not parse module dependencies. Modulepreload fetches the module AND its static imports:
+
+   ```html
+   <!-- Preload the module and its dependency tree -->
+   <link rel="modulepreload" href="/js/app.mjs" />
+   <link rel="modulepreload" href="/js/utils.mjs" />
+   ```
+
+5. **Use prefetch for next-navigation resources.** Prefetch downloads resources at low priority for future navigations:
+
+   ```html
+   <!-- Prefetch likely next page's resources -->
+   <link rel="prefetch" href="/dashboard/chunk.js" />
+   <link rel="prefetch" href="/api/user/profile" />
+   ```
+
+6. **Use fetchpriority to override browser heuristics.** When the browser's automatic priority is wrong:
+
+   ```html
+   <!-- Boost LCP image priority -->
+   <img src="/hero.webp" fetchpriority="high" alt="Hero" />
+
+   <!-- Lower priority for below-fold images the browser might prioritize -->
+   <img src="/ad-banner.webp" fetchpriority="low" alt="Ad" />
+
+   <!-- Boost priority for critical async script -->
+   <script src="/critical-widget.js" async fetchpriority="high"></script>
+   ```
+
+7. **Implement 103 Early Hints.** 103 Early Hints allows the server to send preload hints while still processing the request:
+
+   ```
+   HTTP/1.1 103 Early Hints
+   Link: </styles/main.css>; rel=preload; as=style
+   Link: </fonts/inter.woff2>; rel=preload; as=font; crossorigin
+   Link: <https://cdn.example.com>; rel=preconnect
+
+   HTTP/1.1 200 OK
+   Content-Type: text/html
+   ...
+   ```
+
+   This is especially valuable when the server takes 200-500ms to generate the response — the browser starts fetching resources during that wait time.
+
+## Details
+
+### Resource Hint Decision Tree
+
+| Scenario                                         | Hint            | Priority              |
+| ------------------------------------------------ | --------------- | --------------------- |
+| Resource needed on THIS page, discovered late    | `preload`       | High                  |
+| Resource needed on NEXT page (likely navigation) | `prefetch`      | Low (idle)            |
+| Third-party origin needed soon                   | `preconnect`    | N/A (connection only) |
+| Third-party origin might be needed               | `dns-prefetch`  | N/A (DNS only)        |
+| ES module with dependency chain                  | `modulepreload` | High                  |
+| Override browser's resource priority             | `fetchpriority` | Explicit              |
+
+### Preload vs Prefetch
+
+These are frequently confused. Preload is for the current navigation — it tells the browser "you will need this resource NOW, start fetching immediately at high priority." Prefetch is for future navigations — it tells the browser "the user might navigate here next, download this at idle priority if bandwidth allows."
+
+Using prefetch for current-page resources wastes the first visit (resource loads at low priority). Using preload for next-page resources wastes bandwidth on resources that may never be used.
+
+### Worked Example: Shopify LCP Improvement
+
+Shopify improved LCP by 1.3 seconds on their storefront pages by adding two resource hints: (1) `<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">` for the product hero image — previously discovered only when the browser parsed the `<img>` tag in the body, and (2) `<link rel="preconnect" href="https://cdn.shopify.com">` for their CDN origin — previously the connection was established on first resource request. The preload moved image fetch start from 800ms to 200ms (saving 600ms), and preconnect saved 300ms of connection overhead.
+
+### Worked Example: Wikipedia DNS-Prefetch
+
+Wikipedia reduced page load time by 300ms by implementing dns-prefetch for all external origins (Wikimedia Commons, upload.wikimedia.org, meta.wikimedia.org) and preloading critical fonts. Their pages reference 3-4 external origins, and dns-prefetch eliminated the DNS resolution delay (averaging 40-80ms per origin) from the critical path. They also preloaded their custom font (WikiFont, 28KB WOFF2) to prevent FOIT on first visits.
+
+### Anti-Patterns
+
+**Preloading everything.** If more than 3-5 resources are preloaded, they compete for bandwidth and may delay actually critical resources. Preload only resources that are: (1) critical for the current page, (2) discovered late by the browser, and (3) on the critical rendering path.
+
+**Preload without `as` attribute.** Without `as`, the browser cannot determine the resource type, resulting in: (1) wrong fetch priority, (2) potential double-fetch when the resource is actually used, (3) CSP violations. Always specify: `as="image"`, `as="font"`, `as="style"`, `as="script"`, etc.
+
+**Using prefetch for current-page resources.** Prefetch is low priority and may not complete before the resource is needed. If the resource is needed on the current page, use preload instead. Chrome shows a console warning when a preloaded resource is not used within 3 seconds.
+
+**Too many preconnect hints.** Each preconnect opens a socket and performs a TLS handshake. Beyond 6 origins, the connection overhead (memory, CPU) creates diminishing returns and can actually slow down high-priority connections due to socket exhaustion.
+
+## Source
+
+- W3C Resource Hints Specification — https://www.w3.org/TR/resource-hints/
+- W3C Preload Specification — https://www.w3.org/TR/preload/
+- RFC 8297: 103 Early Hints — https://www.rfc-editor.org/rfc/rfc8297
+- Chrome Priority System documentation — https://web.dev/articles/fetch-priority
+- web.dev Preconnect guide — https://web.dev/articles/uses-rel-preconnect
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.
+- Critical resources (LCP image, primary font) are preloaded and start fetching within 200ms of navigation.
+- Third-party origins have appropriate preconnect or dns-prefetch hints (maximum 6 preconnect hints).
+- No unused preloads (Chrome DevTools shows no "preloaded but not used within 3 seconds" warnings).

package/dist/agents/skills/gemini-cli/perf-resource-hints/skill.yaml

@@ -0,0 +1,40 @@
+name: perf-resource-hints
+version: '1.0.0'
+description: Resource hints — preload, prefetch, preconnect, dns-prefetch, modulepreload, and fetchpriority for optimal resource loading
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-connection-costs
+  - perf-critical-rendering-path
+  - perf-largest-contentful-paint
+  - perf-lazy-loading
+  - perf-font-loading
+  - css-performance-patterns
+stack_signals: []
+keywords:
+  - preload
+  - prefetch
+  - preconnect
+  - dns-prefetch
+  - modulepreload
+  - fetchpriority
+  - resource hints
+  - early hints
+  - 103 early hints
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/perf-responsive-images/SKILL.md

@@ -0,0 +1,225 @@
+# Responsive Images
+
+> Master responsive image delivery — srcset for resolution switching, sizes for viewport-aware selection, the picture element for art direction, automated responsive image generation, and strategies to serve the smallest image that looks sharp on every device.
+
+## When to Use
+
+- Desktop-sized images are served to mobile devices, wasting bandwidth
+- Retina displays show blurry images because only 1x variants are served
+- Lighthouse flags "Properly size images" with significant savings potential
+- A 2000px hero image is served to a 375px mobile viewport
+- Images cause layout shift because width and height attributes are missing
+- Art direction is needed (different crops for different viewports)
+- An image CDN is available but srcset is not configured
+- CMS-uploaded images are served at original resolution regardless of display context
+- Page weight on mobile is double or more compared to what is necessary
+- LCP element is an image that could be served in a smaller size
+
+## Instructions
+
+1. **Implement srcset for resolution switching.** Provide multiple image widths and let the browser choose the optimal one:
+
+   ```html
+   <img
+     src="product-800.jpg"
+     srcset="
+       product-400.jpg   400w,
+       product-800.jpg   800w,
+       product-1200.jpg 1200w,
+       product-1600.jpg 1600w
+     "
+     sizes="(max-width: 600px) 100vw,
+            (max-width: 1200px) 50vw,
+            33vw"
+     alt="Product photo"
+     width="800"
+     height="600"
+     loading="lazy"
+   />
+   ```
+
+   The `sizes` attribute tells the browser how wide the image will be displayed at each viewport width. The browser combines this with the device pixel ratio to select the best srcset candidate.
+
+2. **Calculate correct sizes values.** The sizes attribute must reflect actual CSS layout. Incorrect sizes cause the browser to select the wrong image:
+
+   ```
+   Layout                              | sizes value
+   ------------------------------------|----------------------------------
+   Full-width image                    | 100vw
+   Two-column grid, full-width mobile  | (max-width: 768px) 100vw, 50vw
+   Three-column grid with padding      | (max-width: 768px) 100vw,
+                                       |  (max-width: 1200px) calc(50vw - 32px),
+                                       |  calc(33.3vw - 48px)
+   Fixed-width sidebar image           | 300px
+   ```
+
+3. **Use the picture element for art direction.** When different viewports need different image crops (not just resolutions):
+
+   ```html
+   <picture>
+     <!-- Mobile: tight crop, portrait orientation -->
+     <source
+       media="(max-width: 600px)"
+       srcset="hero-mobile-400.avif 400w, hero-mobile-800.avif 800w"
+       sizes="100vw"
+       type="image/avif"
+     />
+     <source
+       media="(max-width: 600px)"
+       srcset="hero-mobile-400.webp 400w, hero-mobile-800.webp 800w"
+       sizes="100vw"
+       type="image/webp"
+     />
+     <!-- Desktop: wide crop, landscape orientation -->
+     <source
+       srcset="hero-desktop-1200.avif 1200w, hero-desktop-1800.avif 1800w"
+       sizes="100vw"
+       type="image/avif"
+     />
+     <source
+       srcset="hero-desktop-1200.webp 1200w, hero-desktop-1800.webp 1800w"
+       sizes="100vw"
+       type="image/webp"
+     />
+     <img
+       src="hero-desktop-1200.jpg"
+       alt="Hero banner"
+       width="1800"
+       height="600"
+       fetchpriority="high"
+     />
+   </picture>
+   ```
+
+4. **Generate responsive variants in the build pipeline.**
+
+   ```javascript
+   const sharp = require('sharp');
+
+   const WIDTHS = [400, 800, 1200, 1600, 2000];
+
+   async function generateResponsive(inputPath) {
+     const base = inputPath.replace(/\.[^.]+$/, '');
+     const image = sharp(inputPath);
+     const metadata = await image.metadata();
+
+     const tasks = WIDTHS.filter((w) => w <= metadata.width) // don't upscale
+       .flatMap((width) => [
+         sharp(inputPath).resize(width).avif({ quality: 50 }).toFile(`${base}-${width}.avif`),
+         sharp(inputPath).resize(width).webp({ quality: 75 }).toFile(`${base}-${width}.webp`),
+         sharp(inputPath)
+           .resize(width)
+           .jpeg({ quality: 80, mozjpeg: true })
+           .toFile(`${base}-${width}.jpg`),
+       ]);
+
+     await Promise.all(tasks);
+   }
+   ```
+
+5. **Always include width and height attributes.** These prevent layout shift by allowing the browser to calculate aspect ratio before the image loads:
+
+   ```html
+   <!-- Browser calculates aspect ratio: 800/600 = 1.333 -->
+   <img src="photo.jpg" width="800" height="600" alt="Photo" />
+
+   <!-- CSS makes it responsive while maintaining aspect ratio -->
+   <style>
+     img {
+       max-width: 100%;
+       height: auto;
+     }
+   </style>
+   ```
+
+6. **Use fetchpriority for LCP images.** The LCP image should be eagerly loaded with high priority:
+
+   ```html
+   <!-- LCP hero image: eager load, high priority, no lazy -->
+   <img
+     src="hero-1200.jpg"
+     srcset="hero-800.jpg 800w, hero-1200.jpg 1200w, hero-1600.jpg 1600w"
+     sizes="100vw"
+     alt="Hero"
+     width="1600"
+     height="900"
+     fetchpriority="high"
+   />
+
+   <!-- Below-fold images: lazy load, default priority -->
+   <img
+     src="gallery-800.jpg"
+     srcset="gallery-400.jpg 400w, gallery-800.jpg 800w"
+     sizes="50vw"
+     alt="Gallery item"
+     width="800"
+     height="600"
+     loading="lazy"
+   />
+   ```
+
+7. **Configure image CDN responsive delivery.** CDNs can generate responsive variants on the fly:
+
+   ```html
+   <!-- Cloudflare Image Resizing with srcset -->
+   <img
+     src="/cdn-cgi/image/width=800,format=auto/images/hero.jpg"
+     srcset="
+       /cdn-cgi/image/width=400,format=auto/images/hero.jpg   400w,
+       /cdn-cgi/image/width=800,format=auto/images/hero.jpg   800w,
+       /cdn-cgi/image/width=1200,format=auto/images/hero.jpg 1200w
+     "
+     sizes="100vw"
+     alt="Hero"
+   />
+   ```
+
+## Details
+
+### How the Browser Selects a srcset Candidate
+
+The browser multiplies the sizes value (CSS pixels the image will occupy) by the device pixel ratio. A 2x retina device displaying an image at 400 CSS pixels needs an 800-pixel-wide image. The browser picks the smallest srcset candidate that meets or exceeds this target. This is why srcset widths should be in roughly 1.5-2x increments: 400, 800, 1200, 1600 covers 1x through 4x devices at common layout sizes.
+
+### Worked Example: The Guardian
+
+The Guardian generates 7 srcset variants for article images (140, 500, 620, 700, 860, 940, 1020 pixels) tailored to their column layout breakpoints. Their sizes attribute precisely matches their CSS grid: `(max-width: 660px) 100vw, (max-width: 980px) 620px, 700px`. Combined with AVIF/WebP via the picture element, this reduced image bytes per article by 62% on mobile compared to serving a single 1020px JPEG. LCP improved by 400ms on median mobile connections.
+
+### Worked Example: Etsy Product Images
+
+Etsy generates responsive variants at upload time and stores them in their image service. Product listing pages use srcset with 5 width descriptors matched to their grid breakpoints. On mobile (1 column), images are 100vw; on tablet (2 columns), images are ~50vw minus gutters; on desktop (4 columns), images are ~25vw minus gutters. Their sizes attribute encodes this precisely, resulting in the browser selecting a 400px image on mobile instead of a 1600px image — saving 85% of image bytes per card.
+
+### Anti-Patterns
+
+**Incorrect sizes attribute.** If sizes says `100vw` but the image is actually displayed at 33% width, the browser selects an image 3x larger than needed. Always measure the actual CSS layout width at each breakpoint and encode it in sizes.
+
+**Too few srcset variants.** Providing only 2 widths (400, 1600) means a 2x device at 500px layout width must download the 1600px image. Provide enough variants (4-6) to cover the range of viewport-width times device-pixel-ratio combinations.
+
+**Upscaling in srcset.** Never include a srcset width larger than the source image. A 1000px source image upscaled to 2000px is larger and blurrier than serving the 1000px original.
+
+**Missing width/height on responsive images.** Without dimensions, the browser cannot reserve space before the image loads, causing Cumulative Layout Shift. Always include width and height even on responsive images (CSS `height: auto` overrides the attribute for display).
+
+## Source
+
+- MDN: Responsive images — https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
+- web.dev: Serve responsive images — https://web.dev/articles/serve-responsive-images
+- Cloudinary: Responsive images guide — https://cloudinary.com/guides/responsive-images
+- RespImageLint — https://ausi.github.io/respimagelint/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- All content images use srcset with at least 4 width descriptors.
+- The sizes attribute accurately reflects CSS layout widths at each breakpoint.
+- No image is served at more than 1.5x its display dimensions on any device.
+- All images include width and height attributes to prevent layout shift.
+- LCP images use fetchpriority="high" and are not lazy loaded.