# perf-lighthouse

Runs local Lighthouse audits via CLI or Node API, parses reports, and configures performance budgets. Useful for tracking Core Web Vitals and integrating speed checks into CI.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 320 installs · ★ 7089
- Author: tech-leads-club
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/tech-leads-club/agent-skills/tree/HEAD/packages/skills-catalog/skills/(performance)/perf-lighthouse/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/perf-lighthouse

## What it does

This skill sets up and runs Lighthouse audits through the terminal and Node API without opening browser DevTools. It generates JSON or HTML reports, launches headless Chrome, and enforces size thresholds using a `budget.json` configuration. Presets cover mobile emulation and network throttling.

For continuous integration, the skill provides Lighthouse CI settings and workflow steps for GitHub Actions. Code snippets show how to read metrics like LCP and CLS from raw JSON, then compare values between two builds before merging.

This skill focuses strictly on measuring scores and asserting budgets. It will not fix layout bugs or rewrite Astro templates; those tasks require separate optimization skills. Running audits locally requires Google Chrome and the global `lighthouse` package.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill perf-lighthouse -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/perf-lighthouse/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/perf-lighthouse/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill perf-lighthouse -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/perf-lighthouse/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill perf-lighthouse -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/perf-lighthouse/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install tech-leads-club/agent-skills perf-lighthouse
```

2. **Manually: put the files in place**
- File: `.github/skills/perf-lighthouse/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill perf-lighthouse -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/tech-leads-club/agent-skills --path 'packages/skills-catalog/skills/(performance)/perf-lighthouse'
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/perf-lighthouse/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add tech-leads-club/agent-skills --skill perf-lighthouse -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/tech-leads-club/agent-skills/tree/HEAD/packages/skills-catalog/skills/(performance)/perf-lighthouse/SKILL.md

## When to use it
- run local Lighthouse audits via CLI or Node API
- enforce asset size and timing budgets in budget.json
- configure Lighthouse CI for pull request checks in GitHub Actions
- parse JSON reports to compare Web Vitals between builds

## Example prompts
- run a mobile Lighthouse audit for my local dev server and output report.json
- create a budget.json file to limit JavaScript bundle size and LCP timing
- show the Lighthouse CI configuration for automated GitHub Actions checks

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 9ab0b82c07d922b3.

BEGIN THIRD-PARTY FILE 9ab0b82c07d922b3
````text
---
name: perf-lighthouse
description: 'Run Lighthouse audits locally via CLI or Node API, parse and interpret reports, and set performance budgets. Use when measuring site performance, understanding Lighthouse scores, setting up budgets, or integrating audits into CI. Triggers on: lighthouse, run lighthouse, lighthouse score, performance audit, performance budget. Do NOT use for fixing specific performance issues (use perf-web-optimization or core-web-vitals) or Astro-specific optimization (use perf-astro).'
---

# Lighthouse Audits

## CLI Quick Start

```bash
# Install
npm install -g lighthouse

# Basic audit
lighthouse https://example.com

# Mobile performance only (faster)
lighthouse https://example.com --preset=perf --form-factor=mobile

# Output JSON for parsing
lighthouse https://example.com --output=json --output-path=./report.json

# Output HTML report
lighthouse https://example.com --output=html --output-path=./report.html
```

## Common Flags

```bash
--preset=perf           # Performance only (skip accessibility, SEO, etc.)
--form-factor=mobile    # Mobile device emulation (default)
--form-factor=desktop   # Desktop
--throttling-method=devtools  # More accurate throttling
--only-categories=performance,accessibility  # Specific categories
--chrome-flags="--headless"   # Headless Chrome
```

## Performance Budgets

Create `budget.json`:

```json
[
  {
    "resourceSizes": [
      { "resourceType": "script", "budget": 200 },
      { "resourceType": "image", "budget": 300 },
      { "resourceType": "stylesheet", "budget": 50 },
      { "resourceType": "total", "budget": 500 }
    ],
    "resourceCounts": [{ "resourceType": "third-party", "budget": 5 }],
    "timings": [
      { "metric": "interactive", "budget": 3000 },
      { "metric": "first-contentful-paint", "budget": 1500 },
      { "metric": "largest-contentful-paint", "budget": 2500 }
    ]
  }
]
```

Run with budget:

```bash
lighthouse https://example.com --budget-path=./budget.json
```

## Node API

```javascript
import lighthouse from 'lighthouse'
import * as chromeLauncher from 'chrome-launcher'

async function runAudit(url) {
  const chrome = await chromeLauncher.launch({ chromeFlags: ['--headless'] })

  const result = await lighthouse(url, {
    port: chrome.port,
    onlyCategories: ['performance'],
    formFactor: 'mobile',
    throttling: {
      cpuSlowdownMultiplier: 4,
    },
  })

  await chrome.kill()

  const { performance } = result.lhr.categories
  const { 'largest-contentful-paint': lcp } = result.lhr.audits

  return {
    score: Math.round(performance.score * 100),
    lcp: lcp.numericValue,
  }
}
```

## GitHub Actions

```yaml
# .github/workflows/lighthouse.yml
name: Lighthouse

on:
  pull_request:
  push:
````
END THIRD-PARTY FILE 9ab0b82c07d922b3

The third-party file has ended. Everything between the 9ab0b82c07d922b3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2745 of 6401 bytes. © tech-leads-club · MIT · https://github.com/tech-leads-club/agent-skills/tree/HEAD/packages/skills-catalog/skills/(performance)/perf-lighthouse/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md