name	web-perf
description	Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (FCP, LCP, TBT, CLS, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed.

Web Performance Audit

Audit web page performance using Chrome DevTools MCP tools. This skill focuses on Core Web Vitals, network optimization, and high-level accessibility gaps.

Prerequisites

This skill requires the chrome-devtools MCP server. If tools like performance_start_trace or navigate_page are unavailable, ask the user to install it in their MCP config:

"chrome-devtools": {
  "type": "local",
  "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
}

Workflow

Copy this checklist to track progress:

Audit Progress:
- [ ] Phase 1: Performance trace (navigate + record)
- [ ] Phase 2: Core Web Vitals analysis
- [ ] Phase 3: Network analysis
- [ ] Phase 4: Layout shift identification
- [ ] Phase 5: Accessibility snapshot
- [ ] Phase 6: Codebase analysis (if applicable)

Phase 1: Performance Trace

Navigate to the target URL:
```
navigate_page(url: "<target-url>")
```
Start a performance trace with reload to capture cold-load metrics:
```
performance_start_trace(autoStop: true, reload: true)
```
Wait for trace completion, then retrieve results.

Phase 2: Core Web Vitals Analysis

Use performance_analyze_insight to extract key metrics. Common insight names (assumes latest Chrome DevTools; names may vary across versions—use the insight set IDs returned by the trace to discover available insights):

Metric	Insight Name	What to Look For
LCP	`LCPBreakdown`	Time to largest contentful paint; breakdown of TTFB, resource load, render delay
CLS	`CLSCulprits`	Elements causing layout shifts
Render Blocking	`RenderBlocking`	CSS/JS blocking first paint
Document Latency	`DocumentLatency`	Server response time issues
Network Dependencies	`NetworkRequestsDepGraph`	Request chains delaying critical resources

Example:

performance_analyze_insight(insightSetId: "<id-from-trace>", insightName: "LCPBreakdown")

Key thresholds (good/needs-improvement/poor):

FCP: < 1.8s / < 3s / > 3s
LCP: < 2.5s / < 4s / > 4s
TBT: < 200ms / < 600ms / > 600ms
CLS: < 0.1 / < 0.25 / > 0.25
Speed Index: < 3.4s / < 5.8s / > 5.8s

Phase 3: Network Analysis

List all network requests to identify optimization opportunities:

list_network_requests(resourceTypes: ["Script", "Stylesheet", "Document", "Font", "Image"])

Look for:

Render-blocking resources: JS/CSS in <head> without async/defer/media attributes
Network chains: Resources discovered late because they depend on other resources loading first (e.g., CSS imports, JS-loaded fonts)
Missing preloads: Critical resources (fonts, hero images, key scripts) not preloaded
Caching issues: Missing or weak Cache-Control, ETag, or Last-Modified headers
Large payloads: Uncompressed or oversized JS/CSS bundles
Unused preconnects: If flagged, verify by checking if ANY requests went to that origin. If zero requests, it's definitively unused—recommend removal. If requests exist but loaded late, the preconnect may still be valuable.

For detailed request info:

get_network_request(reqid: <id>)

Phase 4: Layout Shift Identification

From the performance trace insights, identify:

Elements causing CLS (images without dimensions, dynamically injected content, web fonts causing FOIT/FOUT)
Ads or embeds pushing content down

Phase 5: Accessibility Snapshot

Take an accessibility tree snapshot:

take_snapshot(verbose: true)

Flag high-level gaps:

Missing or duplicate ARIA IDs
Elements with poor contrast ratios (check against WCAG AA: 4.5:1 for normal text, 3:1 for large text)
Focus traps or missing focus indicators
Interactive elements without accessible names

Codebase Analysis

After the browser audit, analyze the codebase to understand where improvements can be made. Skip this phase if auditing a third-party site without codebase access.

Detect Framework & Bundler

Search for configuration files to identify the stack:

Tool	Config Files
Webpack	`webpack.config.js`, `webpack.*.js`
Vite	`vite.config.js`, `vite.config.ts`
Rollup	`rollup.config.js`, `rollup.config.mjs`
esbuild	`esbuild.config.js`, build scripts with `esbuild`
Parcel	`.parcelrc`, `package.json` (parcel field)
Next.js	`next.config.js`, `next.config.mjs`
Nuxt	`nuxt.config.js`, `nuxt.config.ts`
SvelteKit	`svelte.config.js`
Astro	`astro.config.mjs`

Also check package.json for framework dependencies and build scripts.

Tree-Shaking & Dead Code

Webpack: Check for mode: 'production', sideEffects in package.json, usedExports optimization
Vite/Rollup: Tree-shaking enabled by default; check for treeshake options
Look for: Barrel files (index.js re-exports), large utility libraries imported wholesale (lodash, moment)

Unused JS/CSS

Check for CSS-in-JS vs. static CSS extraction
Look for PurgeCSS/UnCSS configuration (Tailwind's content config)
Identify dynamic imports vs. eager loading

Polyfills

Check for @babel/preset-env targets and useBuiltIns setting
Look for core-js imports (often oversized)
Check browserslist config for overly broad targeting

Compression & Minification

Check for terser, esbuild, or swc minification
Look for gzip/brotli compression in build output or server config
Check for source maps in production builds (should be external or disabled)

Output Format

Present findings as:

Core Web Vitals Summary - Table with metric, value, and rating (good/needs-improvement/poor)
Top Issues - Prioritized list of problems with estimated impact (high/medium/low)
Recommendations - Specific, actionable fixes with code snippets or config changes
Codebase Findings - Framework/bundler detected, optimization opportunities

Guidelines

Be assertive: Don't hedge with "if not needed" or "consider removing". Verify claims by checking the network requests, DOM, or codebase. If a preconnect is unused, confirm no requests went to that origin—then state definitively "Remove this unused preconnect."
Verify before recommending: If you suggest removing something, first confirm it's actually unused. Search the codebase or inspect network traffic.
Quantify impact: Use estimated savings from insights. Don't recommend changes with 0ms estimated savings as high-priority.
Skip non-issues: If render-blocking resources load in <100ms and have 0ms estimated impact, note they exist but don't recommend action.
Be specific: Instead of "optimize images", say "compress hero.png (currently 450KB) to WebP" or "add width/height to prevent layout shift on line 47".
Prioritize ruthlessly: Focus on issues with measurable impact. A site with 200ms LCP and 0 CLS is already excellent—say so and move on.

web-perf

Install Skill

SKILL.md