# Speed Fix

> |

- **Type:** Skill
- **Install:** `agentstack add skill-virdis-agency-website-speed-fix-website-speed-fix`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Virdis-Agency](https://agentstack.voostack.com/s/virdis-agency)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Virdis-Agency](https://github.com/Virdis-Agency)
- **Source:** https://github.com/Virdis-Agency/website-speed-fix

## Install

```sh
agentstack add skill-virdis-agency-website-speed-fix-website-speed-fix
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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                        # audit mobile, produce plan, wait for approval
/speed-fix  --strategy desktop    # desktop audit instead
/speed-fix  --strategy both       # audit both; plan from the worst-scoring audits
/speed-fix  --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  → _Create credentials_ → _API key_ → restrict to the _PageSpeed Insights API_. No quota cost for the free tier.

To use the local-file option:
```bash
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 `` 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):

| Marker | Stack | Playbook section |
|---|---|---|
| `next.config.{ts,js,mjs}` | `nextjs` | `playbooks.md#nextjs` |
| `nuxt.config.{ts,js}` | `nuxt` | `playbooks.md#nuxt` |
| `astro.config.{ts,js,mjs}` | `astro` | `playbooks.md#astro` |
| `svelte.config.{js,ts}` | `sveltekit` | `playbooks.md#sveltekit` |
| `vite.config.{ts,js,mjs}` (and not Astro/SvelteKit) | `vite` | `playbooks.md#vite` |
| `wp-config.php` | `wordpress` | `playbooks.md#wordpress` |
| otherwise | `generic` | `playbooks.md#generic` |

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

### 3. Fetch PSI

```bash
# 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  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.:

| Audit id | Grep targets |
|---|---|
| `render-blocking-resources` | `]*src=` without `defer`/`async` |
| `legacy-javascript` | `browserslist` in `package.json`, `.browserslistrc`; `target` in `tsconfig.json`, `vite.config.*`, `next.config.*` |
| `uses-responsive-images` | `` templates |
| `third-party-facades` | script tags / dynamic imports matching known third-parties (YouTube, Intercom, Drift, HubSpot, GTM, Cal.com) |

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/.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."

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Virdis-Agency](https://github.com/Virdis-Agency)
- **Source:** [Virdis-Agency/website-speed-fix](https://github.com/Virdis-Agency/website-speed-fix)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-virdis-agency-website-speed-fix-website-speed-fix
- Seller: https://agentstack.voostack.com/s/virdis-agency
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.