# Lighthouse

> Lighthouse audit + improvement loop until targets met. Triggers "lighthouse", "performance audit", "page speed", "improve scores", "LCP", "CLS", "INP", "core web vitals".

- **Type:** Skill
- **Install:** `agentstack add skill-darkroomengineering-cc-settings-lighthouse`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [darkroomengineering](https://agentstack.voostack.com/s/darkroomengineering)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [darkroomengineering](https://github.com/darkroomengineering)
- **Source:** https://github.com/darkroomengineering/cc-settings/tree/main/skills/lighthouse

## Install

```sh
agentstack add skill-darkroomengineering-cc-settings-lighthouse
```

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

## About

# Lighthouse Optimization Loop

**Method:** 3 mobile + 3 desktop runs per audit, averaged for reliability. After each code change, re-audit AND visually verify the page with chrome-devtools MCP to catch regressions.

---

## Setup

1. **Parse URL** from `$ARGUMENTS`. If no URL, ask the user. Default: `http://localhost:3000`

2. **Verify prerequisites:**
   ```bash
   lighthouse --version    # CLI must be installed for the batched 3x3 protocol
   ```
   If lighthouse is missing: `npm install -g lighthouse`
   The chrome-devtools MCP is shipped by default; if missing, see `mcp-configs/recommended.json`.

3. **Create results directory:**
   ```bash
   mkdir -p ~/.claude/tmp/lighthouse
   ```

4. **Take baseline screenshots** before any changes:
   - `mcp__chrome-devtools__navigate_page` (type: "url", url: ``)
   - `mcp__chrome-devtools__take_screenshot`

   Describe the current layout, key elements, and visual state. This is your **visual baseline** — you will compare against it after every change to catch regressions.

5. **Confirm with user:** Show the URL, confirm the dev server is running, ask if there are specific pages or routes to audit beyond the main URL.

---

## Audit Protocol

Each audit consists of **3 mobile + 3 desktop runs**, averaged per category.

### Run the audits

```bash
# Mobile runs (Lighthouse default is mobile)
for i in 1 2 3; do
  lighthouse  \
    --output=json \
    --output-path=~/.claude/tmp/lighthouse/mobile-$i.json \
    --chrome-flags="--headless --no-sandbox" \
    --only-categories=performance,accessibility,best-practices,seo \
    --quiet \
    2>/dev/null
done

# Desktop runs
for i in 1 2 3; do
  lighthouse  \
    --output=json \
    --output-path=~/.claude/tmp/lighthouse/desktop-$i.json \
    --chrome-flags="--headless --no-sandbox" \
    --preset=desktop \
    --only-categories=performance,accessibility,best-practices,seo \
    --quiet \
    2>/dev/null
done
```

### Extract scores

For each JSON result file:
```bash
cat ~/.claude/tmp/lighthouse/mobile-1.json | \
  jq '{
    performance: (.categories.performance.score * 100),
    accessibility: (.categories.accessibility.score * 100),
    bestPractices: (.categories["best-practices"].score * 100),
    seo: (.categories.seo.score * 100)
  }'
```

### Compute averages

Average the 3 runs per category for both mobile and desktop. Report as:

```
## Audit Results

| Category | Mobile (avg) | Desktop (avg) |
|----------|-------------|---------------|
| Performance | XX | XX |
| Accessibility | XX | XX |
| Best Practices | XX | XX |
| SEO | XX | XX |
```

### Extract failing audits

From the JSON, find specific audits that failed or scored poorly:
```bash
cat ~/.claude/tmp/lighthouse/mobile-1.json | \
  jq '.audits | to_entries[] | select(.value.score != null and .value.score  **Autonomous mode:** to drive this loop turn-by-turn without re-prompting, set
> `/goal mobile and desktop scores in all four categories meet their targets, or stop after 20 rounds`.
> A goal evaluator (Haiku by default) reads the audit table after each turn and decides whether to continue.
> See [/goal docs](https://code.claude.com/docs/en/goal).

```
LOOP until all scores >= 90 or user interrupts:

  1. IDENTIFY the lowest-scoring category and its top failing audits
     - Read the Lighthouse audit details for specific recommendations
     - Cross-reference with the project's performance rules

  2. PLAN one targeted fix
     - Focus on the highest-impact failing audit
     - One fix at a time — never batch multiple unrelated changes
     - Common fixes by audit:
       • render-blocking-resources → async/defer scripts, inline critical CSS
       • largest-contentful-paint → priority attribute, preload, optimize image
       • cumulative-layout-shift → explicit dimensions, font-display
       • unused-javascript → dynamic imports, code splitting
       • uses-responsive-images → srcSet + sizes, `next/image` (satus) or ``/`vite-imagetools` (novus), proper dimensions
       • uses-text-compression → verify gzip/brotli enabled
       • image-size-responsive → width/height attributes
       • unminified-javascript → check build config
       • dom-size → reduce DOM nodes, virtualize lists
       • third-party-summary → defer/lazy-load third-party scripts
       • font-display → font-display: swap or optional
       • offscreen-images → loading="lazy" (NOT on above-fold/LCP images)

  3. IMPLEMENT the fix
     - Edit the relevant source files
     - Keep changes minimal and focused

  4. VERIFY BUILD
     - Run the project build to ensure no compilation errors
     - If TypeScript project: `tsc --noEmit` first

  5. VISUAL REGRESSION CHECK
     - `mcp__chrome-devtools__navigate_page` to the same URL
     - `mcp__chrome-devtools__take_screenshot`
     - Compare against the baseline screenshot:
       • Layout intact? (same general structure, no collapsed/missing sections)
       • Content visible? (text, images, interactive elements still present)
       • Styling correct? (colors, spacing, typography not broken)
       • Functionality preserved? (interactive elements still look clickable)
     - If regression detected: REVERT the change immediately and try a different approach
     - Also check critical user flows if the change affects interactive elements:
       - `mcp__chrome-devtools__take_snapshot` (a11y tree — confirms interactive elements are present, returns `uid`s)
       - `mcp__chrome-devtools__take_screenshot` (visual verification)

  6. RE-AUDIT
     - Run full audit protocol again (3 mobile + 3 desktop)
     - Compare against previous scores

  7. LOG RESULTS
     - Append to ~/.claude/tmp/lighthouse/results.tsv:
       round	mobile_perf	desktop_perf	mobile_a11y	desktop_a11y	status	description
     - Status: "kept" (scores improved), "reverted" (regression or no improvement)

  8. REPORT
     - Show score delta: "Performance: 72 → 85 (+13)"
     - Show what was changed and why
     - Show the current failing audits for the next round

  9. CONTINUE to next round
```

---

## Visual Regression Protocol

This is the critical safety net. Performance changes MUST NOT break the UI.

### After every code change:

1. **Navigate:** `mcp__chrome-devtools__navigate_page` (type: "url", url: ``)
2. **Screenshot:** `mcp__chrome-devtools__take_screenshot`
3. **Compare** against baseline:
   - Is the page layout the same structure?
   - Are all visible elements still present?
   - Is text readable and properly styled?
   - Are images displaying correctly?
   - Are interactive elements (buttons, forms, nav) visually intact?

### Regression = immediate revert

If any visual regression is detected:
1. `git checkout -- ` to revert
2. Log status as "reverted (visual regression)" in results.tsv
3. Try an alternative approach to the same audit issue
4. NEVER accept a performance improvement that breaks the UI

### Multi-page checks

If the user specified multiple URLs/routes, check ALL of them after each change. A fix that improves the homepage but breaks a subpage is still a regression.

---

## Targets

Default targets (override by telling the agent different ones):

| Category | Mobile | Desktop |
|----------|--------|---------|
| Performance | >= 90 | >= 95 |
| Accessibility | >= 95 | >= 95 |
| Best Practices | >= 95 | >= 95 |
| SEO | >= 95 | >= 95 |

The loop continues until ALL categories on BOTH mobile and desktop meet their targets, or the user interrupts.

---

## Core Web Vitals Focus

When Performance score is low, prioritize these metrics:

| Metric | Target | What to Fix |
|--------|--------|-------------|
| LCP 
Updated: 

## Current Scores
| Category | Mobile | Desktop | Target | Status |
|----------|--------|---------|--------|--------|
| Performance | XX | XX | 90/95 | pass/fail |
| Accessibility | XX | XX | 95/95 | pass/fail |
| Best Practices | XX | XX | 95/95 | pass/fail |
| SEO | XX | XX | 95/95 | pass/fail |

## Progress (baseline → current)
| Category | Mobile | Desktop |
|----------|--------|---------|
| Performance | 62 → 91 (+29) | 78 → 96 (+18) |
| ... |

## Changes Applied
| Round | Fix | Mobile Perf Delta | Visual QA |
|-------|-----|-------------------|-----------|
| 1 | Added priority to hero image | +12 | pass |
| 2 | Deferred analytics script | +8 | pass |
| 3 | Added font-display: swap | +3 | pass |

## Remaining Issues
Top failing audits still to address...
```

---

## Completion

When all targets are met:
1. Print final score summary with deltas from baseline
2. List all changes made (files modified and why)
3. Suggest running a final full visual QA: `/qa `
4. Do NOT auto-commit — let the user review the changes first

## Source & license

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

- **Author:** [darkroomengineering](https://github.com/darkroomengineering)
- **Source:** [darkroomengineering/cc-settings](https://github.com/darkroomengineering/cc-settings)
- **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:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **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-darkroomengineering-cc-settings-lighthouse
- Seller: https://agentstack.voostack.com/s/darkroomengineering
- 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%.