Skip to main content
skill CX Codex

performance-optimization · rampstackco — Claude Code skill: setup and usage

performance-optimization diagnoses web speed issues, Core Web Vitals, and JavaScript bundle size, delivering an actionable fix plan.

MIT 328 installs ★ 1,107 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add rampstackco/claude-skills --skill performance-optimization -a claude-code
Open on GitHub

What performance-optimization does

This skill focuses on website speed optimization. It evaluates pages against Core Web Vitals: LCP, INP, and CLS. For each metric, the assistant identifies typical bottlenecks such as slow server responses, main thread contention during user interactions, and unexpected layout shifts caused by unsized media.

Beyond basic vitals, it analyzes secondary factors: bundle bloat, code splitting per route, modern image delivery, and third-party script overhead. Target benchmarks include keeping initial compressed JavaScript under 170KB and server TTFB under 800ms.

Browser developer tools data or lab runs like Lighthouse are required to start an audit. If the task is checking crawlability or general regression bugs, dedicated SEO or QA workflows should handle that instead.

What it helps with

  • Diagnose and remediate poor LCP, INP, or CLS scores
  • Reduce JavaScript payload through tree-shaking and route splitting
  • Eliminate layout shifts caused by web fonts and unsized embeds
  • Audit third-party widgets blocking main thread execution

Example prompts for the agent

  • Analyze our slow LCP score and show how to optimize critical assets
  • Help split our JavaScript bundle to drop the initial download under 170KB
  • Audit these event handlers causing long tasks and poor INP

How to install performance-optimization

1Skills CLI (Vercel)

npx skills add rampstackco/claude-skills --skill performance-optimization -a claude-code

2Manually: put the files in place

~/.claude/skills/performance-optimization/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/performance-optimization/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about performance-optimization

How to install performance-optimization in Claude Code?

Run npx skills add rampstackco/claude-skills --skill performance-optimization -a claude-code in your terminal.

What does performance-optimization do?

It diagnoses runtime latency, asset overhead, and Core Web Vitals bottlenecks, then drafts concrete engineering steps to resolve them.

When should this skill not be used?

Skip it for crawlability indexing reviews or routine post-deploy bug sweeps, as those belong in technical SEO or QA testing workflows.

Source text

SKILL.md · MIT
---
name: performance-optimization
description: "Diagnose and fix web performance issues including Core Web Vitals (LCP, INP, CLS), bundle size, asset optimization, render performance, and runtime efficiency. Use this skill whenever the user wants to improve page speed, fix Core Web Vitals, optimize assets, reduce bundle size, debug slow renders, or systematically improve a site's performance. Triggers on performance, page speed, Core Web Vitals, LCP, INP, CLS, FID, TTFB, bundle size, code splitting, image optimization, lazy loading, render blocking, slow page, performance audit, Lighthouse score. Also triggers when traffic or conversion is dropping due to perceived slowness."
category: development
catalog_summary: "Core Web Vitals, asset optimization, render performance"
display_order: 4
---

# 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.

**Common causes:**
- Slow database queries on the request path
- N+1 query patterns
- Missing caching
- Server geographic distance from users (no CDN)
- Cold starts on serverless

**Fixes:**
- Cache database queries
- Use a CDN for static and cacheable dynamic content
- Optimize critical-path queries
- Pre-render where possible (SSG, ISR)
- Edge functions for low-latency dynamic content

### Bundle size

JavaScript shipped to the browser.

**Targets:**
- Initial JS under 170KB compressed for typical pages
- Lazy-loaded chunks under 100KB compressed each

**Common causes of bloat:**
- Importing entire libraries when only one function is used
- Bundling polyfills for modern browsers
- Including dev-only code in production
- Duplicate dependencies (multiple versions of the same library)
- Large client-side state (Redux store snapshots, etc.)

**Fixes:**
- Tree-shake imports (`import { fn } from 'lib'` not `import lib from 'lib'`)
- Code-split per route
- Lazy-load below-the-fold components
- Audit dependencies; replace heavy ones (e.g., moment.js → date-fns or native Intl)
- Build-time bundle analyzer to spot bloat
- Dynamic imports for rarely-used features

### Image optimization

Images are typically 60 to 80 percent of page weight.

