Core Web Vitals Narrator

What this skill does

Reads a Lighthouse JSON report or a CrUX API response for one origin and narrates LCP, CLS, and INP scores into a prioritized fix plan. Each prioritized item names the offending element (when available) and a concrete code-level mitigation.

Inputs

• report_path: path to lighthouse-report.json or crux-response.json.
• report_kind: lighthouse or crux.
• Optional device: mobile (default) or desktop.

Steps

1. Detect format. Lighthouse reports have lhr.audits; CrUX has record.metrics.
2. Extract p75 for LCP, CLS, INP, plus any FCP/TTFB available. Convert CrUX histogram bins into a p75 estimate.
3. Score each metric: good, needs-improvement, poor per web.dev thresholds (LCP 2.5/4.0s, CLS 0.1/0.25, INP 200/500ms).
4. For Lighthouse, extract the LCP element from audits.largest-contentful-paint-element and the layout-shift sources from audits.layout-shift-elements.
5. Rank metrics by gap-to-good: priority = max(0, p75 - good_threshold) / (poor_threshold - good_threshold).
6. For each metric, generate suggestions:
   • LCP: preload hero image (<link rel="preload" as="image">), defer non-critical CSS, lazy-load below-the-fold images, use fetchpriority="high" on the hero.
   • CLS: set explicit width/height on images, reserve space for ads with min-height, avoid inserting DOM above existing content.
   • INP: split long tasks (>50ms), debounce input handlers, use requestIdleCallback for non-urgent work, audit third-party scripts.
7. Cite the offending element with its CSS selector if available (Lighthouse provides one).
8. Compose a markdown plan: H2 per metric, ordered list of suggestions, "expected effect" estimates.

Output

web-vitals-plan.md with an executive header (overall verdict, top metric to fix), a per-metric section with prioritized suggestions and selectors, and a "quick wins" appendix for the top three changes most likely to move scores.

Verification

Re-fetch the report after applying suggestions and confirm the targeted metric's p75 dropped by at least 10% (or moved one tier). Cross-check Lighthouse's largest-contentful-paint-element against the suggested selector — if the suggestion mitigates a different element, refine. CrUX data lags by 28 days; document this in the report header so users don't expect immediate movement.

Edge cases

• Origin with insufficient CrUX data: fall back to lab data only and warn.
• Lighthouse report run on localhost: caching and CDN behavior absent; results are advisory only.
• Sites with heavy A/B testing: split-test variants can dominate INP; recommend isolating tests before tuning.
• Reports older than 30 days: prepend a freshness warning; metrics may already have shifted.