/speed-fix

Run a PageSpeed Insights audit against a URL, produce a ranked, file-linked remediation plan for the current working directory, and apply approved fixes. Covers the long tail of Lighthouse opportunities — LCP render delay, render-blocking CSS/JS, legacy polyfills, oversized images, unused JS, font loading, preconnect hygiene, third-party weight.

Usage

/speed-fix <url>                       # audit mobile, produce plan, wait for approval
/speed-fix <url> --strategy desktop    # desktop audit instead
/speed-fix <url> --strategy both       # audit both; plan from the worst-scoring audits
/speed-fix <url> --apply               # skip the approval gate, edit + rebuild + verify
/speed-fix                              # no URL → infer from repo config

API key (optional, recommended)

Set GOOGLE_PAGESPEED_API_KEY to avoid the ~1 req/s anonymous rate limit. The skill resolves the key in this order — first hit wins:

1. $GOOGLE_PAGESPEED_API_KEY in the current shell environment
2. ~/.claude/skills/speed-fix/.env — a single line GOOGLE_PAGESPEED_API_KEY=AIza...
3. anonymous (no key) — still works, just rate-limited

Get a free key at <https://console.cloud.google.com/apis/credentials> → _Create credentials_ → _API key_ → restrict to the _PageSpeed Insights API_. No quota cost for the free tier.

To use the local-file option:

echo 'GOOGLE_PAGESPEED_API_KEY=YOUR_KEY_HERE' > ~/.claude/skills/speed-fix/.env
chmod 600 ~/.claude/skills/speed-fix/.env

The file is gitignored by this repo.

Flow

When invoked, execute these steps in order. Output should be terse: one-line status per step, a full plan table at step 6, and a before/after diff at step 9.

1. Resolve the target URL

If <url> is passed, use it. Otherwise infer:

• package.json → homepage field
• next.config.* → aeo.url / metadataBase / any string literal https://...
• astro.config.* → site
• vercel.json / netlify.toml → production domain
• .env* → NEXT_PUBLIC_SITE_URL, SITE_URL, PUBLIC_URL, etc.

If multiple candidates or none, ask the user once.

2. Detect the stack

Check project root (in order; first hit wins):

State the detected stack on one line (e.g. stack: nextjs (next.config.ts)).

3. Fetch PSI

# Resolve API key: env var, then ~/.claude/skills/speed-fix/.env, else anonymous
KEY="${GOOGLE_PAGESPEED_API_KEY:-}"
ENV_FILE="$HOME/.claude/skills/speed-fix/.env"
if [ -z "$KEY" ] && [ -f "$ENV_FILE" ]; then
  KEY=$(grep -E '^GOOGLE_PAGESPEED_API_KEY=' "$ENV_FILE" | head -1 | cut -d= -f2- | tr -d '"'"'" )
fi

STRATEGIES=("mobile")        # or ("desktop") or ("mobile" "desktop") for --strategy both
HOST=$(echo "$URL" | sed -E 's|https?://||; s|/.*||')
TS=$(date +%s)
mkdir -p /tmp/speed-fix
for S in "${STRATEGIES[@]}"; do
  curl -sS --max-time 60 \
    "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=$(printf '%s' "$URL" | jq -sRr @uri)&strategy=$S&category=PERFORMANCE${KEY:+&key=$KEY}" \
    > "/tmp/speed-fix/psi-$HOST-$S-$TS.json"
done

On non-200 or missing lighthouseResult, surface the error and stop.

Print one summary line per strategy:

mobile: Perf 62 | LCP 3.9s | CLS 0.04 | TBT 680ms | TTFB 280ms

Pull from lighthouseResult.categories.performance.score (×100) and lighthouseResult.audits.metrics.details.items[0].

4. Parse audits

For each audit in lighthouseResult.audits where any of:

• score !== null && score < 0.9
• details.overallSavingsMs > 100
• details.overallSavingsBytes > 5120
• details.type === "opportunity" with non-empty items

…record { id, title, savingsMs, savingsBytes, items }. If --strategy both, merge on audit id and take the worse score.

Look up each id in audits.md. If the id isn't in the table, bucket it as investigate and include verbatim in the plan; extend audits.md opportunistically after the run.

5. Map audits to files

For each remediation, use Grep/Glob to locate the concrete files — e.g.:

Annotate each item with file:line when found. If you can't locate a clean file target, mark the item as advisory — include it in the plan but don't propose an automated edit.

6. Render the plan

Output a ranked markdown table grouped by category. Column order:

| # | audit | category | est. savings | file(s) | proposed change |

Rank primarily by savingsMs (descending), then savingsBytes. Group headings in this order: LCP critical path, Payload reduction, Images, Fonts, Third-party, Build config, Advisory.

Below the table, list explicit file edits as path:line → change, short enough to scan.

7. Gate on approval

Unless --apply, stop here:

• In plan mode: call ExitPlanMode. The plan content is the markdown from step 6.
• Outside plan mode: print the plan and ask Apply these fixes? (yes / pick / no). pick lets the user mark items to skip.

8. Apply fixes

For each approved item, perform the Edit/Write/Bash actions listed in playbooks.md under the detected stack. Rules:

• One category at a time. Apply LCP fixes, type-check, then payload, then images, etc. This makes it easy to isolate a regression to a single group.
• Never commit. Even if the prior session committed — the /speed-fix skill edits files only. User runs git commit when satisfied.
• Re-run verification commands after each group: if package.json has typecheck, run it; if it has build, run it. On failure, stop and report — do not keep applying.
• Skip anything marked `advisory`. Surface it in the final report as a follow-up.

9. Verify

Re-fetch PSI for the same strategy (or strategies). Emit a before/after line per strategy and per fixed audit:

mobile: Perf 62 → 81 | LCP 3.9s → 2.1s | TBT 680ms → 240ms
  legacy-javascript:  failed (14 KiB) → passing
  uses-responsive-images: 48 KiB → 8 KiB
  render-blocking-resources: 380 ms → 120 ms

If any audit regressed, flag it in red and do not proceed to further edits — ask the user how to handle.

10. Write the run report

Append .speed-fix/<ISO-ts>.md to the project with:

• Before/after PSI snapshot (score + CWV)
• List of applied fixes with file paths and short rationale
• List of skipped advisory items
• Raw PSI JSON path in /tmp/speed-fix/ (for later diffing)

Ensure .speed-fix/ is in .gitignore — if not, prepend it.

References

• audits.md — PSI audit id → remediation mapping. Consult this in step 4.
• playbooks.md — per-stack recipes. Consult this in steps 5 and 8.

Design notes (why this works)

• Plan-first is load-bearing. Some fixes (tightening browserslist, aliasing polyfill-module, setting experimental.inlineCss) have non-obvious blast radius. A user-reviewed plan catches mistakes the skill can't.
• Skill is prompt, not code. Claude does the work with Bash/Read/Edit. No bundled JS, no install step, no version drift.
• Stack detection is cheap but critical. A Next.js fix applied to a Vite repo will either error or silently no-op; the detection step prevents both.
• Verification closes the loop. Re-running PSI after edits is what turns this from "checklist of advice" into "measurable improvement."