PageSpeed Forensics: find why your mobile PageSpeed score is low

Description

What it is

PageSpeed Forensics is a skill for Claude Code (and any agent that reads SKILL.md) for the last mile of the mobile score in PageSpeed Insights and Lighthouse. It ships a step-by-step method, 6 technical guides and 11 Node.js scripts with no dependencies, except sharp (optional) for the visual comparison.

The problem it solves

The usual advice (compress images, defer JavaScript, preload the LCP image) tends to leave a page around 85. The missing mobile points hide where those checklists never look: how the HTML crosses the network, when Chrome produces the first frame and how Lighthouse's simulator turns a run into a score.

If Lighthouse says 100 on your PC and PageSpeed says 85, if first paint comes 1–2 s late with nothing blocking it, or if almost all of your TBT comes from the tag manager, this skill finds the cause and proves it with evidence.

How it works in 3 steps

• Read the real report: psi-report saves from pagespeed.web.dev the scores, metrics, audits with their tables, the test environment, the final screenshot and the filmstrip, with no API key.
• Reproduce PageSpeed on your computer: a local proxy adds latency and server time, and delivers the HTML in TCP slow-start flights. You run Lighthouse 3–5 times per variant and compare medians of simulated and observed metrics.
• Test and verify: the proxy applies fixes without rebuilding (inline CSS, no font or image preloads, content-visibility or your own CSS). Before moving anything into your code, you compare grayscale, blurred screenshots and check anchors, fixed elements and page height.

What you get

• SKILL.md: the 6-step method, a symptom → cause table and a report template (finding, evidence, cause, fix, risk, how to revert and whether it needs the owner's decision)
• 6 guides: first-frame freeze, first TCP flight (initcwnd), render-path fixes and their traps, Lighthouse and PageSpeed quirks, third-party tags and verification
• 11 scripts: flight-proxy, burst-timing, lh-runs, lh-summary, trace-milestones, main-thread-per-second, trace-first-frame, psi-report, screens, visual-diff and section-heights
• README in Spanish and English, and a license file

Who it is for

• Developers and agencies whose sites are stuck around 85–90 on mobile after applying the usual advice
• Teams with Next.js or React landing pages (the guides include Next.js-specific notes)
• Anyone who needs to explain with data why PageSpeed and their own computer don't give the same score

Requirements

• Node.js 22 or later
• Google Chrome or Chromium (or the CHROME_PATH variable)
• Internet access for Lighthouse (it runs with npx, no install) and to read PageSpeed
• sharp, only for the visual comparison (npm i -D sharp)
• A production build of your site served over HTTP on your computer, for the lab
• Claude Code or another agent that reads SKILL.md (or run the scripts by hand)

Important notes

• It does not guarantee a score: it finds causes and measures each change with medians. The result depends on your site and on what you decide to change.
• Some fixes are business decisions (deferring analytics, changing the server or adding a CDN): the skill shows you the cost and the decision is yours.
• CrUX field data takes 28 days to reflect a change.
• The skill, the guides and the script output are in English; the README is in Spanish and English.
• psi-report reads the PageSpeed web page: if Google changes its design, that script may stop working.
• Raising the server's initial TCP window requires admin access to a Linux server, or a CDN.
• Independent product, not affiliated with Google. PageSpeed Insights, Lighthouse and Chrome are trademarks of Google.