Lighthouse

Run Google Lighthouse to measure web quality and verify that fixes actually moved the numbers. Lighthouse audits a URL across Performance, Accessibility, SEO, Best Practices, and (since v13.6) Agentic Browsing and returns a 0–100 score per category plus a list of failing audits with specific guidance.

When to use this skill

This skill measures. Sibling quality skills fix. The workflow is a loop:

measure (this skill)  →  fix (performance / accessibility / seo / best-practices)  →  re-measure

Reach for this skill to: get a baseline score, find the specific failing audits, set a performance budget, gate a build in CI, or prove a change improved (or regressed) a metric. Don't guess at improvements — measure, change one thing, measure again.

How it works

1. Pick a target URL — a deployed URL, or a local dev/preview server (http://localhost:3000).
2. Run Lighthouse — prefer scripts/run-lighthouse.sh <url>; it runs several times, takes the median, and emits compact JSON (full reports are huge and waste context).
3. Read category scores + failing audits from the JSON.
4. Map each failing audit to a fix using the relevant quality skill.
5. Re-run and report the before/after delta.

Install & run (CLI)

The Lighthouse readme installs it globally (v13 needs Node 22.19+), and it drives a local Chrome/Chromium you must have installed:

npm install -g lighthouse
# or: yarn global add lighthouse

lighthouse https://example.com --view    # basic run; --view opens the HTML report

Lighthouse auto-detects an installed Chrome; point it at a specific binary with the CHROME_PATH environment variable.

For a quick one-off without a global install, npx lighthouse <url> also works — the published CLI bin supports it, though the official docs only cover the global install.

Machine-readable run for an agent (JSON to a file, quiet, headless):

npx lighthouse https://example.com \
  --quiet \
  --chrome-flags="--headless=new" \
  --only-categories=performance,accessibility,seo,best-practices \
  --output=json --output-path=./lh.json

The wrapper script (recommended)

scripts/run-lighthouse.sh wraps the CLI, runs N times, picks the median run (Lighthouse's own guidance for reducing variance), and prints compact JSON to stdout — category scores plus the failing audits only. Human logs go to stderr.

# Usage: run-lighthouse.sh <url> [runs] [categories]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility

Example output:

{
  "success": true,
  "url": "https://example.com",
  "runs": 3,
  "lighthouseVersion": "13.x",
  "scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96, "agentic-browsing": 100 },
  "failingAudits": [
    { "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
    { "id": "unused-javascript", "score": 0.3, "displayValue": "Potential savings of 180 KiB" }
  ]
}

Key flags

For every flag (throttling, emulation, -G/-A gather/audit mode, plugins, etc.), see the complete references/CLI-FLAGS.md — or run lighthouse --help.

Reading the JSON

Scores are 0–1 floats under categories; audit details are under audits.

# Category scores (0–1) → multiply by 100 for the familiar score
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json

# Core Web Vitals lab values
jq '.audits | {
  LCP: .["largest-contentful-paint"].displayValue,
  CLS: .["cumulative-layout-shift"].displayValue,
  TBT: .["total-blocking-time"].displayValue
}' lh.json

# Failing/opportunity audits worth acting on
jq '[.audits[] | select(.score != null and .score < 0.9)
     | {id, score, displayValue}]' lh.json

Performance budgets

Heads up: the old LightWallet --budget-path CLI flag and the performance-budget / timing-budget audits have been removed from Lighthouse. There is no longer a built-in budget flag on the lighthouse CLI.

Enforce budgets in one of two ways instead:

1. Lighthouse CI assertions (recommended) — gate a build on metric thresholds and category scores with @lhci/cli. This is the supported, modern path; see references/CI.md for lighthouserc.js assertions like:

   assertions: {
     'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
     'cumulative-layout-shift':  ['error', { maxNumericValue: 0.1 }],
     'total-blocking-time':      ['warn',  { maxNumericValue: 300 }],
     'categories:performance':   ['error', { minScore: 0.9 }],
   }

2. Assert on the JSON yourself — for a quick local/CI gate without LHCI, read the numeric values out of the report and fail your script:

   lcp=$(jq '.audits["largest-contentful-paint"].numericValue' lh.json)
   awk "BEGIN{exit !($lcp <= 2500)}" || { echo "LCP over budget: ${lcp}ms"; exit 1; }

Lab vs. field — read this before trusting a number

Lighthouse is a lab tool: one synthetic load, on emulated hardware, with simulated throttling. It is reproducible and great for catching regressions, but it is not what real users experience.

• Variance is real. A single run can swing ±5–10 points. Run at least 3 times and take the median (the wrapper script does this).
• For real-user data, use field sources instead: CrUX, PageSpeed Insights (which shows both lab + field), Search Console's Core Web Vitals report, or the web-vitals library reporting to your analytics.
• INP can't be measured in a single Lighthouse load — it needs real interactions. Lighthouse reports Total Blocking Time (TBT) as its lab proxy; treat field INP as the source of truth.

Lighthouse v13 note (Insight Audits)

Since v13 (Oct 2025+), Lighthouse migrated Performance to Insight Audits. Several legacy per-opportunity audit IDs were merged or removed (e.g. CLS-related audits → cls-culprits-insight, image audits → image-delivery-insight). The advice is unchanged; only audit IDs and report grouping moved. When parsing older reports, treat them as a superset, not a contradiction. Pin a Lighthouse version in CI so audit IDs you assert on stay stable.

Lighthouse CI lags the CLI. @lhci/cli 0.15.x bundles Lighthouse 12.x, so lhci autorun reports v12 audit IDs — no *-insight audits and no agentic-browsing category — even when npx lighthouse gives you v13. Write LHCI assertions against the version LHCI actually runs (check lighthouseVersion in its reports). See references/CI.md.

Agentic Browsing category (v13.6+)

Lighthouse 13.6 added an agentic-browsing category: checks that AI agents can read and operate the page. Upstream flags it as still under development and subject to change, so treat its audit IDs as unstable and don't hard-gate CI on it yet.

Most of these are not applicable (score: null) on a page with no llms.txt, ARD manifest, or WebMCP tools. They are excluded from the score, not failed. The HTML report shows this category as a fraction of passed audits; in JSON its score is still a 0–1 float. Fix failures in agent-accessibility-tree with an accessibility skill; for the rest, see the agentic web guide.

How the Performance score is built

The Performance score is a weighted blend of lab metrics (weights shift between versions). As of recent versions, the heavy hitters are roughly:

Because TBT/LCP/CLS dominate, fixing those moves the score most. Use the Lighthouse Scoring Calculator to see exactly how a metric change maps to points.

CI and the programmatic API

Kept in references to stay focused:

• Continuous integration — @lhci/cli, lighthouserc.js assertions, and a GitHub Actions workflow: references/CI.md
• Programmatic (Node) API — driving Lighthouse with chrome-launcher for custom flows, user flows, and bulk runs: references/PROGRAMMATIC-API.md

Mapping audits to fixes

Pair this skill with addyosmani/web-quality-skills for the fix side of the loop.

References

• Lighthouse repo & Node CLI
• Understanding the results
• User flows
• Lighthouse CI (budgets via assertions)
• Scoring
• Full CLI flag reference · CI setup · Programmatic API