pagespeed-audit

name

pagespeed-audit

description

Use when the user asks to audit website performance, check PageSpeed scores, review Core Web Vitals (LCP/CLS/INP/FCP/TBT), find slow pages, or run a performance audit. Fetches real data from Google PageSpeed Insights API, maps each failing audit to the project codebase, then produces a prioritized split: immediate fixes (safe to apply now) vs. tickets (need planning). Triggers on phrases like 'pagespeed audit', 'check my performance score', 'why is my site slow', 'Core Web Vitals audit', 'PageSpeed report', or /pagespeed-audit.

PageSpeed Audit

Fetch real PageSpeed Insights data, trace each finding to the codebase, and produce a prioritized action plan: quick wins applied (or listed) immediately, larger efforts written as tickets.

Reference: references/audit-mappings.md maps every Lighthouse audit ID to investigation commands and fix guidance. Load it before investigating findings.

---

Workflow

0. Resolve inputs

If not provided in $ARGUMENTS, ask:

• URL to audit (required)
• Project directory (optional — defaults to current working directory)
• Mode: report (findings only) or fix (apply quick wins immediately)

Default mode is report if not specified.

---

1. Fetch PageSpeed data

Run the fetch script (both mobile and desktop):

python <skill-root>/scripts/fetch_pagespeed.py <url>

The script reads PAGESPEED_API_KEY from the environment if set. Without a key it still works but is rate-limited. Output is JSON with mobile and desktop keys.

---

2. Parse and present scores

From the JSON output, build a summary table:

                  Mobile    Desktop
Performance         --        --
Accessibility       --        --
Best Practices      --        --
SEO                 --        --

Core Web Vitals (Mobile)
  LCP:    Xs   [Good / Needs Improvement / Poor]
  CLS:    X    [Good / Needs Improvement / Poor]
  INP:    Xms  [Good / Needs Improvement / Poor]
  FCP:    Xs
  TBT:    Xms
  SI:     Xs

Field Data (real users, if available):
  LCP p75: X  CLS p75: X  INP p75: X

Score convention: 90-100 Good, 50-89 Needs Improvement, 0-49 Poor.

Show mobile scores primarily (Google uses mobile-first indexing). Note if desktop differs significantly.

---

3. Load audit mappings

Read references/audit-mappings.md now. It contains investigation commands and fix patterns for every audit ID returned by Lighthouse.

---

4. Investigate the codebase

For each failing opportunity and diagnostic (score < 0.9), use the investigation commands from the mappings reference to check whether the issue exists in the project.

Work through findings in impact order (lowest score / highest estimated savings first).

For each finding, state:

• Confirmed in code: yes / no / partial
• Location: file path(s) where the issue was found
• Evidence: the specific code or config that causes it

Skip investigation if no project directory is available — note this in the report.

---

5. Classify and prioritize

Split confirmed findings into two buckets using the classification table in references/audit-mappings.md:

Quick Fixes — safe to apply in < 2 hours, low regression risk:

• Image priority prop missing on hero
• Missing <link rel="preconnect">
• <img> tags replaceable with next/image
• font-display not set / missing next/font
• GIFs replaceable with <video>
• compress: false in next.config
• Below-fold images without lazy loading
• Missing sizes prop on <Image>

Tickets — need planning, profiling, or carry regression risk:

• Bundle splitting / unused JS
• Server-side caching / TTFB
• Tailwind purge / unused CSS audit
• Third-party script facades
• DOM virtualization
• INP (requires DevTools profiling session)

---

6. Output the report

## PageSpeed Audit — <url>
Audited: <date>  Strategy: mobile + desktop

### Scores
[table from step 2]

### Core Web Vitals
[CWV summary with pass/fail status]

### Quick Fixes (<N items)
For each: audit name | file/line | what to change | expected impact

### Tickets (<N items)
For each: audit name | why it's a ticket | investigation starting point | effort S/M/L

### Passed Audits
[brief list of what's already working]

---

7. Apply fixes (fix mode only)

In fix mode: apply each Quick Fix one at a time, confirm with the user before each change, then suggest re-running the audit to verify score improvement.

In report mode: list Quick Fixes as ready-to-apply but do not touch files.

---

Notes

• If the API returns no field data (CrUX), note "Lab data only — no real-user data available for this URL."
• If both mobile and desktop fail on the same audit, the fix is usually the same code path.
• PageSpeed scores fluctuate ~5 points between runs — a 1-2 point change is noise.
• next/image and next/font solve a large fraction of Next.js performance issues — check these first.
• For TTFB issues, look for getServerSideProps or un-cached fetch() in server components.