@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/claude-code/perf-heap-profiling/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-heap-profiling
+version: '1.0.0'
+description: Heap profiling — Chrome DevTools heap snapshots, allocation tracking, retained vs shallow size
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-memory-leaks
+  - perf-garbage-collection
+  - perf-profiling-methodology
+  - node-performance-profiling
+stack_signals: []
+keywords:
+  - heap snapshot
+  - allocation tracking
+  - retained size
+  - shallow size
+  - dominator tree
+  - retaining path
+  - Chrome DevTools
+  - memory profiling
+  - heapdump
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-http2-multiplexing/SKILL.md

@@ -0,0 +1,163 @@
+# HTTP/2 Stream Multiplexing
+
+> Master HTTP/2's binary framing layer, stream multiplexing over a single TCP connection, stream priorities, HPACK header compression, server push mechanics, and head-of-line blocking mitigation to eliminate redundant connections and accelerate page delivery.
+
+## When to Use
+
+- A page opens 6+ TCP connections per origin and you need to reduce connection overhead
+- Network waterfall shows sequential resource loading despite parallel availability
+- Lighthouse flags "Reduce server response times (TTFB)" related to connection establishment
+- You are evaluating whether to domain-shard assets or consolidate to fewer origins
+- Server push is being considered for critical CSS or JS delivery
+- You need to prioritize resource delivery order (critical CSS before analytics scripts)
+- HTTP/1.1 head-of-line blocking is measurably delaying page loads
+- A migration from HTTP/1.1 to HTTP/2 is planned and you need to understand behavioral differences
+- You need to decide between bundling all resources into single files vs fine-grained splitting
+- Connection coalescing behavior needs to be understood for multi-domain TLS certificate configurations
+
+## Instructions
+
+1. **Verify HTTP/2 support.** Check the server and CDN configuration. In Chrome DevTools Network panel, the "Protocol" column shows `h2` for HTTP/2. In curl: `curl -I --http2 https://example.com` — look for `HTTP/2 200`. Confirm the TLS certificate covers all relevant domains for connection coalescing.
+
+2. **Understand the binary framing layer.** HTTP/2 replaces HTTP/1.1 text-based protocol with a binary framing layer. Every HTTP message is broken into frames (HEADERS, DATA, PRIORITY, RST_STREAM, SETTINGS, PUSH_PROMISE, PING, GOAWAY, WINDOW_UPDATE, CONTINUATION). Frames are assigned to numbered streams, and multiple streams are multiplexed over a single TCP connection.
+
+   ```
+   HTTP/2 Connection (single TCP socket)
+   +--------------------------------------------------+
+   | Stream 1: GET /index.html     [HEADERS] [DATA]   |
+   | Stream 3: GET /style.css      [HEADERS] [DATA]   |
+   | Stream 5: GET /app.js         [HEADERS] [DATA]   |
+   | Stream 7: GET /hero.webp      [HEADERS] [DATA]   |
+   +--------------------------------------------------+
+   Frames from all streams interleave on the same connection.
+   ```
+
+3. **Configure stream priorities.** HTTP/2 allows clients to assign priority weight (1-256) and dependency relationships between streams. Browsers set priorities automatically: CSS and fonts get higher priority than images. Override with the `fetchpriority` attribute when the browser's heuristics are wrong.
+
+   ```html
+   <!-- Boost priority for LCP hero image -->
+   <img src="/hero.webp" fetchpriority="high" alt="Hero" />
+
+   <!-- Lower priority for below-the-fold images -->
+   <img src="/gallery-1.webp" fetchpriority="low" alt="Gallery" loading="lazy" />
+   ```
+
+4. **Leverage HPACK header compression.** HTTP/2 uses HPACK to compress headers. The first request sends full headers; subsequent requests on the same connection reference a shared dynamic table, sending only differences. Typical savings: 85-95% reduction in header bytes after the first request. Headers that repeat across requests (cookies, user-agent, accept) benefit most.
+
+5. **Evaluate server push carefully.** Server push allows the server to send resources before the client requests them. The server sends a PUSH_PROMISE frame, then the DATA frames for the pushed resource. In practice, server push is deprecated in Chrome 106+ and removed from most implementations because:
+   - Pushed resources compete with the response body for bandwidth
+   - The browser may already have the resource cached (wasted bytes)
+   - 103 Early Hints is the recommended replacement
+
+   ```
+   # Instead of server push, use 103 Early Hints:
+   HTTP/1.1 103 Early Hints
+   Link: </style.css>; rel=preload; as=style
+   Link: </app.js>; rel=preload; as=script
+
+   HTTP/2 200
+   Content-Type: text/html
+   # ... full response follows
+   ```
+
+6. **Remove HTTP/1.1 workarounds.** After confirming HTTP/2 works, reverse these HTTP/1.1 hacks:
+   - **Remove domain sharding** — consolidate assets to fewer origins (one origin = one multiplexed connection)
+   - **Stop concatenating all CSS/JS into single files** — HTTP/2 makes fine-grained splitting viable (better cache granularity)
+   - **Remove image sprites** — individual images with HTTP/2 avoid downloading unused sprite sections
+
+7. **Measure improvement.** Compare before/after using WebPageTest with the "Connection View" to visualize multiplexing. Key metrics: number of TCP connections (should approach 1 per origin), TTFB for individual resources (should overlap), and total page load time.
+
+## Details
+
+### Binary Framing and Stream Lifecycle
+
+Each HTTP/2 stream goes through a defined lifecycle: idle -> open -> half-closed -> closed. Streams use odd numbers for client-initiated requests and even numbers for server-initiated pushes. The maximum concurrent streams is negotiated in SETTINGS frames (default: 100 in most implementations). If the limit is reached, new requests queue until a stream closes.
+
+Frame sizes are limited by SETTINGS_MAX_FRAME_SIZE (default: 16,384 bytes, max: 16,777,215 bytes). Larger frames reduce framing overhead but increase head-of-line blocking at the TCP level.
+
+### Connection Coalescing
+
+HTTP/2 can reuse a connection for multiple origins if: (1) the origins resolve to the same IP address, and (2) the TLS certificate covers both origins (via SAN or wildcard). For example, if `cdn.example.com` and `api.example.com` share a certificate and resolve to the same IP, the browser uses one connection for both.
+
+### TCP-Level Head-of-Line Blocking
+
+HTTP/2 eliminates HTTP-level head-of-line blocking (multiple requests in flight simultaneously), but TCP-level head-of-line blocking remains. If a TCP packet is lost, all streams on that connection stall until the packet is retransmitted. On lossy networks (mobile, high-latency), this can negate multiplexing benefits. HTTP/3 (QUIC) solves this by using UDP with per-stream loss recovery.
+
+Measured impact: at 2% packet loss, HTTP/2 performance degrades by approximately 30-40% compared to ideal conditions. At 5% loss, multiple HTTP/1.1 connections can outperform HTTP/2's single multiplexed connection.
+
+### Worked Example: Akamai HTTP/2 Migration
+
+Akamai measured an 8x improvement in page load time under high-latency conditions (300ms RTT) by enabling HTTP/2 multiplexing. The test page loaded 100 image tiles. Under HTTP/1.1 with 6 connections per origin, loading was serialized in batches of 6. Under HTTP/2, all 100 requests were multiplexed over a single connection, with frames interleaved based on priority. The key insight: the improvement is most dramatic on high-latency connections where connection establishment cost dominates.
+
+### Worked Example: Etsy HTTP/2 Adoption
+
+Etsy migrated to HTTP/2 and measured a 13% reduction in median page load time. Their approach: (1) deploy HTTP/2 at the CDN edge, (2) remove domain sharding that split assets across 4 origins, (3) switch from concatenated bundles to per-page code splitting. The consolidated single-origin approach reduced DNS lookups from 4 to 1 and TCP handshakes from 24 (4 origins x 6 connections) to 1. Cache efficiency improved because individual changed modules invalidated only their chunk, not the entire bundle.
+
+### Anti-Patterns
+
+**Domain sharding with HTTP/2.** HTTP/1.1 browsers limited connections to 6 per origin, so sites spread assets across multiple domains (cdn1.example.com, cdn2.example.com). With HTTP/2, this splits the multiplexed connection into multiple connections, each with its own HPACK state and priority tree. Consolidate to one origin.
+
+**Overly aggressive server push.** Pushing resources the client already has cached wastes bandwidth. The client can send RST_STREAM to cancel a push, but the server may have already transmitted significant data. Use 103 Early Hints instead — the client can skip preloading resources it has cached.
+
+**Single mega-bundle.** HTTP/1.1 favored fewer, larger files to minimize requests. HTTP/2 makes request overhead negligible, so fine-grained code splitting is preferred: each module changes independently, enabling granular cache invalidation. A recommended baseline: one vendor chunk (rarely changes) + one chunk per route (changes independently).
+
+**Ignoring stream priorities.** Without explicit priority configuration, the server may send low-priority resources (analytics scripts, tracking pixels) before high-priority ones (CSS, fonts). Use `fetchpriority` attributes and server-side priority tuning.
+
+**Enabling HTTP/2 only at the CDN edge, not origin-to-CDN.** If your CDN terminates HTTP/2 at the edge but uses HTTP/1.1 for origin connections, you lose multiplexing benefits on the backend leg. Ensure your origin supports HTTP/2 and configure the CDN to use HTTP/2 for origin fetches. Cloudflare, Fastly, and Akamai all support HTTP/2 to origin.
+
+**Not testing with realistic concurrency levels.** HTTP/2 multiplexing benefits scale with the number of concurrent requests. Testing with a page that loads 5 resources will show minimal improvement over HTTP/1.1. Real-world SPAs often load 50-100 resources (chunks, images, API calls). Test with production-representative page loads to accurately measure HTTP/2 impact. Use WebPageTest's "Connection View" to confirm streams are actually multiplexed rather than serialized.
+
+### Decision Guidance: Bundling Strategy Under HTTP/2
+
+HTTP/2 makes the "many small files vs. few large files" trade-off different from HTTP/1.1, but the optimal answer is not "never bundle." The ideal approach depends on cache invalidation frequency and total resource count:
+
+- **Under 30 resources per page** — fine-grained splitting works well. Each module caches independently, and HTTP/2 handles concurrent delivery efficiently.
+- **Over 100 resources per page** — even with HTTP/2, browser resource scheduling overhead and priority inversion become measurable. Group related modules into logical chunks (per-route bundles of 3-5 modules) to reduce total stream count while maintaining cache granularity.
+- **Shared vendor code** — always separate vendor dependencies (React, lodash, etc.) into a dedicated chunk. These change on a different cadence than application code and benefit from long-term caching.
+
+### Flow Control and Window Sizing
+
+HTTP/2 implements flow control at both the connection and stream levels. Each stream has a flow control window (default: 65,535 bytes) that limits how much data the sender can transmit before receiving a WINDOW_UPDATE frame. The connection also has a flow control window that limits aggregate data across all streams.
+
+Undersized flow control windows cause throughput bottlenecks on high-bandwidth connections. If the initial window is 64KB and the RTT is 100ms, maximum throughput per stream is limited to ~640KB/s regardless of available bandwidth. Most servers auto-tune window sizes, but verify that your server or reverse proxy (Nginx, Envoy, HAProxy) is configured with adequate initial window sizes for your bandwidth profile. Nginx default `http2_recv_buffer_size` is 256KB — increase to 1MB+ for high-throughput scenarios.
+
+### HPACK Compression Effectiveness by Header Type
+
+Not all headers benefit equally from HPACK compression. Headers that repeat identically across requests see the highest compression ratios because they are stored in the dynamic table and referenced by index:
+
+- **Cookies** — often the largest header (1-4KB), repeats identically on every request to the same origin. HPACK compresses subsequent requests to a single index reference (~1 byte). This alone can save 50-80% of total header bytes.
+- **Authorization** — Bearer tokens repeat across API calls. HPACK reduces these to index references after the first request.
+- **Varying headers** (e.g., unique request IDs, timestamps) — these cannot be deduplicated and must be transmitted in full each time. Minimize custom headers that change per request.
+
+The HPACK dynamic table has a maximum size (default: 4,096 bytes, configurable via SETTINGS_HEADER_TABLE_SIZE). On connections with highly diverse header values, the table evicts entries frequently, reducing compression effectiveness. Monitor HPACK compression ratio in server logs to detect this.
+
+For API-heavy applications with large cookie headers, increasing the table size to
+8,192 or 16,384 bytes can meaningfully improve compression ratios on long-lived
+connections.
+
+## Source
+
+- RFC 7540: HTTP/2 — https://www.rfc-editor.org/rfc/rfc7540
+- RFC 7541: HPACK Header Compression — https://www.rfc-editor.org/rfc/rfc7541
+- Ilya Grigorik, "High Performance Browser Networking" (O'Reilly), Chapter 12
+- Akamai HTTP/2 performance benchmarks — https://developer.akamai.com/blog
+- Chrome 106 Server Push deprecation — https://developer.chrome.com/blog/removing-push
+
+## 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.
+- HTTP/2 is verified active (Protocol column shows `h2`) and domain sharding is eliminated.
+- Number of TCP connections per origin approaches 1 for HTTP/2-enabled origins.
+- Resource loading waterfall shows parallel multiplexed delivery rather than sequential batching.

package/dist/agents/skills/claude-code/perf-http2-multiplexing/skill.yaml

@@ -0,0 +1,38 @@
+name: perf-http2-multiplexing
+version: '1.0.0'
+description: HTTP/2 stream multiplexing — concurrent requests, server push, prioritization, and head-of-line blocking mitigation
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-http3-quic
+  - perf-connection-costs
+  - perf-cdn-strategies
+  - perf-resource-hints
+  - perf-critical-rendering-path
+stack_signals: []
+keywords:
+  - http2
+  - multiplexing
+  - streams
+  - server push
+  - hpack
+  - head-of-line blocking
+  - connection coalescing
+  - binary framing
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-http3-quic/SKILL.md

@@ -0,0 +1,165 @@
+# HTTP/3 and QUIC Protocol
+
+> Understand HTTP/3's QUIC transport layer — 0-RTT connection establishment, UDP-based stream multiplexing without head-of-line blocking, connection migration across network changes, and built-in TLS 1.3 encryption for faster, more resilient web delivery.
+
+## When to Use
+
+- Users on mobile networks experience high latency due to TCP+TLS handshake overhead
+- HTTP/2 performance degrades on lossy networks (>1% packet loss) due to TCP head-of-line blocking
+- Application serves users who switch between WiFi and cellular connections mid-session
+- You are evaluating CDN providers and need to understand HTTP/3 support implications
+- Lighthouse or WebPageTest shows high connection establishment times on repeat visits
+- Your site serves a global audience with significant traffic from high-latency regions
+- You need to configure HTTP/3 fallback behavior via Alt-Svc headers
+- Real-time applications (video conferencing, live streaming) need resilient transport
+- You are configuring 0-RTT and need to understand replay attack implications
+- Performance testing shows TTFB variance correlated with network switching events
+
+## Instructions
+
+1. **Check current HTTP/3 support.** Verify your CDN or server supports HTTP/3. In Chrome DevTools Network panel, the Protocol column shows `h3` for HTTP/3 connections. Test with curl: `curl --http3 -I https://example.com`. Check server headers for `alt-svc: h3=":443"` which advertises HTTP/3 availability.
+
+2. **Understand QUIC transport fundamentals.** QUIC is a UDP-based transport protocol that integrates TLS 1.3. Unlike TCP, QUIC handles multiplexing at the transport layer, so packet loss on one stream does not block other streams.
+
+   ```
+   TCP + TLS 1.2 (HTTP/2):     QUIC (HTTP/3):
+   ┌──────────────────┐        ┌──────────────────┐
+   │ 1 RTT: TCP SYN   │        │ 1 RTT: QUIC      │
+   │ 1 RTT: TCP ACK   │        │   handshake +     │
+   │ 1 RTT: TLS hello │        │   TLS 1.3 +       │
+   │ 1 RTT: TLS finish│        │   first data      │
+   │ First data: 3 RTT │        │ First data: 1 RTT │
+   └──────────────────┘        └──────────────────┘
+                                (0 RTT on reconnect)
+   ```
+
+3. **Configure Alt-Svc advertisement.** The server advertises HTTP/3 availability via the Alt-Svc response header. The browser remembers this and attempts QUIC on subsequent connections.
+
+   ```
+   # Server response header
+   Alt-Svc: h3=":443"; ma=86400
+
+   # Nginx configuration
+   add_header Alt-Svc 'h3=":443"; ma=86400';
+
+   # Caddy automatically enables HTTP/3
+   ```
+
+4. **Enable 0-RTT for repeat connections.** QUIC's 0-RTT mode allows clients to send data in the first packet on reconnection using cached server parameters. This eliminates handshake latency entirely for repeat visitors.
+
+   ```
+   First visit:  Client ─── QUIC handshake (1 RTT) ──→ Server
+   Repeat visit: Client ─── 0-RTT data + handshake ──→ Server
+                 (data sent immediately, no waiting for handshake)
+   ```
+
+   **Security consideration:** 0-RTT data can be replayed by an attacker. Only allow 0-RTT for idempotent requests (GET, HEAD). Non-idempotent requests (POST, PUT, DELETE) must use 1-RTT mode.
+
+5. **Leverage connection migration.** When a mobile user switches from WiFi to cellular, TCP connections break (IP address changes). QUIC connections survive because they are identified by a Connection ID, not by IP:port tuple. Configure connection ID rotation for privacy.
+
+6. **Configure fallback behavior.** Not all networks support UDP (some corporate firewalls block it). Implement graceful fallback:
+   - Browser tries HTTP/3 (QUIC over UDP)
+   - If UDP is blocked, falls back to HTTP/2 (TCP)
+   - Alt-Svc cache remembers working protocol
+
+7. **Measure improvement.** Compare HTTP/2 vs HTTP/3 using WebPageTest with mobile network profiles. Focus on: TTFB (especially repeat visits with 0-RTT), performance under packet loss (2-5% loss scenarios), and connection migration success rate.
+
+## Details
+
+### QUIC Packet Structure
+
+QUIC packets contain one or more frames. Each frame belongs to a specific stream. Unlike TCP, QUIC handles loss recovery per-stream: if stream 3 loses a packet, streams 1 and 5 continue unaffected. This eliminates the TCP head-of-line blocking problem that affects HTTP/2.
+
+Each QUIC connection starts with a cryptographic handshake that integrates TLS 1.3. The handshake and encryption are inseparable — there is no unencrypted QUIC. This means middleboxes cannot inspect or modify QUIC traffic (unlike TCP where TLS is a separate layer).
+
+### QPACK Header Compression
+
+HTTP/3 uses QPACK instead of HPACK for header compression. HPACK requires in-order delivery (which TCP provides), but QUIC streams may arrive out of order. QPACK handles this by using separate unidirectional streams for the dynamic table, allowing header blocks to be decoded independently.
+
+### Congestion Control
+
+QUIC implements pluggable congestion control at the application layer (not in the kernel like TCP). Common algorithms:
+
+- **Cubic** — default in most implementations, similar to TCP Cubic
+- **BBR (Bottleneck Bandwidth and Round-trip propagation time)** — Google's algorithm, better for high-bandwidth, high-latency paths
+- **BBRv2** — improved fairness with Cubic flows
+
+### Worked Example: Google Search Latency
+
+Google deployed QUIC (the precursor to HTTP/3) across their services and measured an 8% reduction in search latency globally. The improvement was particularly dramatic in high-latency regions: India saw a 15% reduction in search result page load time, primarily from 0-RTT eliminating handshake roundtrips. On YouTube, QUIC reduced rebuffering by 18% on mobile networks due to connection migration surviving WiFi-to-cellular handoffs during video playback.
+
+### Worked Example: Cloudflare HTTP/3 Measurements
+
+Cloudflare measured a 12.4% improvement in time-to-first-byte for HTTP/3 vs HTTP/2 connections on mobile networks. The improvement was attributed to: (1) 0-RTT on repeat connections saving one full RTT (~50-150ms on mobile), (2) elimination of TCP head-of-line blocking under the 1-3% packet loss typical of mobile networks, and (3) faster loss recovery from QUIC's more granular acknowledgment mechanism. On wired connections with low packet loss, the improvement was smaller (~3-5%), primarily from 0-RTT savings.
+
+### Anti-Patterns
+
+**Assuming HTTP/3 is universally available.** Approximately 5-8% of networks block UDP traffic (corporate firewalls, some ISPs). Always configure Alt-Svc based fallback to HTTP/2. Test in environments with UDP blocking before deployment.
+
+**Not configuring 0-RTT replay protection.** 0-RTT data can be captured and replayed. An attacker could replay a 0-RTT GET request to trigger server-side effects. Only allow 0-RTT for safe, idempotent methods. Implement server-side replay detection for sensitive endpoints.
+
+**Ignoring connection migration for mobile traffic.** If your audience is primarily mobile, connection migration is a major benefit. Ensure your load balancer and CDN support QUIC connection IDs — some L4 load balancers route by IP:port and will break connection migration.
+
+**Serving HTTP/3 without optimizing the TLS certificate chain.** QUIC's initial handshake must fit in the initial congestion window. An oversized certificate chain (>4KB) requires multiple roundtrips, negating the 1-RTT handshake benefit. Use ECDSA certificates (smaller than RSA), minimize chain length, and enable OCSP stapling.
+
+**Disabling QUIC retry tokens in production.** QUIC retry tokens protect against IP address spoofing amplification attacks. Without retry, an attacker can send a small initial packet with a spoofed source IP and the server responds with a much larger handshake — a classic amplification vector. Always enable retry tokens in production. The cost is one additional roundtrip for the first connection, but subsequent connections from the same client are not affected.
+
+**Not monitoring QUIC-specific metrics.** Standard HTTP monitoring (status codes, TTFB) misses QUIC-specific failure modes. Track: 0-RTT acceptance rate (should be >80% for repeat visitors), connection migration success rate, UDP block rate (percentage of clients falling back to TCP), and handshake failure rate. A sudden drop in 0-RTT acceptance may indicate a server key rotation issue or middlebox interference.
+
+### Decision Guidance: When HTTP/3 Provides the Most Benefit
+
+HTTP/3 is not uniformly better than HTTP/2 in all scenarios. The largest gains appear under specific conditions:
+
+- **High packet loss (>1%)** — HTTP/3's per-stream loss recovery eliminates head-of-line blocking. On networks with 2-3% packet loss (typical mobile), HTTP/3 can be 30-50% faster than HTTP/2.
+- **High RTT (>100ms)** — 0-RTT saves an entire roundtrip on repeat connections. At 200ms RTT, this saves 200ms of latency — significant for perceived performance.
+- **Mobile users switching networks** — connection migration keeps sessions alive across WiFi-to-cellular transitions. Without it, users experience 1-3 second stalls while TCP connections are re-established.
+- **Low packet loss, low RTT (wired connections)** — improvement is marginal (3-5%). The cost of deploying and maintaining HTTP/3 infrastructure may not be justified for intranet or datacenter-to-datacenter traffic.
+
+### QUIC and Load Balancers
+
+QUIC connections are identified by Connection IDs, not IP:port tuples. This creates challenges for load balancers that route based on the 5-tuple (src IP, src port, dst IP, dst port, protocol). If a QUIC connection migrates (client IP changes), a naive load balancer routes the migrated packets to a different backend server, breaking the connection.
+
+Solutions:
+
+- **Connection ID-aware load balancers** — encode routing information in the Connection ID itself. The load balancer extracts the backend server identifier from the Connection ID without maintaining per-connection state. RFC 9312 defines a standardized format for this.
+- **Shared state backends** — store QUIC session state in a shared store (Redis, memcached) so any backend can resume a migrated connection. Adds latency but works with existing L4 load balancers.
+- **CDN termination** — terminate QUIC at the CDN edge and use HTTP/2 or HTTP/1.1 to the origin. This is the simplest approach and avoids load balancer complexity entirely. Most CDNs (Cloudflare, Fastly, Akamai) support this.
+
+### UDP Path MTU Discovery
+
+QUIC runs over UDP, which does not have TCP's built-in path MTU discovery. QUIC implements its own PMTU discovery by sending probe packets of increasing size. If a packet exceeds the path MTU, it is silently dropped (unlike TCP where ICMP messages signal the issue). Some networks block ICMP "Packet Too Big" messages, making PMTU discovery unreliable. QUIC's initial packet size is capped at 1200 bytes (the minimum guaranteed MTU for IPv6) to ensure the handshake succeeds. After connection establishment, QUIC can probe for larger MTU to improve throughput for bulk transfers.
+
+### Debugging QUIC Connections
+
+QUIC's encryption makes traditional packet inspection tools (tcpdump, Wireshark) less useful — the payload is encrypted. To debug QUIC issues, use QUIC-aware tooling:
+
+- **Chrome's net-export** — `chrome://net-export/` captures QUIC session logs including handshake details, stream states, and congestion control metrics
+- **qlog** — standardized QUIC event logging format (RFC 9516). Most QUIC implementations support qlog output. Visualize with qvis (https://qvis.quictools.info/)
+- **SSLKEYLOGFILE** — set this environment variable to capture TLS keys, enabling Wireshark to decrypt QUIC traffic for development debugging (never in production)
+
+## Source
+
+- RFC 9000: QUIC Transport Protocol — https://www.rfc-editor.org/rfc/rfc9000
+- RFC 9114: HTTP/3 — https://www.rfc-editor.org/rfc/rfc9114
+- RFC 9204: QPACK Header Compression — https://www.rfc-editor.org/rfc/rfc9204
+- Google QUIC Discovery paper — "The QUIC Transport Protocol: Design and Internet-Scale Deployment" (SIGCOMM 2017)
+- Cloudflare HTTP/3 performance analysis — https://blog.cloudflare.com/http3-the-past-present-and-future/
+
+## 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.
+- HTTP/3 is active (Protocol column shows `h3`) with Alt-Svc fallback to HTTP/2 configured.
+- 0-RTT is enabled for idempotent requests with replay protection for non-idempotent endpoints.
+- TTFB on repeat visits shows measurable improvement from 0-RTT connection establishment.

package/dist/agents/skills/claude-code/perf-http3-quic/skill.yaml

@@ -0,0 +1,37 @@
+name: perf-http3-quic
+version: '1.0.0'
+description: HTTP/3 and QUIC protocol — 0-RTT connections, connection migration, stream-level flow control, and UDP-based transport
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - perf-http2-multiplexing
+  - perf-connection-costs
+  - perf-cdn-strategies
+  - perf-compression
+stack_signals: []
+keywords:
+  - http3
+  - quic
+  - 0-rtt
+  - connection migration
+  - udp transport
+  - stream multiplexing
+  - congestion control
+  - tls 1.3
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/perf-image-formats/SKILL.md

@@ -0,0 +1,183 @@
+# Image Formats
+
+> Master modern image format selection — WebP, AVIF, and JPEG XL encoding characteristics, quality-to-size trade-offs, automated conversion pipelines, content negotiation with the picture element, and format-specific optimization for photographic, illustrative, and UI image types.
+
+## When to Use
+
+- Images account for a significant portion of page weight (common: 40-60% of total bytes)
+- Lighthouse flags "Serve images in next-gen formats" with substantial savings
+- JPEG and PNG are served without considering WebP or AVIF alternatives
+- Image-heavy pages (e-commerce, portfolios, news) have slow LCP due to hero image size
+- A CDN or image service is available but format negotiation is not configured
+- Users on mobile networks experience slow image loading
+- You need to decide between lossy and lossless compression for different image types
+- A build pipeline processes images but does not generate modern format variants
+- Thumbnail generation produces unnecessarily large files
+- Image quality is visibly degraded and you need to find the optimal quality setting
+
+## Instructions
+
+1. **Understand format capabilities and browser support.**
+
+   ```
+   Format    | Lossy | Lossless | Alpha | Animation | Browser Support
+   ----------|-------|----------|-------|-----------|----------------
+   JPEG      | Yes   | No       | No    | No        | Universal
+   PNG       | No    | Yes      | Yes   | No        | Universal
+   WebP      | Yes   | Yes      | Yes   | Yes       | 97%+ (all modern)
+   AVIF      | Yes   | Yes      | Yes   | Yes       | 92%+ (Chrome, Firefox, Safari 16.4+)
+   JPEG XL   | Yes   | Yes      | Yes   | Yes       | Safari 17+, limited elsewhere
+   ```
+
+2. **Select the right format by image type.** Different content benefits from different formats:
+
+   ```
+   Photographs (complex, many colors):
+     Best: AVIF (30-50% smaller than JPEG at equivalent quality)
+     Fallback: WebP (25-35% smaller than JPEG)
+     Legacy: JPEG
+
+   UI elements, logos, icons with transparency:
+     Best: WebP lossless (26% smaller than PNG)
+     Alternative: AVIF lossless
+     Simple graphics: SVG (vector, infinitely scalable)
+
+   Screenshots, text-heavy images:
+     Best: WebP lossless or AVIF lossless
+     Avoid: JPEG (text artifacts at any quality)
+
+   Animated content:
+     Best: AVIF animated (much smaller than GIF)
+     Fallback: WebP animated
+     Consider: MP4/WebM video for long animations
+   ```
+
+3. **Implement format negotiation with the picture element.**
+
+   ```html
+   <picture>
+     <!-- AVIF: best compression, served to supporting browsers -->
+     <source srcset="hero.avif" type="image/avif" />
+     <!-- WebP: wide support, good compression -->
+     <source srcset="hero.webp" type="image/webp" />
+     <!-- JPEG: universal fallback -->
+     <img src="hero.jpg" alt="Hero image" width="1200" height="600" />
+   </picture>
+   ```
+
+4. **Automate format conversion in the build pipeline.** Use sharp for high-performance server-side conversion:
+
+   ```javascript
+   // build-images.js using sharp
+   const sharp = require('sharp');
+   const glob = require('glob');
+
+   const QUALITY = { avif: 50, webp: 75, jpeg: 80 };
+
+   async function convertImage(inputPath) {
+     const base = inputPath.replace(/\.(jpg|jpeg|png)$/i, '');
+
+     await Promise.all([
+       sharp(inputPath).avif({ quality: QUALITY.avif, effort: 6 }).toFile(`${base}.avif`),
+       sharp(inputPath).webp({ quality: QUALITY.webp, effort: 6 }).toFile(`${base}.webp`),
+       sharp(inputPath).jpeg({ quality: QUALITY.jpeg, mozjpeg: true }).toFile(`${base}.opt.jpg`),
+     ]);
+   }
+
+   glob.sync('src/images/**/*.{jpg,jpeg,png}').forEach(convertImage);
+   ```
+
+5. **Configure quality settings by content type.** AVIF and WebP quality scales are not equivalent to JPEG quality:
+
+   ```
+   Content Type          | AVIF Quality | WebP Quality | JPEG Quality
+   ----------------------|-------------|-------------|-------------
+   Hero/banner photos    | 50-60       | 75-80       | 80-85
+   Thumbnails            | 40-50       | 65-75       | 70-80
+   Product photos        | 55-65       | 78-82       | 82-88
+   Background textures   | 35-45       | 60-70       | 65-75
+   Lossless (UI/text)    | lossless    | lossless    | N/A (use PNG)
+   ```
+
+6. **Implement server-side content negotiation.** When the picture element is impractical (CMS content, email), use Accept header negotiation:
+
+   ```nginx
+   # Nginx: serve AVIF/WebP based on Accept header
+   map $http_accept $img_suffix {
+     "~image/avif"  ".avif";
+     "~image/webp"  ".webp";
+     default        "";
+   }
+
+   location ~* ^(/images/.+)\.(jpe?g|png)$ {
+     set $base $1;
+     set $ext $2;
+     add_header Vary Accept;
+     try_files $base$img_suffix.$ext $uri =404;
+   }
+   ```
+
+7. **Use image CDN services for on-the-fly conversion.** Services like Cloudflare Images, Imgix, or Cloudinary handle format conversion, resizing, and optimization automatically:
+
+   ```html
+   <!-- Cloudflare Image Resizing -->
+   <img src="/cdn-cgi/image/format=auto,width=800,quality=75/images/hero.jpg" />
+
+   <!-- Imgix -->
+   <img src="https://example.imgix.net/hero.jpg?auto=format&w=800&q=75" />
+   ```
+
+## Details
+
+### AVIF Encoding Characteristics
+
+AVIF is based on the AV1 video codec and achieves the highest compression ratios of any still image format. At equivalent perceptual quality, AVIF is typically 30-50% smaller than JPEG and 20% smaller than WebP. The trade-off is encoding speed: AVIF encoding is 10-100x slower than JPEG encoding at high effort levels. This makes AVIF ideal for pre-processed assets (build pipelines, CDN origin) but impractical for real-time encoding. Decoding is fast and hardware-accelerated on modern devices.
+
+### Perceptual Quality Metrics
+
+SSIM (Structural Similarity) and Butteraugli are used to compare formats at equivalent perceptual quality. An AVIF at quality 50 and a JPEG at quality 80 may have identical SSIM scores (e.g., 0.95) while the AVIF is 45% smaller. Always compare formats at equivalent perceptual quality, not at equivalent quality parameter values. The tools dssim and ssimulacra2 provide reliable perceptual comparisons.
+
+### Worked Example: Netflix Promotional Images
+
+Netflix generates AVIF, WebP, and JPEG variants of every promotional image (title cards, hero banners, episode stills). Their pipeline runs ssimulacra2 to find the minimum quality parameter for each format that meets their perceptual threshold (ssimulacra2 score < 1.0). Result: AVIF title cards average 12KB vs 28KB for equivalent JPEG, a 57% reduction. Across their catalog of millions of images, this saves petabytes of CDN bandwidth annually. They use the picture element with AVIF first, WebP second, JPEG fallback.
+
+### Worked Example: Unsplash Photo Delivery
+
+Unsplash serves 2+ billion image requests monthly. They generate multiple format variants at upload time using libvips (the library underlying sharp). Each photo exists in AVIF, WebP, and JPEG at multiple quality tiers. Their CDN (Imgix) handles format negotiation via the Accept header and Vary response header. The combination of modern formats and responsive sizing reduced their median image transfer size from 350KB to 85KB — a 76% reduction — while maintaining photographer-grade quality standards.
+
+### Anti-Patterns
+
+**Using the same quality parameter across formats.** AVIF quality 80 and JPEG quality 80 produce vastly different file sizes and visual quality. Always calibrate per-format quality settings using perceptual metrics, not matching numbers.
+
+**Converting PNG screenshots to lossy WebP/AVIF.** Text-heavy screenshots and UI mockups should use lossless compression. Lossy encoding creates visible artifacts around text edges that are particularly noticeable at normal viewing distances.
+
+**Serving AVIF without a fallback.** AVIF browser support is ~92% but not universal. Always provide WebP and JPEG fallbacks via the picture element or Accept header negotiation.
+
+**Re-encoding already-compressed images.** Converting a low-quality JPEG to AVIF does not improve quality — it compounds compression artifacts. Always convert from the highest-quality source (original upload, RAW, or lossless PNG).
+
+## Source
+
+- web.dev: Serve images in modern formats — https://web.dev/articles/serve-images-webp
+- AVIF specification — https://aomediacodec.github.io/av1-avif/
+- sharp documentation — https://sharp.pixelplumbing.com/
+- Squoosh — https://squoosh.app/
+- Can I Use: AVIF — https://caniuse.com/avif
+
+## 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 photographic images are served in AVIF with WebP and JPEG fallbacks.
+- Format selection uses the picture element or server-side content negotiation.
+- Quality settings are calibrated per format and content type using perceptual metrics.
+- Build pipeline automatically generates modern format variants from source images.
+- Image-heavy pages show at least 30% byte reduction compared to JPEG-only serving.