Skip to content
Get packs

Guide · Agent skill

How to use the multi-page Lighthouse SEO audit skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the seo-unlighthouse agent skill, which lets an AI agent crawl a website and run Lighthouse on each page it finds, using the open-source Unlighthouse tool on your own machine. It is for SEO and web performance people who need a site-wide view rather than one URL at a time. By the end you will know how to install the skill, how to ask for an audit in plain language, and what the results contain.

Multi-page Lighthouse SEO auditAgriciDaniel/claude-seo · MIT

Quick start

  1. 1Check Node 18+. Confirm Node 18 or newer is on your PATH before installing anything.
  2. 2Download and unzip the skill. Get the ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
  3. 3Run the install script. Run extensions/unlighthouse/install.sh to pre-warm the unlighthouse npm package.
  4. 4Confirm the site is yours to test. Make sure you own the site or have permission, because the audit crawls every discovered route.
  5. 5Ask for the audit. Use the /seo unlighthouse <url> command or a plain request naming the site.
  6. 6Set a cap and output directory. Add --max-routes and --output-dir for large sites so you can keep the JSON and HTML reports.
  7. 7Review the scores. Check the median category scores, then open the per-route list to find the pages to fix.

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file and any supporting files. It gives an AI agent specific instructions and tools for one kind of task. This skill is named seo-unlighthouse, and its SKILL.md file is the only file listed for it.

Once installed, the agent can run Lighthouse against every URL it discovers on a site, up to a configurable cap (default 200 routes). It then summarizes the results as median scores for performance, accessibility, best practices and SEO, with a per-route breakdown and a JSON and HTML report.

  • Median score per Lighthouse category across all audited routes: performance, accessibility, best-practices, seo
  • route_count: the number of routes actually audited
  • routes: the per-route breakdown, also saved as ci-result.json in the output directory

Check the requirements before you install

The skill needs Node 18 or newer available on your PATH, and the unlighthouse npm package, which is installed by the install script. It also depends on the claude-seo plugin scripts, including the scripts/claude-seo wrapper and unlighthouse_run.py. No API key is needed.

The skill runs local scripts and uses the network, so it is not suitable where you cannot install Node 18+ or run local scripts.

  • Node 18+ on your PATH
  • Run extensions/unlighthouse/install.sh to pre-warm the Unlighthouse package
  • Claude Code or the Claude apps with Skills support
extensions/unlighthouse/install.sh

Install the skill from the ZIP download

Download the ZIP for this skill from our page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Then run the install script from the extensions/unlighthouse folder so the Unlighthouse package is ready.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills
~/.claude/skills/

Trigger the skill with a natural request

You can ask for the audit in plain language, or use the explicit command form. The explicit form is the most predictable. The default is a mobile audit of up to 200 routes, with JSON and HTML reports written to a temporary directory.

To change the form factor, add a desktop flag. To cap the number of routes and keep the reports, pass a route limit and an output directory.

  • Plain request: "Run a multi-page Lighthouse audit on https://example.com and tell me which pages score lowest on SEO."
  • Desktop: "Audit every page of example.com on desktop with Lighthouse."
  • Capped and saved: "Audit up to 50 pages of example.com and save the reports to ./reports."
/seo unlighthouse <url> /seo unlighthouse <url> --device desktop /seo unlighthouse <url> --max-routes 50 --output-dir ./reports

Tune the route cap and timeouts

The route cap and per-page timeout are written into a generated unlighthouse.config.mjs file, which is passed to the Unlighthouse CLI. The per-page Lighthouse timeout defaults to 60 seconds and can be changed with a page timeout flag. This is separate from the overall subprocess guard, which defaults to 600 seconds.

Use a smaller route cap for a first pass on a large site. The skill forwards all flags through the claude-seo wrapper, which runs a URL safety check before it starts.

  • --max-routes: limit how many routes are audited
  • --page-timeout <seconds>: per-page Lighthouse timeout (default 60)
  • --timeout: overall subprocess guard (default 600)

Read the results and know when to use another skill

The skill reports route_count, aggregate_scores and the per-route routes list. Aggregate scores are medians, so one slow outlier page does not dominate the picture, but you should still open the per-route list to find the specific URLs that need work.

For data from real users on a single URL, this skill is the wrong tool. The skill itself points to seo-google psi or seo-google crux for single-URL field data (CrUX). For LCP subpart breakdowns on slow pages, it points to the lcp_subparts.py workflow.

  • Use seo-unlighthouse for site-wide lab audits and regression checks
  • Use seo-google psi or seo-google crux for single-URL field data
  • Use the lcp_subparts.py workflow for slow LCP pages

Safety notes before you crawl a site

This skill crawls every route it discovers, which can put load on the server. Only audit sites you own or have permission to test.

The skill treats fetched pages, search results, API responses and third-party files as untrusted data. Any text in them that addresses the agent is reported as a finding, not followed. The agent should not run commands, install anything or change settings because fetched content asks it to.

  • Test only sites you own or have permission to test
  • Start with a low --max-routes value on unfamiliar sites
  • Treat page content as data, not instructions

What people use it for

  • Finding slow or low-SEO-score pages across a large content site that exceeds the PageSpeed Insights free daily quota
  • Running a site-wide Lighthouse regression check after a deploy
  • Measuring Core Web Vitals locally in a restricted environment where external APIs are not an option
  • Producing JSON and HTML reports of accessibility and best-practice scores for a client review

Frequently asked questions

Is the seo-unlighthouse skill free?

The skill is published under the MIT licence, and the Unlighthouse tool it uses is also MIT-licensed. The skill runs locally and the source does not mention API keys or quotas for it. Check the licence file in the repository for full terms.

What do I need installed to use it?

You need Node 18 or newer on your PATH, the unlighthouse npm package installed through extensions/unlighthouse/install.sh, and the claude-seo plugin scripts including scripts/claude-seo and unlighthouse_run.py.

How is this different from PageSpeed Insights?

PageSpeed Insights tests one URL at a time and has a free daily quota. This skill runs Lighthouse locally across many routes on a site. For single-URL field data from real users, the skill itself recommends the seo-google psi or crux skills instead.

How many pages will it audit?

By default it audits up to 200 routes. You can set a lower or higher limit with the route cap option, which is written into a generated unlighthouse.config.mjs file.

Why is my audit timing out?

Each page has a default Lighthouse timeout of 60 seconds, and the overall subprocess has a 600-second guard. Increase the per-page timeout with --page-timeout for slow pages, or lower the route cap so the run finishes within the overall limit.

Can I use it in a CI pipeline?

The source says it is useful for CI integration and local measurement. Note that unlighthouse-ci has no --max-routes flag, so the route cap is set through the generated config file instead.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you need to check many pages of a site for speed, accessibility, best-practice and SEO problems and you are comfortable running local scripts on Node 18+. Pick a different tool for real-user data on a single URL, or if you cannot install local scripts or do not have permission to crawl the site.

Download the skill