**Best practices:**
- Modern formats: WebP everywhere supported, AVIF where supported
- Responsive images: `srcset` for different viewport sizes
- Lazy loading: `loading="lazy"` for below-the-fold
- Explicit dimensions: prevents CLS
- Right size: don't ship 4000px images for 800px display
- LCP image: preload, never lazy-load

### Font loading

Web fonts often delay text render and cause CLS.

**Best practices:**
- Self-host fonts (avoid third-party blocking)
- Preload critical fonts (`<link rel="preload" as="font">`)
- Use `font-display: swap` for non-critical fonts
- Subset fonts to remove unused glyphs
- Use variable fonts where possible
- Provide system-font fallback that visually matches

### Third-party scripts

Third parties (analytics, ads, chat widgets) often dominate performance budgets.

**Audit each:**
- Is it required?
- Can it load after page interaction (defer)?
- Can it run from a worker (off main thread)?
- Is the third party itself fast?
- Are there lighter-weight alternatives?

A common pattern: 50 percent of performance issues come from third-party scripts.

---

## Workflow

1. **Establish a baseline.** Lighthouse scan, WebPageTest run, or Real User Monitoring data. Capture current Core Web Vitals.
2. **Identify the worst offender.** LCP, INP, or CLS - which is failing? Focus there first.
3. **Diagnose specifically.** Browser dev tools (Performance tab, Network tab, Coverage tab). Identify the actual cause of the metric failure.
4. **Plan fixes.** Per identified issue, plan a specific change. Estimate impact and effort.
5. **Implement.** One fix at a time where possible. Easier to measure impact.
6. **Re-measure.** After each major fix, re-run Lighthouse and check Real User Monitoring.
7. **Iterate.** Performance is rarely solved in one pass. Plan for ongoing monitoring and fixes.

---

## Tools

**Lab tools** (run on demand):
- Lighthouse (built into Chrome DevTools)
- PageSpeed Insights (online)
- WebPageTest (online, more configurable)
- Browser Performance tab (deep flame graph analysis)

**Field tools** (real user data):
- Chrome User Experience Report (CrUX) - public data for any site
- Real User Monitoring (RUM) - your own users (DataDog, New Relic, custom, etc.)
- Search Console Core Web Vitals report

Lab tools are useful for diagnosis. Field tools are the source of truth for what users actually experience.

---

## Failure patterns

- **Optimizing without measuring.** Performance theater without baseline metrics. Always measure first.
- **Optimizing the wrong metric.** A great Lighthouse score with bad real-user metrics means your test conditions don't match users.
- **Over-optimizing.** Spending weeks shaving 10ms off TTFB while CLS is 0.4. Fix the worst offender first.
- **Lighthouse-driven optimization only.** Lighthouse runs in idealized conditions. Always check field data.
- **Single-page optimization.** Performance regressions creep in across the codebase. Build performance budgets and CI checks.
- **Treating every byte as equal.** A render-blocking 100KB script is worse than a deferred 500KB script.
- **Bundle size obsession.** Bundle size matters, but execution time matters more. A small bundle that takes 5 seconds to parse is worse than a larger bundle that runs fast.
- **Ignoring third parties.** "It's the analytics tag, not us." Third parties run on your domain in your users' eyes. Own them.

---

## Output format

Default output is a performance report at `performance-audit.md`.

Structure:
1. Executive summary
2. Methodology (tools, conditions, sample pages)
3. Current state (Core Web Vitals, Lighthouse scores, RUM data)
4. Critical issues (Core Web Vitals failures)
5. Important issues (sub-optimal but not failing)
6. Polish (further-than-required wins)
7. Remediation roadmap (sequenced)
8. Performance budget recommendations
9. Monitoring plan

For complex audits, include:
- Per-page Lighthouse exports
- Bundle analysis output
- Network waterfall screenshots
- Specific code snippets to change

---

## If required data is unavailable

This skill's output depends on data, measurements, or tool results it cannot generate on its own. When a required input, tool, or data source is unavailable or unverifiable, the sanctioned output is the deliverable with the gap stated: what was needed, what was actually obtained or verified, and which parts of the output are affected. Fabricating, estimating, or interpolating a required number to complete the deliverable is never sanctioned. A stated gap is a complete answer.

---

## Reference files

