Source: addyosmani/web-quality-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the Core Web Vitals skill?
The Core Web Vitals skill teaches a coding agent to fix LCP, INP and CLS the measured way: look at real-user field data first, record a browser trace to find the cause, change only what the failing metric implicates, and re-measure. It works with Claude Code, Codex, Cursor and other agents that read the SKILL.md format.
It is one of six skills in addyosmani/web-quality-skills, Addy Osmani's "(unofficial) measurement-first collection" of skills built around Lighthouse, Chrome DevTools, Core Web Vitals, WCAG and search guidance.
The skill's description reads: "Optimize Core Web Vitals (LCP, INP, CLS) for better page experience using field and lab evidence. Use when asked to "improve Core Web Vitals", "fix LCP", "reduce CLS", "optimize INP", "page experience optimization", or "fix layout shifts"."
As of 24 October 2026, its skills.sh page listed 31.7K installs (snapshot, 24 October 2026).
What does it do?
The skill is model-invoked, so the agent loads it when you mention Core Web Vitals, LCP, INP, CLS or layout shifts. Its core rule is "measure before optimizing." The SKILL.md sets this sequence for a runnable URL:
- Check page-level CrUX data at the 75th percentile, with a clearly labeled origin fallback if page data doesn't exist.
- Record a browser performance trace under stated conditions. With Chrome DevTools MCP, that's the
performance_start_tracetool. - Analyze only the insights tied to the failing metric, then inspect the code and resources they implicate.
- Re-run the same lab measurement after the fix. It tells the agent not to claim an immediate field improvement, because CrUX and your own monitoring need new visits.
It uses the same thresholds as Google's Web Vitals guidance:
| Metric | Measures | Good | Needs improvement | Poor |
|---|---|---|---|---|
| LCP | Loading | 2.5 s or less | 2.5 s to 4 s | over 4 s |
| INP | Responsiveness | 200 ms or less | 200 ms to 500 ms | over 500 ms |
| CLS | Visual stability | 0.1 or less | 0.1 to 0.25 | over 0.25 |
LCP. The SKILL.md lists the usual causes: slow server response (TTFB over 800 ms), render-blocking CSS, a hero image the browser discovers late, and content that only appears after client-side JavaScript. It prefers a discoverable <img> with fetchpriority="high" and adds a preload only when the trace shows late discovery, warning that speculative preloads compete for bandwidth. It also covers the Speculation Rules API for prerendering likely next pages, with caveats: each prerender costs about a full page load, analytics fire early, and only Chromium browsers act on it.
INP. It splits a slow interaction into input delay, processing time and presentation delay, and tells the agent not to touch the event handler until the trace shows which phase dominates.
CLS. It tells the agent to find the element that triggered a shift, noting that the element that moved "may be the victim of content inserted above it."
There are short framework fixes for Next.js, React and Vue or Nuxt, such as next/image with priority for LCP and useTransition for INP.
What's in the folder:
SKILL.md: the workflow, thresholds, LCP fixes, measurement sources and framework notes.references/LCP.md,references/INP.md,references/CLS.md: deeper guides the agent reads only when a trace or field data points at that metric.
It also links to two files in the sibling performance skill: references/MEASUREMENT.md for the measurement workflow and references/RUM.md for production monitoring, where it recommends the web-vitals library.
How do you install it?
This skill plus the performance skill. The skills.sh command installs core-web-vitals alone. The skills CLI accepts --skill more than once, so you can add performance in the same step and keep the measurement links working:
npx skills add https://github.com/addyosmani/web-quality-skills --skill core-web-vitals --skill performance
Add -g for all projects. In Claude Code the folders land in .claude/skills/, or ~/.claude/skills/core-web-vitals/ with -g, the standard Claude Code skill locations. The CLI needs Node.js 22.20 or later.
All six skills as a Claude Code plugin. From the README:
/plugin marketplace add addyosmani/web-quality-skills
/plugin install web-quality-skills@addy-web-quality-skills
It then appears as /web-quality-skills:core-web-vitals.
Codex and Gemini CLI. The README gives codex plugin marketplace add addyosmani/web-quality-skills for Codex CLI v0.122 or later (then @core-web-vitals in chat) and gemini extensions install https://github.com/addyosmani/web-quality-skills. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
claude.ai. The README suggests adding the skill to project knowledge or pasting the SKILL.md into a conversation. You can also zip the folder and upload it under Customize, then Skills, per the Claude Help Center.
Recommended: a trace tool. The skill is built around Chrome DevTools MCP. Its docs give this Claude Code command:
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
See Claude Code MCP for how MCP servers work in Claude Code.
How do you use it?
Give it a URL it can load, and tell it which metric or page matters if you know.
Example prompts (suggestions, not quotes from the repo):
Our product page has poor LCP on mobile in Search Console. Trace http://localhost:3000/product/42 and fix the cause.Find what causes layout shift on the blog index and reserve space for it.The filter dropdown feels slow. Trace the interaction and tell me which INP phase is the problem before changing code.Add web-vitals reporting so we get LCP, INP and CLS from real users, broken down by route.
Requirements: a runnable page plus Chrome DevTools MCP, or the Lighthouse CLI or PageSpeed Insights as a fallback. For field data you need CrUX data for the page or origin, or your own monitoring.
Tips and limits
- Lab is not field. The skill warns against comparing "a single lab value directly with a field p75." A fast local trace doesn't mean your users see a pass.
- Source-only runs give hypotheses. Without runtime evidence it won't claim a metric is failing, which is the right call but means less certainty.
- Lighthouse audits skip performance in DevTools MCP. The skill notes that
lighthouse_audit"intentionally covers non-performance Lighthouse categories," so it uses traces instead. The DevTools MCP tool reference says the same. - Ranking is not promised. The README notes Google uses Core Web Vitals in its page-experience systems, "but a passing score does not promise a ranking change."
- Security audit. On 24 October 2026 its skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Pass. The skill ships no scripts of its own.
The skill is MIT licensed, so you can copy and adapt it if you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and the three files in references/. Paste the repo link instead and Kipt lists all six skills, so you can bring in performance at the same time. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/web-quality-skills.
Similar skills
- Web performance skill: Cloudflare's five-phase audit that traces a page load and ranks fixes, a good second opinion on LCP and CLS.
- SEO skill: the sibling skill that points to this one for page experience signals.
- Web best practices skill: blocking scripts, passive listeners and console errors from the same repo.
- Accessibility skill: the repo's WCAG 2.2 audit, often run in the same pass.