seo-skills/seo-audit-skill: a 332-rule SEO audit CLI, Electron app and Claude Code skill

The gap seo-skills/seo-audit-skill fills

Most free SEO checkers are web pages. You paste a URL, you get a score, and the score is produced by code you cannot read, configured in ways you cannot inspect, and impossible to run inside a build pipeline. seo-skills/seo-audit-skill takes the opposite position: the audit is a local process. The repository is TypeScript, the licence is MIT, and the published package is @seomator/seo-audit, which exposes a single binary named seomator. The README describes 332 rules across 20 categories, covering technical SEO, Core Web Vitals, structured data, accessibility, security headers and what it calls AI/GEO search readiness.

The audience is narrower than the rule count suggests. This is for engineers who already know what a canonical tag is and want the check to run in CI rather than in a browser tab. It is also for people working inside an AI coding agent: the repository ships a SKILL.md and a skill/ directory, and the README lists a Claude Code skill alongside the CLI and an Electron desktop app as three delivery mechanisms for the same rule set. If you want a marketing dashboard with historical trend lines and email digests, nothing in the README describes that.

How the audit actually runs: Playwright, raw DOM, and per-asset checks

The mechanism is a render-then-inspect loop. The CLI drives a browser through Playwright to measure Core Web Vitals, and the README states that the tool automatically uses your system Chrome, Chromium or Edge, so no separate browser download is needed if Chrome is already present. That is a real constraint disguised as a convenience: the numbers you get are the numbers your installed browser produces, not a pinned headless build.

Two design choices are worth calling out. First, JavaScript rendering analysis compares the raw DOM against the rendered DOM, which is the only honest way to audit a single-page application, because a fetch of the HTML source tells you almost nothing about what a crawler eventually sees. Second, the tool performs per-asset checks on every subresource loaded during render: cache policy, text compression, image sizing and redirect chains. That is a much finer grain than the usual page-level summary, and it is where a lot of real performance problems live.

State lives in SQLite. Audits are stored in ~/.seomator/audits.db by default, and the README says that file is what seomator report, seomator compare and the desktop app read. Crawl data is compressed and audit history persists between runs, which is what makes score history per domain possible in the Electron app. The flip side is that the CLI is stateful on your machine: two engineers running the same command on the same site are not looking at the same database. The README documents a --no-save flag to keep an audit out of your history, which is the escape hatch for CI runners.

Installing seo-skills/seo-audit-skill and running a first audit

The README recommends a global npm install. The package requires Node, and the npm badge in the README points at a Node version constraint, so check that before installing.

npm install -g @seomator/seo-audit
seomator audit https://example.com

The first command installs the seomator binary globally. The second runs a single-page audit with the default console output format and prints a prioritised report. If you have Chrome installed, Core Web Vitals are measured automatically; if you do not, the README's note implies you need one of Chrome, Chromium or Edge present.

Core Web Vitals measurement is the slow part, so the README offers a way to skip it when you only care about markup and headers:

seomator audit https://example.com --no-cwv

For a multi-page audit, enable crawl mode. The README's example caps the crawl at 20 pages, and the defaults are 10 pages at concurrency 3 with a 30000 ms timeout:

seomator audit https://example.com --crawl --max-pages 20

To feed the result into an agent, switch the format to llm and pipe it. The README gives this exact pipeline:

seomator audit https://example.com --format llm --no-cwv | claude "analyze and prioritize fixes"

The llm format is one of five: console, json, html, markdown and llm. For CI, json with an output path is the practical choice, since the README lists exit codes and JSON output as the CI/CD integration points.

What the 332 rules do not tell you

The headline number is the weakest part of the pitch. The README does not break the 332 rules down per category, so you cannot tell in advance whether accessibility is 80 rules or 8, and you cannot tell which of the 20 categories are thin. If your audit needs to satisfy a specific external standard, you have to run it and read the output rather than trust the total.