- [`references/audit-template.md`](references/audit-template.md) - Full performance audit report template.
- [`references/optimization-checklist.md`](references/optimization-checklist.md) - Quick-reference checklist of common optimizations by priority.
- [`references/optimization-playbook.md`](references/optimization-playbook.md) - Symptom-to-fix playbook for the common Core Web Vitals problems (LCP, INP, CLS).

© rampstackco · MIT · rampstackco/claude-skills

Similar skills

All skills for Frontend and UI →

performance-optimization by other authors comes first.

performance-optimization addyosmani performance-optimization — an agent skill that measures before it changes code: Core Web Vitals budgets, N+1 queries, missing indexes and slow endpoints. CX Codex +1 82,600installs performance-optimization gamedev-skills The performance-optimization Claude Code skill measures game frame time and tracks down low FPS or stutter in Godot, Unity, Unreal, and Roblox. It activates for profiling requests and frame-rate problems. CX Codex +1 14,200installs performance-optimization Mindrally performance-optimization — a rule set for web performance: server-side rendering, CSS, JavaScript, assets and caching. Useful when your agent writes frontend code and you want a bar to hold it to. CX Codex +1 907installs performance-optimization dylantarre performance-optimization is a skill for Claude Code that diagnoses and resolves janky UI animations and frame drops using core animation principles. CX Codex +1 591installs performance-optimization akillness performance-optimization turns profiler traces, load tests, and query plans into a targeted tuning brief. Pinpoints a single bottleneck and verifies fixes with before-and-after data. CX Codex +1 367installs web-performance-optimization davila7 web-performance-optimization — a Claude skill that walks through why a site loads slowly and fixes the bottlenecks step by step. CX Codex +1 3,490installs web-performance-audit secondsky web-performance-audit — a skill that audits page speed: pulls Core Web Vitals, finds bottlenecks and points at what to fix. Useful when LCP or CLS drifts out of range. CX Codex +1 553installs performance-and-web-vitals dembrandt The performance-and-web-vitals skill guides Lighthouse audits and Core Web Vitals fixes across LCP, CLS, and INP. It provides rules to optimize images, fonts, scripts, and layout shifts. CX Codex +1 1,200installs performance-engineering travisjneuman performance-engineering — a skill for Claude Code designed for full-stack web application performance optimization. Activates when Core Web Vitals drop, bundle sizes increase, or page response times degrade. CX Codex +1 144installs performance-budget-setter patricio0312rev The performance-budget-setter skill turns bundle, API, database, and render performance into measurable limits. Use it when CI checks and ongoing monitoring need clear targets. CX Codex +1 228installs performance-budget-guard davila7 performance-budget-guard — a Claude hook that measures your Next.js JS bundle after a build and blocks the deploy when it goes over the performance budget. 393installs

From the same set102

The whole set →
multi-step-form-design multi-step-form-design helps plan multi-step forms with progress, conditional fields, and save-and-resume flows. Use it when scoping a new form or reviewing a long one. CX Codex +1 338installs qa-testing qa-testing is a Claude Code skill for three-tier web page checks using browser console snippets, from post-deploy smoke tests to pre-launch QA. CX Codex +1 335installs editorial-qa editorial-qa is a skill that checks content before publication, including briefs, facts, brand voice, structure, SEO, and AI-content signals. It supports one-off pieces and sampling at scale. CX Codex +1 333installs pillar-content-architecture pillar-content-architecture — a skill that designs content hubs: pillar topic selection, cluster planning, internal linking, URL structure. Use it when content fails to rank despite decent individual pieces. CX Codex +1 333installs design-standards The design-standards skill applies practical design rules to pages and components, covering contrast, spacing, hierarchy, and mobile layouts. Use it while building UI or reviewing work before release. CX Codex +1 325installs launch-runbook The launch-runbook skill structures a product or website launch: pre-go-live checks, deployment sequencing, DNS cutover steps, post-launch verification, and rollback triggers. CX Codex +1 325installs interactive-product-tour interactive-product-tour is a Claude Code skill for designing in-product tours, tooltips, and contextual help. It activates when scoping trigger logic, tour architecture, or a hint system from scratch. CX Codex +1 324installs content-and-copy content-and-copy is a Claude Code skill for drafting and editing blog posts, explainers, and website copy with a five-part focus on structure and voice. CX Codex +1 324installs

Project sponsors

Companies that keep this analytics open