seo-audit-skill: a Script plus LLM SEO audit that writes an HTML report per page
SEO agent skill for OpenClaw,Claude Code, and AI agents. Generate beginner SEO audits and advanced technical SEO reports for any page.
At a glance
- What is it?
- JeffLi1993/seo-audit-skill splits SEO auditing into deterministic Python checks and LLM judgement, emitting a standalone HTML report. It is best for auditing one page at a time, not for crawling a whole site.
- Who is it for?
- Adopt seo-audit-skill if you audit individual pages and want a repeatable checklist that an agent can execute without you remembering which tags to inspect. Skip it if you need a full-site crawl, historical tracking, or a report you can hand to a non-technical stakeholder without editing.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 90 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills: a checklist that an agent can actually execute
Most SEO tools sit at two extremes. A crawler like Screaming Frog or a hosted auditor will index thousands of URLs and hand you a database, which is more than you need when the question is why one landing page is not ranking. A chat prompt like "review my SEO" produces prose that varies between runs and cannot be diffed. seo-audit-skill targets the space in between: give an agent a single URL and get back a structured report covering the checks a practitioner would run by hand, with the mechanical parts done by scripts so the output is stable.
The README frames the audience as people running Claude Code, Cursor, or any runtime that supports SKILL.md. The homepage points to OpenClaw as well. That means the intended user already has an agent session open and wants the audit to happen inside it, not in a separate browser tab. The two tiers reflect two different jobs. The basic skill is described as the default, a 20-plus check report from a URL. The full skill adds PageSpeed, sitemap inventory, social tags, content quality, GSC data and competitor gap analysis. The full tier is the one that needs outside credentials.
Script plus LLM: which layer decides what
The architecture section of the README is explicit about the division of labour. Layer 1 is Python scripts handling what it calls deterministic checks: HTTP status, XML parsing, string matching. Layer 2 is the LLM handling semantic judgment: keyword intent, content quality, page type inference.
That split shows up in the directory layout. In seo-audit/scripts you get check-site.py (robots.txt plus sitemap to JSON), check-page.py (TDK, H1, canonical, slug to JSON), check-schema.py (JSON-LD extraction and validation), and fetch-page.py, described as a raw HTML fetcher with SSRF protection. The full skill swaps in a different set: check-site.py adds staging detection and sitemap inventory, check-pagespeed.py wraps the PageSpeed Insights API, check-social.py validates OG and Twitter Card tags, and check-schema.py is upgraded to cover localized schema validation.
The consequence is that the LLM never has to guess whether a title tag is 47 or 63 characters. It receives that as a number. What it does have to guess, or infer, is whether the title matches search intent. That is a reasonable boundary, and it is also the boundary where the tool's accuracy becomes hard to audit, because the deterministic half is reproducible and the semantic half is not.
What the checks actually cover, and where the line sits between tiers
The coverage tables are the most useful part of the README because they mark each check as basic or full. On the site side, the basic tier handles robots.txt with RFC 9309 group parsing, sitemap.xml validation, 404 handling (distinguishing a true 404 from a soft 404 that returns 200, and from a 301 redirect to the homepage), URL canonicalization, i18n and hreflang, JSON-LD schema, and E-E-A-T trust pages. The full tier adds sitemap URL inventory, staging subdomain indexation detection, GSC crawl status, and PageSpeed.
Two of those deserve attention. The staging check looks for public test., staging., dev., preview., beta. and uat. hosts that mirror production and may be indexable. That is a specific, findable misconfiguration, and it is the kind of thing a general-purpose crawler will not flag unless you configure it to. The hreflang check goes past presence and tests reciprocal symmetry, BCP 47 codes, x-default, default-language URL duplication, and whether canonical and hreflang agree. Those are the failure modes that actually break international sites.
On the page side, the basic tier checks URL slug, title tag length against a 50 to 60 character target, meta description against 120 to 160, single H1 with keyword match, canonical self-reference, image alt text with JS-render detection, word count against a 500-word floor, keyword placement within the first 100 body words, heading structure with an H2 target of 5 to 7, and internal links excluding nav and footer. The full tier adds OG and Twitter tags, content quality, and robots meta directives including noindex, nofollow and max-snippet. Note that robots meta is full-tier only. If a page is accidentally noindexed, the basic audit will not tell you.
Getting it running: one install command and one API key
The README gives a single installation path: npx skills add JeffLi1993/seo-audit-skill. After that, the invocation is a natural-language instruction to the agent, with the example "audit this page: https://example.com". The report lands at reports/<hostname>-audit.html for a basic audit and reports/<hostname>-full-audit.html for a full one. The README shows a worked example where auditing https://openclaw.ai produces reports/openclaw-ai-audit.html.
The full skill has one hard dependency. PageSpeed checks require a Google PageSpeed Insights API key. You set PAGESPEED_API_KEY or GOOGLE_PAGESPEED_API_KEY, or pass --api-key on the command line. The README states plainly that without a key the full audit stops and asks you to configure one. That is a deliberate stop rather than a silent skip, which is the right call: a report that quietly omits its performance section is worse than one that refuses to start.
There is no documented configuration for the basic tier, and no release has been published, so installation is from the repository rather than a versioned package. The README also suggests a second workflow after the audit: share the report with Cursor or Claude Code and have the assistant work through the findings item by item. That turns the HTML report into an input for a fix loop rather than a document you read once.
The single-page scope is a real constraint, not a footnote
The tool audits one page per invocation. The sitemap URL inventory in the full tier is the closest thing to site-wide context, and the README describes its purpose as giving you a site-level map so you can then choose representative URLs from important directories for deeper full audits. That is manual triage. Nothing in the material suggests the skill walks a sitemap and audits every URL.
This matters because the most damaging SEO problems are often site-wide and invisible from a single page. A canonical tag that points to the wrong host on every page looks fine on the one page you checked. A robots.txt disallow that blocks an entire directory will not show up in a page-level audit of a URL you reached directly. The basic tier does parse robots.txt and sitemap.xml, so it will catch some of this, but the audit's unit of analysis is still one URL.
The other limitation is the LLM layer itself. Content quality, keyword intent and page type inference are not reproducible between runs. Two audits of the same page, days apart, can produce different priority actions. For a one-off review that is acceptable. For tracking whether a fix worked, you want to compare the script JSON, not the narrative sections.
How it differs from running Lighthouse or a crawler directly
The obvious alternative for the performance half is Lighthouse itself, or the PageSpeed Insights API that check-pagespeed.py already calls. Running Lighthouse directly gives you the same scores and lab metrics, and it gives them without an agent in the loop. The difference is scope and packaging: Lighthouse answers questions about rendering and performance, while seo-audit-skill bundles that with robots.txt parsing, hreflang reciprocity, schema field validation and a priority-ordered action list in one report. If performance is your only concern, the skill is an extra layer over a tool you can run yourself.
A closer comparison is a full-site crawler such as Screaming Frog. The approaches are opposite. A crawler starts from a seed URL, follows links, and builds a table of every page it reaches, which surfaces site-wide patterns and duplicate content across templates. seo-audit-skill starts from a page you chose and reasons about that page in depth, including semantic checks a crawler cannot perform, such as whether the H1 matches search intent. Neither replaces the other. The honest framing is that the skill is for depth on a known page, and a crawler is for breadth across an unknown site.
There is also the plain-prompt alternative: ask an agent to review a page with no skill installed. That is free and requires no install, but the checks vary per run and nothing enforces that alt text or canonical tags get examined at all. The skill's value is that the script layer makes those checks mandatory and machine-readable.
Maintenance, licence and what to verify before trusting a report
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive position and it means you can vendor the scripts into an internal tool. It is not legal advice, and if you redistribute the skill inside a product you should read the licence text rather than this summary. Note that the skill shells out to the Google PageSpeed Insights API, so your use of that endpoint is governed by Google's terms, not by the MIT grant.
On maintenance, the last push recorded is 2026-06-17 and no releases were retrieved. Without tagged releases there is no version pin to hold, so if you install via npx skills add you are tracking the default branch. That is a real operational cost: a change to a check script can alter your report output with no version number to explain it. The dependency surface is small (Python scripts plus an HTTP fetch layer), which keeps the maintenance burden low, but the absence of releases means you should record the commit you installed from if you care about reproducibility.
Before trusting the output, verify the deterministic layer first. Run the basic skill against a page where you know the correct title length, canonical target and hreflang set, then open the JSON produced by check-page.py and check-schema.py and compare. If the scripts are right, the LLM's judgement sits on solid ground. If a script is wrong, no amount of semantic reasoning downstream will fix it. The second thing to verify is whether robots meta is in scope for your audit, because in the basic tier it is not.
Editorial conclusion
Adopt seo-audit-skill if you audit individual pages and want a repeatable checklist that an agent can execute without you remembering which tags to inspect. Skip it if you need a full-site crawl, historical tracking, or a report you can hand to a non-technical stakeholder without editing. Before relying on it, run the basic skill against a page whose correct answers you already know and confirm the JSON from check-page.py and check-schema.py matches, because the LLM layer can only judge what those scripts extract.
Community notes