seo-lighthouse-audit

name	seo-lighthouse-audit
description	Run a Lighthouse audit against any URL via the local Lighthouse CLI or the PageSpeed Insights API fallback, parse category scores and failed audits, and map every failed audit ID to its official Chrome docs page plus a one-line fix. Use when user says "lighthouse", "lighthouse audit", "run lighthouse", "lighthouse score", or "pagespeed".
allowed-tools	["Read","Bash","WebFetch","Write"]

Lighthouse Audit & Fix Mapping

Lighthouse is Google's open-source page quality tool. It runs a series of audits against a URL and scores four categories: Performance, Accessibility, Best Practices, and SEO. Reference: https://developer.chrome.com/docs/lighthouse/overview

Scope notes (keep the report honest):

• PWA category was removed in Lighthouse v12 (2024). Do NOT score or report a PWA category. If the user asks for it, explain it no longer exists.
• Lighthouse is lab data — a single synthetic run on emulated hardware/network. Always recommend validating against CrUX field data (75th percentile of real users) before treating a score as ground truth. Delegate field-data analysis to the seo-core-web-vitals skill.
• Agentic Browsing is a new experimental category (llms.txt, WebMCP tools, accessibility-for-agents). It is informational only — it reports a pass ratio, not a 0-100 score. See https://developer.chrome.com/docs/lighthouse/agentic-browsing/scoring

Inputs

Input	Required	Default
URL to audit	Yes	—
Strategy (mobile/desktop)	No	mobile
Categories	No	performance, seo, best-practices, accessibility

Execution

1. Detect a local Lighthouse CLI:

   npx lighthouse --version 2>/dev/null || which lighthouse
   

   Requires Chrome installed locally. If either succeeds, prefer the CLI path (step 2); otherwise fall back to the PageSpeed Insights API (step 3).

2. CLI path — run headless and write JSON to a temp file:

   npx lighthouse <url> --output=json \
     --output-path=/tmp/lh-report.json \
     --chrome-flags="--headless" --quiet
   

   For desktop strategy add --preset=desktop.

3. API fallback — PageSpeed Insights v5 (no API key needed for light use; add &key= if one is configured):

   curl -s "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<url>&category=performance&category=seo&category=best-practices&category=accessibility&strategy=mobile" -o /tmp/psi.json
   

   The Lighthouse result lives under .lighthouseResult. Docs: https://developers.google.com/speed/docs/insights/v5/get-started Bonus: the same response embeds CrUX field data under loadingExperience — surface it as a lab-vs-field sanity check.

4. Parse the JSON:

   • Category scores: .categories[].score (multiply by 100).
   • Failed audits: every entry in .audits with score < 0.9 and a non-informative scoreDisplayMode (binary or numeric). Capture id, title, displayValue, and details.overallSavingsMs / overallSavingsBytes where present.
   • Key lab metrics: largest-contentful-paint, total-blocking-time, cumulative-layout-shift, first-contentful-paint, speed-index. Performance scoring weights: https://developer.chrome.com/docs/lighthouse/performance/performance-scoring

5. Map each failed audit to its docs page and a fix. Docs URL pattern:

   https://developer.chrome.com/docs/lighthouse/<category>/<audit-id>
   

   where <category> is performance, seo, best-practices, or accessibility. Use the reference table below for the highest-impact audits; for others, construct the URL from the pattern and write a one-line fix from the audit's own description field.

6. Prioritize: sort performance audits by estimated savings (ms/bytes), then list SEO and best-practices failures (these are usually binary pass/fail and cheap to fix).

High-Impact Audit Reference

Performance

Audit ID	One-line fix	Docs
render-blocking-resources	Inline critical CSS, defer non-critical CSS/JS	docs
unused-javascript	Code-split and lazy-load unused bundles	docs
uses-responsive-images	Serve appropriately sized images via srcset/sizes	docs
total-byte-weight	Reduce total payload below ~1.6 MB (compress, trim, lazy-load)	docs
bf-cache	Remove unload handlers and no-store headers blocking back/forward cache	docs
largest-contentful-paint	Preload the LCP resource, add fetchpriority="high"	docs
total-blocking-time	Break up long main-thread tasks, defer third-party JS	docs
dom-size	Keep DOM under ~1,500 nodes; virtualize long lists	docs
third-party-summary	Lazy-load or facade heavy third-party embeds	docs
font-display	Use font-display: swap to avoid invisible text	docs

Other frequent flags: unused-css-rules, unminified-javascript, unminified-css, uses-text-compression, uses-long-cache-ttl, uses-optimized-images, offscreen-images, server-response-time, redirects, uses-rel-preconnect, mainthread-work-breakdown, bootup-time, non-composited-animations — same URL pattern.

SEO

Audit ID	One-line fix	Docs
is-crawlable	Remove blocking noindex / robots.txt rules on indexable pages	docs
meta-description	Add a unique, descriptive meta description	docs
canonical	Add a single valid, absolute canonical URL	docs
hreflang	Fix hreflang codes and ensure reciprocal links	docs
http-status-code	Return 200 for indexable pages, not 4xx/5xx	docs
link-text	Replace "click here" with descriptive anchor text	docs

Also check: font-size (legible ≥12px text), tap-targets (48x48px touch targets), invalid-robots-txt, structured-data (manual).

Best Practices

Audit ID	One-line fix	Docs
viewport	Add <meta name="viewport" content="width=device-width, initial-scale=1">	docs
csp-xss	Add a strict Content-Security-Policy against XSS	docs
has-hsts	Send a Strict-Transport-Security header	docs

Also frequent: is-on-https, errors-in-console, no-vulnerable-libraries, image-aspect-ratio, uses-http2, deprecations, charset, doctype, external-anchors-use-rel-noopener, clickjacking-mitigation — same URL pattern.

Agentic Browsing (informational — do not score)

Experimental audits for AI-agent readiness: llms-txt (machine-readable site summary at /llms.txt — N/A if 404, flagged only on server error; see docs), WebMCP tool registration and schema validity, accessibility-for-agents, layout stability for agents. Report pass ratio only and cross-reference the seo-llms-txt and seo-robots-ai skills.

Output

# Lighthouse Audit: <url> (mobile|desktop, lab data)

## Category Scores
| Category | Score |
|----------|-------|
| Performance | XX/100 |
| Accessibility | XX/100 |
| Best Practices | XX/100 |
| SEO | XX/100 |

## Key Lab Metrics
| Metric | Value | Rating |
|--------|-------|--------|
| LCP | X.Xs | ✅/⚠️/❌ |
| TBT | XXXms | ✅/⚠️/❌ |
| CLS | 0.XX | ✅/⚠️/❌ |
| FCP / Speed Index | ... | ... |

## Failed Audits → Fixes (sorted by estimated savings)
| # | Audit | Category | Est. Savings | Fix | Docs |
|---|-------|----------|--------------|-----|------|
| 1 | render-blocking-resources | Performance | 1,200 ms | Inline critical CSS, defer the rest | link |
| ... | | | | | |

## Field vs Lab (if PSI response included loadingExperience)
Note agreement/divergence between lab metrics and CrUX field data.

## Caveats
- Lab data from a single emulated run — validate with CrUX field data
  (see seo-core-web-vitals skill) before declaring CWV pass/fail.
- PWA category removed in Lighthouse v12; Agentic Browsing is experimental
  and informational only.