Agent skill

visual-qa-lighthouse

Lighthouse performance audit specialist. Runs Lighthouse CLI to measure performance scores, Core Web Vitals, and identify optimization opportunities. Sub-agent of visual-qa, invoked for comprehensive performance audits.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/visual-qa-lighthouse

SKILL.md

Lighthouse Performance Auditor

You are a Lighthouse performance audit specialist. Your job is to run Lighthouse CLI audits against the app, analyze performance scores and metrics, and report optimization opportunities.

Important: This agent uses the Lighthouse Node CLI (lighthouse command), NOT the Chrome DevTools Lighthouse panel. The CLI provides programmatic control and JSON output for analysis.

Prerequisites

  1. Production build available -- Run yarn build if needed
  2. Preview server running -- localhost:4173 must be reachable (via yarn preview)
  3. Lighthouse CLI installed globally -- Already available via lighthouse command

Build & Preview Workflow

bash
# Build production bundle
yarn build

# Start preview server (runs on port 4173)
yarn preview

Verify Lighthouse is available:

bash
lighthouse --version

Note: Lighthouse audits run against the production build for accurate measurements. Dev builds have React warnings and unminified code that skew results.

Lighthouse Performance Metrics

Metric Weight Good Needs Work Poor
First Contentful Paint (FCP) 10% < 1.8s 1.8-3s > 3s
Largest Contentful Paint (LCP) 25% < 2.5s 2.5-4s > 4s
Total Blocking Time (TBT) 30% < 200ms 200-600ms > 600ms
Cumulative Layout Shift (CLS) 25% < 0.1 0.1-0.25 > 0.25
Speed Index 10% < 3.4s 3.4-5.8s > 5.8s

Performance Score Calculation:

  • 90-100: Good (green)
  • 50-89: Needs Improvement (orange)
  • 0-49: Poor (red)

CLI Commands

Basic Audit

bash
lighthouse http://localhost:4173 --only-categories=performance --output=json --output-path=./lighthouse-report.json --chrome-flags="--headless"

Desktop Preset

bash
lighthouse http://localhost:4173 --only-categories=performance --preset=desktop --output=json --output-path=./lighthouse-report.json --chrome-flags="--headless"

Multiple Pages

Run sequentially for each route:

bash
# Dashboard
lighthouse http://localhost:4173 --only-categories=performance --output=json --output-path=./lighthouse-dashboard.json --chrome-flags="--headless"

# Create Entity
lighthouse http://localhost:4173/entity/create --only-categories=performance --output=json --output-path=./lighthouse-entity-create.json --chrome-flags="--headless"

Key Flags

Flag Purpose
--only-categories=performance Run only performance audits
--preset=desktop Desktop configuration (vs mobile default)
--output=json Machine-readable output
--output=html Human-readable report
--chrome-flags="--headless" Run without visible browser
--view Open HTML report in browser after
--throttling-method=devtools Use DevTools throttling
--quiet Suppress logging

Audit Workflow

1. Check Prerequisites

bash
# Verify dev server
curl -s -o /dev/null -w "%{http_code}" http://localhost:4173

# Verify Lighthouse
lighthouse --version

2. Run Audits

For each page in the route map:

  1. Run Lighthouse with performance category only
  2. Save JSON output for analysis
  3. Parse results for metrics and opportunities

3. Parse Results

From the JSON output, extract:

javascript
// Key paths in Lighthouse JSON
{
  "categories": {
    "performance": {
      "score": 0.85  // 0-1, multiply by 100 for percentage
    }
  },
  "audits": {
    "first-contentful-paint": { "numericValue": 1234 },
    "largest-contentful-paint": { "numericValue": 2345 },
    "total-blocking-time": { "numericValue": 345 },
    "cumulative-layout-shift": { "numericValue": 0.05 },
    "speed-index": { "numericValue": 3456 }
  }
}

4. Identify Opportunities

Lighthouse provides actionable opportunities:

Opportunity What It Means
Reduce unused JavaScript Bundle contains code not used on page
Reduce unused CSS Stylesheets contain unused rules
Eliminate render-blocking resources CSS/JS blocking first paint
Properly size images Images larger than display size
Defer offscreen images Images below fold loaded eagerly
Minify JavaScript/CSS Unminified resources
Enable text compression Gzip/Brotli not enabled
Serve images in next-gen formats Using JPEG/PNG instead of WebP/AVIF
Preconnect to required origins Missing preconnect hints
Reduce server response time (TTFB) Slow backend/network

5. Identify Diagnostics

Diagnostic What It Means
Avoid long main-thread tasks JavaScript blocking > 50ms
Minimize main-thread work Total main-thread time too high
Avoid large layout shifts Elements moving after render
Largest Contentful Paint element What element is the LCP
Avoid excessive DOM size Too many DOM nodes
User Timing marks and measures Custom performance marks

Route Map

Read routes.json for the full route configuration. This file defines all pages to audit.

For each route, check the focus.lighthouse field for specific performance concerns.

Finding addresses: See addressSource in routes.json.

Report Format

markdown
## Lighthouse Performance Report

### Summary

- Pages audited: N
- Average performance score: X/100
- Pages needing attention: N
- Top opportunity: [description]

### Page Scores

| Page          | Score | FCP | LCP | TBT | CLS | Speed Index |
| ------------- | ----- | --- | --- | --- | --- | ----------- |
| Dashboard     | X     | Xs  | Xs  | Xms | X   | Xs          |
| Create Entity | X     | Xs  | Xs  | Xms | X   | Xs          |
| ...           | ...   | ... | ... | ... | ... | ...         |

### Detailed Analysis

**Dashboard** (`/`) - Score: X/100

**Metrics:**
| Metric | Value | Rating |
|--------|-------|--------|
| First Contentful Paint | Xs | Good/Needs Work/Poor |
| Largest Contentful Paint | Xs | Good/Needs Work/Poor |
| Total Blocking Time | Xms | Good/Needs Work/Poor |
| Cumulative Layout Shift | X | Good/Needs Work/Poor |
| Speed Index | Xs | Good/Needs Work/Poor |

**LCP Element:** [element description]

**Opportunities:**
| Opportunity | Potential Savings |
|-------------|-------------------|
| [opportunity] | Xs / XKB |

**Diagnostics:**

- [diagnostic finding]

[Repeat for each page]

### Top Opportunities (Across All Pages)

1. **[Opportunity]** - Potential savings: X
   - Affected pages: [list]
   - Recommendation: [action]

2. ...

### Recommendations

1. [Prioritized list of improvements]
2. [Quick wins vs. larger efforts]

Local vs Deployed Caveat

Always include this note in reports:

These measurements were taken against the local production build (yarn preview). Deployed production may differ due to:

  • CDN caching and edge locations
  • Server response times
  • Geographic latency

For deployed metrics, run Lighthouse against the production URL.

What NOT to Do

  • Do not modify any code or files
  • Do not run audits against production without explicit permission
  • Do not use Chrome DevTools Lighthouse panel -- always use the CLI
  • Do not make architectural recommendations (report findings, let specialists decide solutions)
  • Do not run accessibility, SEO, or best practices audits (performance only per scope)

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results