/webperf-core-web-vitals

name: webperf-core-web-vitals
description: Intelligent Core Web Vitals analysis with automated workflows and decision trees. Measures LCP, CLS, INP with guided debugging that automatically determines follow-up analysis based on results. Includes workflows for LCP deep dive (5 phases), CLS investigation (loading vs interaction), INP debugging (latency breakdown + attribution), and cross-skill integration with loading, interaction, and media skills. Use when the user asks about Core Web Vitals, LCP optimization, layout shifts, or interaction responsiveness. Compatible with Chrome DevTools MCP.
license: MIT
metadata:
  author: Joan Leon | @nucliweb
  version: 2.6.3
  mcp-server: chrome-devtools
  category: web-performance
  repository: https://github.com/nucliweb/webperf-snippets

WebPerf: Core Web Vitals

JavaScript snippets for measuring web performance in Chrome DevTools.

Running a script

1. Run the script with `mcp__chrome-devtools__evaluate_script`, passing the file instead of its code: `sourcePath` with the absolute path of `scripts/<Name>.js` in this skill, and `format: "script"`, since a script runs by itself and is not a function. Read the object it returns. The scripts have no console output, so the returned object is the result: `script`, `status` and the metric data (`value`, `rating`, `details`, `items`, `issues`), as described in `references/schema.md`. 2. When `status` is `"tracking"`, the script keeps observing the page. After the interactions, call the function named in `getDataFn` with another `mcp__chrome-devtools__evaluate_script` call, as an arrow function in `function`, for example `() => getINP()`, and read the object it returns. 3. When `status` is `"error"` or `"unsupported"`, read `error`: the page may not have loaded yet, or the browser lacks the API.

`sourcePath` and `format` need Chrome DevTools MCP 1.11.0 or later, and the server only reads files inside its workspace roots: the project, the temp folder and each `--workspace=<folder>` in its arguments. When it answers `Access denied`, as it does for a skill installed outside the project, such as in `~/.claude/skills/`, read the file and pass its code in `function`, still with `format: "script"`. A `--workspace` with the real folder of the skills makes the path work; the server follows symlinks, so a link to the folder is not enough.

Without Chrome DevTools MCP, run the same snippet with the [webperf-snippets CLI](https://webperf-snippets.net/CLI), which loads the page in headless Chromium and prints the same result objects: `npx webperf-snippets <url> --snippet <Name> --json`, where `<Name>` is the script name without `.js`. It needs Playwright and Chromium (`npm install --save-dev webperf-snippets playwright`, then `npx playwright install chromium`), and tracking snippets take `--interact-script <file>` to drive the interactions.

Scripts

• `scripts/CLS.js` — Cumulative layout shift (CLS)
• `scripts/INP.js` — Interaction to next paint (INP)
• `scripts/LCP-Image-Entropy.js` — LCP image entropy
• `scripts/LCP-Subparts.js` — LCP subparts
• `scripts/LCP-Trail.js` — LCP trail
• `scripts/LCP-Video-Candidate.js` — LCP video candidate
• `scripts/LCP.js` — Largest contentful paint (LCP)

Common Workflows

Complete Core Web Vitals Audit

When the user asks for a comprehensive Core Web Vitals analysis or "audit CWV":

1. **LCP.js** - Measure Largest Contentful Paint 2. **CLS.js** - Measure Cumulative Layout Shift 3. **INP.js** - Measure Interaction to Next Paint 4. **LCP-Subparts.js** - Break down LCP timing phases 5. **LCP-Trail.js** - Track LCP candidate evolution

LCP Deep Dive

When LCP is slow or the user asks "debug LCP" or "why is LCP slow":

1. **LCP.js** - Establish baseline LCP value 2. **LCP-Subparts.js** - Break down into TTFB, resource load, render delay 3. **LCP-Trail.js** - Identify all LCP candidates and changes 4. **LCP-Image-Entropy.js** - Check if LCP image has visual complexity issues 5. **LCP-Video-Candidate.js** - Detect if LCP is a video (poster or video element)

CLS Investigation

When layout shifts are detected or the user asks "debug CLS" or "layout shift issues":

1. **CLS.js** - Measure overall CLS score 2. **Layout-Shift-Loading-and-Interaction.js** _(pending — available in webperf-interaction skill)_ 3. Cross-reference with **webperf-loading** skill:

• Find-Above-The-Fold-Lazy-Loaded-Images.js (lazy images causing shifts)
• Fonts-Preloaded-Loaded-and-used-above-the-fold.js (font swap causing shifts)

INP Debugging

When interactions feel slow or the user asks "debug INP" or "slow interactions":

1. **INP.js** - Measure overall INP value; call `getINP()` after interactions, `getINPDetails()` for the 15 slowest interactions 2. **Interactions.js** _(pending — available in webperf-interaction skill)_ 3. **Input-Latency-Breakdown.js** _(pending — available in webperf-interaction skill)_ 4. **Long-Animation-Frames.js** _(pending — available in webperf-interaction skill)_ 5. **Long-Animation-Frames-Script-Attribution.js** _(pending — available in webperf-interaction skill)_

Video as LCP Investigation

When LCP is a video element (detected by LCP-Video-Candidate.js):

1. **LCP-Video-Candidate.js** - Identify video as LCP candidate 2. **Video-Element-Audit.js** (from Media skill) - Audit video loading strategy 3. **LCP-Subparts.js** - Analyze video loading phases 4. Cross-reference with **webperf-loading** skill:

• Resource-Hints-Validation.js (check for video preload)
• Priority-Hints-Audit.js (check for fetchpriority on video)

Image as LCP Investigation

When LCP is an image (most common case):

1. **LCP.js** - Measure LCP timing 2. **LCP-Subparts.js** - Break down timing phases 3. **LCP-Image-Entropy.js** - Analyze image complexity 4. Cross-reference with **webperf-media** skill:

• Image-Element-Audit.js (check format, dimensions, lazy loading)

5. Cross-reference with **webperf-loading** skill:

• Find-Above-The-Fold-Lazy-Loaded-I