/audit — Comprehensive site SEO audit

Target: $ARGUMENTS

Load first: ${CLAUDE_PLUGIN_ROOT}/skills/seo-fundamentals/SKILL.md (ground-truth rules) and, from ${CLAUDE_PLUGIN_ROOT}/skills/seo-fundamentals/references/: technical-seo-deep-dive.md (crawl budget, CWV, soft 404s, redirects, mobile parity, findings format), schema-markup-templates.md, international-seo.md if the site is multi-locale, navboost.md for section 7, and scoring-spec.md §4 for severity levels.

Project context: if .claude/project-context.md, .agents/project-context.md, or .agents/product-marketing-context.md exists in the working directory, read it and ask only for what it does not cover.

Inputs (ask once for what is missing)

Domain · site type (SaaS, e-commerce, content/blog, multilingual, local, marketplace) · scope (full, technical, on-page, content, international, competitive) · target keywords · 2–3 competitors (or discover via search) · locales served · known issues and recent changes (migration, traffic drop, update) · GSC/GA4 access (MCP, exports, screenshots, none). If SEO tools are connected (Ahrefs, Semrush, Similarweb, DataForSEO, GSC), pull metrics from them and cite the tool.

Tooling

• Page facts (title, meta, canonical, hreflang, robots meta, JSON-LD, headings, links, images, word count): python3 ${CLAUDE_PLUGIN_ROOT}/scripts/fetch_page.py "<url>" --json per sampled page. Text metrics: text_metrics.py --from-json.
• WebFetch only for reading rendered content — never for schema detection (it strips <script>). If fetch_page.py finds no JSON-LD, write "not detected in static HTML — verify with Rich Results Test".
• CWV: field data from PageSpeed Insights / CrUX when reachable; otherwise mark "verify in PSI".

Priority order

1 Crawlability & indexation → 2 Technical foundations → 3 International (if applicable) → 4 On-page sample → 5 Content → 6 Entity & topical authority → 7 NavBoost & engagement → 8 Links & authority → 9 Competitive position. Blocking issues (P0) surface before optimization work (P2/P3).

Sections

1. Technical

• Crawl & index: robots.txt (unintended blocks, sitemap reference); sitemap.xml (present, only canonical 200 URLs, fresh); self-referencing canonicals, no cross-locale canonical; noindex only where intended; soft 404s; redirect chains/loops (max 1 hop); one host/protocol/slash/case form.
• Performance & CWV: LCP <2.5 s, INP <200 ms, CLS <0.1, TTFB <800 ms; render-blocking resources; image formats and lazy loading; HTTPS, no mixed content.
• Mobile-first parity: same content, headings, structured data, canonical, hreflang, links as desktop; viewport meta; tap targets ≥48 px; body font ≥16 px; no horizontal scroll at 375 px; no intrusive interstitials; responsive, not m.. Check with Lighthouse mobile audit (the Mobile-Friendly Test and GSC Mobile Usability report were retired in 2023).
• Structured data: types found and validity; misalignment with visible content (→ /alignment-audit); missing opportunities (Article, Product, BreadcrumbList, Organization/LocalBusiness with sameAs). Do not recommend FAQ/HowTo for rich results.
• Architecture: click depth ≤3 for important pages; pillar → cluster hierarchy; HTML navigation; no orphans.
• Crawl budget (10K+ URLs): parameters and facets handled; infinite scroll with paginated fallback; no session IDs.

2. International (multi-locale sites)

Apply international-seo.md: self-referencing and reciprocal hreflang with valid ISO codes and x-default; hreflang targets 200/indexable/canonical-matching; every locale self-canonical; consistent locale URL strategy (no ?lang=, no IP/Accept-Language negotiation); full main-content translation; sitemap hreflang with xmlns:xhtml. Single-locale sites: skip, flag opportunities.

3. On-page sample (5–10 pages)

