Core Web Vitals Optimization Skill

A Claude Code skill for measuring, diagnosing, and fixing the three Core Web Vitals metrics — LCP, INP, and CLS — that directly impact Google Search rankings and user experience.

When to Use This Skill

Choose this skill when:

• Improving Google PageSpeed Insights or Lighthouse scores
• Diagnosing slow page loads, janky interactions, or layout shifts
• Optimizing a web application for SEO ranking signals
• Preparing a site for Google's page experience update
• Profiling and fixing specific performance regressions

Consider alternatives when:

• You need server-side performance optimization (use APM tools)
• You need network-level optimization (use CDN configuration)
• You need comprehensive accessibility auditing (use an accessibility skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add core-web-vitals

# Analyze a page for Core Web Vitals issues
claude "analyze the Core Web Vitals for our homepage"

# Fix specific metric
claude "our LCP is 4.2 seconds, help me bring it under 2.5s"

Copy
// Measure Core Web Vitals in production
import { onLCP, onINP, onCLS } from 'web-vitals';

function sendToAnalytics(metric: { name: string; value: number; id: string }) {
  navigator.sendBeacon('/api/vitals', JSON.stringify(metric));
}

onLCP(sendToAnalytics);
onINP(sendToAnalytics);
onCLS(sendToAnalytics);

Core Concepts

The Three Metrics

Metric	Measures	Good	Needs Work	Poor
LCP (Largest Contentful Paint)	Loading performance	≤ 2.5s	≤ 4.0s	> 4.0s
INP (Interaction to Next Paint)	Responsiveness	≤ 200ms	≤ 500ms	> 500ms
CLS (Cumulative Layout Shift)	Visual stability	≤ 0.1	≤ 0.25	> 0.25

LCP Optimization

Copy
<!-- Preload the LCP image -->
<link rel="preload" as="image" href="/hero-image.webp" fetchpriority="high" />

<!-- Use modern formats with fallback -->
<picture>
  <source srcset="/hero.avif" type="image/avif" />
  <source srcset="/hero.webp" type="image/webp" />
  <img src="/hero.jpg" alt="Hero" width="1200" height="600"
       fetchpriority="high" decoding="async" />
</picture>

Copy
// Avoid render-blocking resources
// Move non-critical CSS to async loading
<link rel="preload" href="/non-critical.css" as="style"
      onload="this.onload=null;this.rel='stylesheet'" />

// Inline critical CSS
<style>{criticalCSS}</style>

INP Optimization

Copy
// Break up long tasks with scheduler.yield()
async function processLargeList(items: Item[]) {
  for (const item of items) {
    processItem(item);

    // Yield to the main thread periodically
    if (navigator.scheduling?.isInputPending()) {
      await scheduler.yield();
    }
  }
}

// Use requestIdleCallback for non-urgent work
requestIdleCallback(() => {
  analytics.track('page_view');
  prefetchNextPage();
});

CLS Prevention

Copy
/* Always set dimensions on images and videos */
img, video {
  width: 100%;
  height: auto;
  aspect-ratio: 16 / 9; /* Prevents layout shift */
}

/* Reserve space for dynamic content */
.ad-slot {
  min-height: 250px;
  contain: layout;
}

/* Use transform for animations, not layout properties */
.animate-in {
  transform: translateY(0);   /* Good: no layout shift */
  /* top: 0; */               /* Bad: causes layout shift */
}

Configuration

Parameter	Type	Default	Description
lcp_target	number	2.5	Target LCP in seconds
inp_target	number	200	Target INP in milliseconds
cls_target	number	0.1	Target CLS score
audit_scope	string	"page"	Scope: page, route, site
include_filmstrip	boolean	false	Generate visual filmstrip of page load
device	string	"mobile"	Test device: mobile, desktop
connection	string	"4g"	Network throttling: 4g, 3g, slow-3g
report_format	string	"markdown"	Output: markdown, json, html

Best Practices

1. Measure in the field, not just in lab — Lighthouse scores are synthetic; use the web-vitals library to collect real user metrics (RUM) and identify issues that only appear on actual devices and networks.

2. Optimize LCP first since it has the biggest impact — preload the LCP element, use fetchpriority="high" on the hero image, inline critical CSS, and eliminate render-blocking scripts.

3. Set explicit dimensions on all media — every img, video, and iframe should have width and height attributes or CSS aspect-ratio to prevent CLS during loading.

4. Use contain: layout on dynamic content areas — ad slots, skeleton loaders, and lazy-loaded sections should reserve space with min-height and contain: layout to prevent shifts when content loads.

5. Defer non-critical JavaScript — use defer or async on script tags, code-split aggressively, and use requestIdleCallback or scheduler.yield() for analytics, tracking, and prefetching.

Common Issues

LCP regresses after adding a new above-the-fold component — New components above the fold compete with the LCP element for rendering priority. Audit fetchpriority settings and ensure the LCP element loads before decorative above-fold content.

INP spikes on specific interactions — Profile the interaction with Chrome DevTools Performance panel. Common causes: synchronous LocalStorage access, large React re-renders, or unoptimized event handlers. Break long tasks into smaller async chunks.

CLS caused by web fonts loading — Font swaps cause text to reflow. Use font-display: optional (prevents any shift) or font-display: swap with size-adjust to match fallback font metrics to the web font.