Lighthouse Audit Skill

A Skill packages up a recurring workflow: instructions, plus any scripts it needs, so Claude Code runs it the same way every time instead of reinventing the approach. This one automates the "why is my site slow / scoring badly" request end to end.

What it does

1. Resolves the target. If you already have Lighthouse JSON reports, it skips straight to summarizing them. Otherwise it asks for a URL, checks that it responds, and warns you when you point it at a dev server, since unminified code skews the performance numbers.
2. Runs Lighthouse twice against the URL: mobile (throttled) and desktop, covering performance, accessibility, best practices, SEO and agentic browsing. The gap between the two numbers is itself a diagnostic signal.
3. Summarizes the raw JSON reports (often 10,000+ lines each) with a bundled Node script, so the agent's context goes to analysis and the raw data stays on disk. A --full pass on the worst report adds the LCP element and phase breakdown, CLS culprits, render-blocking requests and unused JS per file.
4. Traces every finding back to the actual source in your codebase: a specific import, an unsized hero image, a render-blocking script. A reference file maps each finding type to where it usually lives in Next.js, Gatsby, Vite SPAs, Astro and friends, and static sites. Deliberate tradeoffs like analytics or consent tools get marked "not fixing" with a reason.
5. Writes lighthouse-fix-plan.md at the repo root from a bundled template, ordered by real impact, with file and line references for each fix.
6. Asks whether to fix now or later, and never edits source without that answer. When fixing, it verifies each change with the project's own typecheck, lint, test and build scripts, then re-runs both audits and compares the tables.

<!-- diagram: flow-lighthouse-audit -->
graph TD
    R[Resolve target] --> Q{Reports provided?}
    Q -- No --> A[Run Lighthouse: mobile + desktop]
    Q -- Yes --> B
    A --> B[Summarize reports with bundled script]
    B --> C[Diagnose each finding against the project source]
    C --> D[Write prioritized fix plan]
    D --> E{Fix now or later?}
    E -- Now --> F[Work through findings by severity]
    F --> H[Verify with project scripts, re-run audits]
    E -- Later --> G[Plan file is the handoff artifact]

Why a skill instead of a one-off prompt

The same audit gets asked for repeatedly, by different people, months apart. A skill means the process doesn't have to be re-explained or re-discovered each time: run both form factors, summarize instead of reading raw, verify against source, write a structured plan. It's version-controlled like any other project asset, so improvements to the workflow benefit every future audit.

Prerequisites

• Lighthouse CLI, ideally installed globally with npm install -g lighthouse. If it's missing, the skill asks before falling back to npx -y lighthouse, since that downloads the package.
• Google Chrome or Chromium, which Lighthouse drives headless to load the page.
• Node.js, for the bundled summarize-report.mjs script. It uses only built-in modules, so there's nothing to install.
• A reachable URL: a deployed page, or a local production build (build then start/preview). A dev server works but gives misleading performance numbers. Existing Lighthouse JSON reports also work in place of a URL.

What's inside

Maintained publicly in Agentry Labs, a framework-agnostic collection of reusable AI-agent components. The skill directory contains:

• SKILL.md: the instructions Claude Code follows
• scripts/summarize-report.mjs: condenses one or two raw Lighthouse JSON reports into score and metric tables, merged opportunities and failing audits, with a --full mode for diagnostic detail
• references/framework-hints.md: where each finding type usually traces to, by stack
• assets/fix-plan-template.md: the structure of the fix plan, including a "Not fixing" section so accepted tradeoffs don't get re-raised next audit
• evals/evals.json: test cases used to check the skill still behaves as expected after edits