The more interesting honesty is in the reporting layer. The README states that unmeasurable checks report as "not measured" instead of fake passes. That is a deliberate refusal to inflate a score, and it is the right call, but it also means a clean-looking report can contain holes. Read the not-measured entries before you read the score.

INP deserves separate scrutiny. The README describes --simulate-interaction as scrolling and clicking the page so INP can be measured, and it explicitly says the result is reported as synthetic and unscored. So the tool will not give you a real Interaction to Next Paint number from a synthetic session, and it says so. If INP is your blocking metric, this is not the measurement source; it is a signal that a page is worth measuring properly with field data.

There is also a rendering cost. Comparing raw and rendered DOM plus checking every subresource means each audited page is loaded in a real browser. On a site with heavy third-party scripts, a 50-page crawl at default concurrency will take a while, and the README's timeout default of 30000 ms per request is the knob you will reach for first.

seo-skills/seo-audit-skill versus Lighthouse CI

The obvious comparison is Lighthouse, usually run through Lighthouse CI. Both drive a real browser and both produce a score, but they optimise for different things.

Lighthouse is a fixed set of performance, accessibility, best-practices and SEO audits, and Lighthouse CI is built around asserting budgets and thresholds across runs in a pipeline. Its SEO category is deliberately small. seo-skills/seo-audit-skill goes the other way: the rule set is the product, and it extends into territory Lighthouse does not cover, including cross-page analysis. The README describes sitemap URLs cross-checked against status, canonical and robots.txt, canonical chains and loops, hreflang target validation and reciprocity, duplicate content and duplicate H1s, orphan and isolated pages, and inbound link quality. None of that is a single-page concern, which is why crawl mode exists.

The trade-off is maturity of the performance methodology. Lighthouse has a long, heavily documented scoring model. This project's answer to performance is Core Web Vitals measured through your system browser, plus per-asset checks, plus a JavaScript rendering comparison. That is a reasonable engineering position, and the not-measured policy is more honest than a synthetic pass, but the README does not describe a scoring model in the same depth. If your team already has Lighthouse CI budgets wired into a pipeline, adding this tool means running two browser-based audits, not replacing one.

Maintenance, licence and upgrade cost

The licence is MIT, stated in the README badge and in the LICENSE file at the repository root. That permits commercial use and modification; it also means no warranty, and the README does not describe any support arrangement. Nothing here is legal advice, so read LICENSE yourself if the distinction matters to your organisation.

The release cadence is visible and fast. v4.0.0 landed on 2026-09-04, v4.1.0 on 2026-09-05, and v5.0.0 on 2026-09-05. The v5.0.0 release title is "the score means more than it did", and v4.1.0 is titled "the config layer does what it documents". Both titles imply behaviour changes rather than pure additions, which is the upgrade cost you should budget for: a major version that changes what the score means will move your numbers even when your site has not changed. The last push to the repository was on 2026-09-05, so the project is recent rather than dormant, and it is not archived.

The configuration layer is TOML with presets and inheritance, and the CLI accepts --config <path>. The README does not document a migration path between config schema versions, so if you pin a config file and upgrade across a major version, verify the config still applies before trusting the report. For CI, pin the package version rather than installing latest, and use --no-save so the runner's ~/.seomator/audits.db does not accumulate state between jobs.

Editorial conclusion

Adopt it if you already have Chrome, Chromium or Edge installed and you want a single command that returns console, JSON, HTML, Markdown or LLM-shaped output, or if you want the same rule set callable from inside a Claude Code session. Do not adopt it as a hosted monitoring service: the CLI writes to a local SQLite file at ~/.seomator/audits.db, and the README does not document any server-side scheduling or alerting. Before you commit, verify three things on your own machine: that the browser it picks up for Core Web Vitals is the one you expect, that --simulate-interaction reports INP as synthetic and unscored rather than as a real field measurement, and that the categories you care about are among the 20 the tool ships.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. seo-skills/seo-audit-skill on GitHub