gsc-lighthouse

GSC + Lighthouse health check

Pulls Google Search Console (sitemap status, per-URL index coverage, 28-day search analytics) and runs Lighthouse via the PageSpeed Insights API on the top 10 pages by clicks. Produces a single report a non-technical person can read.

The point: most "SEO audit" tools throw a hundred warnings at you. This one tells you what's actually broken, calibrates against false positives, and groups fixes by theme so you can ship a single PR instead of a hundred.

Step 1: Ask the user 2 questions

1. What's your GSC property? (the verified site in Search Console)

   • sc-domain:example.com, Domain property (covers all subdomains and protocols)
   • https://example.com/, URL-prefix property (one specific protocol + host)
   • If they don't know, link them to https://search.google.com/search-console and ask them to copy the property URL from the sidebar.

2. Do you have a PAGESPEED_API_KEY configured? (.env or shell env)

   • yes → Lighthouse step runs.
   • no / skip → Lighthouse step is skipped, GSC report still ships. (See README.md "Setup: PSI API key" for the 3-command setup, ~30 seconds.)

That's it. No other config needed.

Step 2: Run the audit

cd skills/gsc-lighthouse
python audit.py --site "sc-domain:example.com"

Add --no-lighthouse to skip the PSI step. Add --top N to audit a different number of pages (default 10).

The script writes a JSON dump to ./out/audit-<date>.json and prints the structured report to stdout.

Step 3: Report

Read audit.py's stdout straight back to the user. Don't reformat unless they ask; the script's output is already structured for direct read.

If the user wants a TL;DR, summarize in this shape:

## GSC + Lighthouse: {today}

Sitemap:        {N URLs, errors/warnings}
Indexing:       {indexed} / {total}
Search (28d):   {clicks}, {±%} vs prior 28d
Lighthouse:     median perf {score}, median LCP {seconds}

Top 3 fixes (impact-ordered):
1. {theme}, {N pages affected}, est. {savings}
2. ...
3. ...

Bottom line: {one sentence}