Homepage + 3–5 key landing pages + 2–3 recent posts. Per page: title (value, length, click quality) · meta description · H1 count and entity · H2/H3 hierarchy · entity in first 50 words · internal links and anchors · alt coverage · URL · canonical · mobile parity. Table with Status / Finding / Evidence / Fix.

4. Content

Depth vs competitors (word count is a proxy, not the goal) · freshness (12+ months untouched) · thin pages (<300 words that should be more) · duplicates and cannibalization (→ keyword-mapper agent) · gaps vs competitors · missing formats (guides, comparisons, glossaries, templates) · cluster interlinking.

5. Keywords

Apparent targets per page · keyword-to-page map and cannibalization · quick wins (positions 8–20) · high-impression low-CTR pages (GSC) · YMYL exposure.

6. Entity & topical authority

• Primary entity per key page (NER on top 10 landing pages); flag topic drift.
• Expected-entity gaps for top 10 target queries (/entity-coverage on 2–3 of them).
• siteFocusScore proxy: share of indexed pages inside the primary topic cluster (>70% strong, <40% scattered).
• Author entities: bylines with sameAs, dedicated author pages, schema.org/Person, per-author topic depth.
• Content ↔ schema alignment on 5 pages with numbers (/alignment-audit).
• Citable-passage density on 3 articles (text_metrics.py; target ≥4 per 1,000 words).

7. NavBoost & engagement

Run the seven modules from /navboost-audit where GSC/GA4 data exists (position-normalized CTR, pogo-stick proxy, engaged sessions, session duration, branded search, brand+topic queries, Knowledge Panel). Without data: list them as "verify via GSC/GA4", do not estimate.

8. Competitors

Table: content depth · publishing frequency · keyword coverage · technical score (CWV, mobile, schema) · SERP features captured · backlinks (if data) · international coverage · AI Overview citations observed — target vs each competitor, winner per row.

Site-type playbooks (apply the matching one)

• SaaS: thin feature pages; blog not linked to product pages; missing comparison/alternatives pages; no glossary or education hub; pricing page only branded.
• E-commerce: category pages with grids only; manufacturer-copied descriptions; Product schema without price/availability/rating; facet duplicates; out-of-stock handling; missing breadcrumb schema.
• Content/blog: stale posts; cannibalization; no pillars; chronological-only linking; weak author entities; schema not matching body; low passage density; scattered topics diluting focus.
• Multilingual: hreflang errors; cross-locale canonicals; thin locales; boilerplate-only translation; no x-default; IP redirects; locale hidden from URL.
• Local: inconsistent NAP; missing LocalBusiness schema with address/geo/hours; GBP; per-location pages (or city-swap duplicates); no localized content; broken map.
• Marketplace: templated vendor pages; no canonical strategy for variants; search/filter URLs flooding crawl.

Output

1. Executive summary — 3–5 sentences: biggest strength, top 3 priorities, overall health (Strong foundation / Needs work / Critical issues).
2. Findings tables grouped by section, 5-field format: Issue · Impact · Evidence (URL, script output, GSC report) · Fix · Priority (P0 blocks indexing / P1 high / P2 quick win / P3 long-term). No evidence, no finding.
3. Content gap recommendations — topic, why, format, priority, effort.
4. Action plan — Quick wins (this week, <2 h each) · Strategic (this quarter) · Roadmap (6–12 months), each with impact, effort, dependencies.
5. AI search visibility — passage density, entity coverage, content-data alignment, verified authors, original data; consider an llms.txt. Point to /citable-passage, /entity-coverage, /alignment-audit.

Tools to cite: Google Search Console, PageSpeed Insights / Lighthouse, Rich Results Test, Schema.org validator, Bing Webmaster Tools; Screaming Frog (rendering on), Ahrefs/Semrush, Sitebulb, ContentKing, Similarweb where available.

Next: /meta-tags, /topic-clusters, /internal-links, /write-seo, /score, /schema-gen, /navboost-audit.