| name | seo-audit |
| description | Audit and fix a website's technical SEO and AI-search (GEO) readiness against Google's official guidance, page by page, ending in a computed SEO/GEO score. Use when asked to audit SEO, fix indexing or crawling problems, check canonicals/hreflang/sitemaps/structured data, diagnose why pages are not indexed or traffic dropped, prepare a site migration, or make a site visible to AI answer engines. Also use before shipping changes that touch routing, metadata, robots.txt or sitemaps. |
SEO audit and repair
You are running SEO Prompt Master. Bring every public page of the project in
the working directory into compliance with Google's documented guidance, and
prove it rather than asserting it.
Before anything else
Read docs/README.md for the map, then keep docs/ open as you work. It is the
only source of truth in this skill. If a claim about how Google behaves is
not in docs/01–docs/17, say "not covered by the knowledge base" instead of
recalling it from memory — the SEO web is full of advice that was true in 2021.
Check verticals/README.md for an overlay matching the project's industry. It
adds emphasis; it never replaces the core audit.
Two ways to learn what is wrong, and you need both
Read the code to know what the project intends. Run the tool to know what
the server actually does. They disagree more often than anyone expects, and the
gap is where the bugs live.
node tools/seo-audit.mjs --url https://the-site.example --max 40 --md seo-report.md
Zero dependencies, Node 18+. It samples across the sitemap rather than the head
of it, then checks robots.txt against RFC 9309, sitemap limits and lastmod
credibility, host consolidation, per-template soft 404s, canonical
self-reference, hreflang reciprocity across pages (a one-way set is
discarded in full), duplicate titles, streamed-metadata visibility, raw-HTML
content volume, structured-data validity, and image dimensions. It exits 1 if
any P1 is open, so it can gate a deploy.
Point it at a local build (--url http://localhost:3000) when there is no live
site yet.
Three things it deliberately cannot see, which stay your job: whether the
content is any good (docs/14), off-page authority (docs/17), and real
field CWV data, which only CrUX has (docs/05).
The workflow
Follow START.md, which holds the full phase-by-phase instructions:
| Phase | File | Output |
|---|
| 0 — Bootstrap & detect | prompts/00-bootstrap.md | Stack report |
| 1 — Discover routes | prompts/01-discover-routes.md | ROUTES-INVENTORY.md |
| 2 — Audit each page | prompts/02-audit-page.md | SEO-AUDIT-PROGRESS.md |
| 3 — Prioritise | prompts/03-prioritize-fixes.md | P1/P2/P3 backlog + baseline score |
| 4 — Fix & verify | prompts/04-apply-and-verify.md | Fixes, each with evidence |
| 5 — Live signals (optional) | prompts/05-live-signals.md | Field data, if a live URL exists |
Classify every route as public-index, public-noindex (internal search, live
tools, auth screens) or private (dashboards, admin, API). Getting this wrong
in Phase 1 makes every later phase wrong: a page being reachable is not the
same as it deserving to be indexed.
Rules that are not negotiable
- Fix shared infrastructure first. A metadata helper, the sitemap builder,
robots.txt, the i18n layer — one change there fixes hundreds of pages. Per-page
work afterwards.
- Never break the build. Typecheck, lint and build after every change. If it
fails, fix it before moving on.
- Evidence, not assertion. A page is not fixed until you have re-fetched it
and seen the change —
curl the route, grep the rendered output, or re-run
the tool. "Should now be correct" is not a result.
- Persist progress to
SEO-AUDIT-PROGRESS.md as you go. Long runs outlive
context windows; the file is what survives.
- Don't stop between phases to check in. A site with hundreds of routes is a
reason to keep working, not a reason to summarise and wait. Stop only if you
cannot access the repo or run the build, or if a finding needs a genuine
product decision ("should
/internal-tool be public at all") — ask that one
question and keep going on everything else meanwhile.
Reporting
End with the SEO Score and GEO Score from docs/11: the per-category
breakdown, the coverage status (final vs provisional), and the caveat that
off-page factors are out of scope. A bare number is not a report.
Before calling a score final, re-verify a random ~15% of everything already
marked done by re-reading the actual output, not your notes. Optimistic
copy-paste ticks are the failure mode this catches.
