performance-optimization

Files (5)

• README.md
• SKILL.md
• audit-template.md · references/
• optimization-checklist.md · references/
• optimization-playbook.md · references/

SKILL.md (first lines)

# Performance Optimization

Diagnose web performance issues and produce a remediation plan. Stack-agnostic. Anchored to Core Web Vitals and standard browser performance patterns.

This skill goes deeper than the performance checks in `qa-testing` and `seo-technical`. Use this when performance itself is the goal.

---

## When to use

- Fixing Core Web Vitals (LCP, INP, CLS)
- Diagnosing slow page loads
- Reducing JavaScript bundle size
- Optimizing images, fonts, and other assets
- Fixing layout shift, render-blocking resources, jank
- Pre-launch performance verification
- Annual performance health check

## When NOT to use

- General QA after deploys (use `qa-testing`)
- Technical SEO including indexing and crawling (use `seo-technical`)
- Code review for general bugs (use `code-review-web`)

---

## Required inputs

- The site or page under audit
- Specific performance complaints if any
- Target metrics (Core Web Vitals thresholds, Lighthouse score, custom)
- Browser dev tools access
- Performance monitoring data if available (Real User Monitoring, lab data)

---

## The framework: Core Web Vitals

Three metrics carry most of the weight for both user experience and SEO:

### LCP (Largest Contentful Paint)

**What it measures:** Time until the largest visible content element finishes rendering.

**Targets:**
- Good: under 2.5 seconds
- Needs improvement: 2.5 to 4.0 seconds
- Poor: over 4.0 seconds

**Common causes of poor LCP:**
- Slow server response time (TTFB over 800ms)
- Render-blocking JavaScript or CSS
- Large unoptimized images for the LCP element
- Late-loading fonts that delay text render
- Client-side rendering of the LCP element

**Common fixes:**
- Server-render the LCP element (no client-side render)
- Optimize the LCP image (right format, right size, preloaded)
- Reduce render-blocking resources (defer non-critical CSS and JS)
- Use modern image formats (WebP, AVIF)
- Specify image dimensions to skip layout pass

### INP (Interaction to Next Paint)

**What it measures:** Responsiveness to user interactions. Replaces FID as the standard interactivity metric.

**Targets:**
- Good: under 200ms
- Needs improvement: 200 to 500ms
- Poor: over 500ms

**Common causes of poor INP:**
- Long-running JavaScript blocking the main thread
- Heavy event handlers
- Excessive React/framework re-renders
- Synchronous operations in event handlers
- Large DOM with expensive layouts

**Common fixes:**
- Break long tasks into chunks (`scheduler.yield()` or `setTimeout`)
- Memoize expensive computations
- Debounce or throttle high-frequency event handlers (scroll, mousemove, input)
- Avoid synchronous storage or DOM operations in handlers
- Reduce DOM size (under 1500 elements ideal)
- Use CSS over JS for animations where possible

### CLS (Cumulative Layout Shift)

**What it measures:** How much the page jumps around as it loads. Unexpected layout shifts hurt usability.

**Targets:**
- Good: under 0.1
- Needs improvement: 0.1 to 0.25
- Poor: over 0.25

**Common causes of poor CLS:**
- Images without explicit dimensions
- Ads, embeds, iframes that load late
- Dynamically injected content above existing content
- Web fonts causing FOIT/FOUT (flash of invisible/unstyled text)
- CSS that depends on JS-loaded data

**Common fixes:**
- Always specify `width` and `height` (or `aspect-ratio`) on images and videos
- Reserve space for ads and embeds before they load
- Use `font-display: optional` or `font-display: swap` thoughtfully
- Avoid injecting content above the fold after initial render
- Preload critical fonts

---

## Beyond Core Web Vitals

### Time to First Byte (TTFB)

The server response time. Bad TTFB makes everything else worse.

**Targets:** under 800ms ideal.

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills