SEO Validate

/seo-validate — SEO Validation Scanner

$ARGUMENTS

Scan a codebase for SEO issues using pattern-matching heuristics. Detects W3C/HTML violations, meta tag gaps, structured data problems, hreflang errors, Core Web Vitals risks (LCP/INP/CLS), resource-hint misuse, above-the-fold anti-patterns, GEO gaps (chunk architecture, hedging language, decision frameworks, semantic triples, freshness), topical authority gaps (pillar/cluster structure, orphan pages, cannibalization), SPA/CSR/SSG crawlability problems, technical SEO misconfigurations, and accessibility-for-SEO issues. Read-only — never modifies files.

Standards basis: W3C HTML5 Recommendation, W3C WCAG 2.2, Schema.org vocabulary, IETF RFC 5646 (BCP 47 language tags) for hreflang, web.dev Core Web Vitals thresholds (LCP <2.5s, INP <200ms, CLS <0.1), Google Search Central crawlability guidelines, and emerging GEO (Generative Engine Optimization) practices.

Usage

/seo-validate                                # Scan full project, auto-detect framework
/seo-validate src/                           # Scan specific path
/seo-validate --scope rendering              # Only SPA/CSR/SSG crawlability checks
/seo-validate --scope performance            # Only Core Web Vitals static signals
/seo-validate --scope geo                    # Only GEO (Generative Engine Optimization)
/seo-validate --scope topical               # Only topical authority and cluster architecture
/seo-validate --severity high                # Filter to HIGH findings only
/seo-validate --framework next               # Force framework (skip auto-detection)
/seo-validate --rendering csr                # Force rendering-mode interpretation
/seo-validate --output json                  # Structured JSON output for CI integration

Scopes:

• full (default) — all 10 categories
• technical — HTML semantics, hreflang, CWV, rendering, technical SEO (categories 1, 4, 5, 7, 8)
• content — meta/OG, structured data, GEO, a11y-for-SEO (categories 2, 3, 6, 9)
• performance — only CWV static signals (category 5)
• geo — only GEO / citability checks (category 6)
• rendering — only category 7 (SPA/CSR/SSG crawlability) — useful for migration audits
• topical — only topical authority and cluster architecture (category 10)

Severity filtering: --severity high shows only HIGH, --severity warn shows HIGH+WARN, --severity info shows all. Default: all.

What This Command Does

1. Detect framework and rendering mode from package.json, config files, and entry HTML.
2. Run the scanner script for a deterministic baseline over 8 of the 10 categories.
3. Extend the scan by hand using Grep/Glob/Read against framework-aware patterns for everything the script does not cover.
4. Interpret findings with specific fix suggestions tied to the detected framework.
5. Report findings with file paths, line numbers, severity, confidence, and standards citations.

Steps

Step 1: Detect Framework & Rendering Mode

Run detection before scanning so category patterns can adapt. Detection order:

1. Read package.json (if present) and inspect dependencies + devDependencies:

2. Read config files to refine:

   • next.config.* — check output: 'export' (forces SSG), images, i18n settings.
   • nuxt.config.* — check ssr: false, generate blocks (SSG export).
   • astro.config.* — check output: 'server'|'static'|'hybrid' and prerender directives.
   • gatsby-config.* — plugin list (gatsby-plugin-react-helmet, gatsby-plugin-sitemap).
   • svelte.config.* — adapter choice (static, node, vercel).
   • vite.config.* + package.json scripts — look for vite-plugin-ssr, vite-plugin-prerender.
   • angular.json — look for SSR builder config.

3. Read entry HTML (public/index.html, index.html, app/layout.tsx, src/app.html, etc.) to confirm whether meaningful content is prerendered or only a mount point (<div id="root"></div>).

4. Override precedence: --framework and --rendering flags override detection.

Report the detected framework and rendering mode in the Summary table.

Step 2: Run the Scanner Script

python3 ${CLAUDE_SKILL_DIR}/scripts/seo-scanner.py [path] [--output json|text]

Deterministic checks over meta tags, heading order, image alt, JSON-LD, hreflang, robots.txt, sitemap, Core Web Vitals signals and llms.txt. No framework awareness — it reads files, not build config. Categories 7 and 10 are not touched.

Step 3: Extend the Scan by Hand

Read reference/scanner-categories.md in full, then work every category in --scope with Grep (regex across files) and Read (config parsing / ordered checks), skipping only what Step 2 already reported. Patterns are framework-aware — use the framework detected in Step 1 to select the right rule set.

Categories 7 (Rendering Mode & Crawlability) and 10 (Topical Authority) get no help from the script. Run them in full or say in the report that you did not.

Step 4: Interpret and Enrich

For each finding:

1. Read the flagged file/lines to confirm the match is real (not a comment, not a type-only reference).
2. Add a specific fix tied to the framework (e.g., "use next/image with priority prop" vs. "add <link rel="preload" as="image"> to <head>").
3. Mark confidence: definitive for regex matches against known-bad patterns, heuristic for co-occurrence / absence checks.
4. Skip false positives when context shows the concern is addressed elsewhere (e.g., meta tags set in a layout file the route inherits from).

Step 5: Report

Present findings sorted by severity (HIGH → WARN → INFO), then by file path. State which findings came from the script and which from the manual pass, and name any category you did not complete.

Scanner Reference

scripts/seo-scanner.py gives a deterministic baseline over 8 of the 10 categories. The full pattern tables, per-framework rules and standards citations live in reference/scanner-categories.md.

Categories 7 and 10 have no script coverage at all — they are entirely manual, and skipping them is the most likely way this skill under-reports.

Output Format

## SEO Validation Report

### Summary
| Metric | Value |
|--------|-------|
| Scope | full / technical / content / performance / geo / rendering / topical |
| Framework detected | next / nuxt / astro / gatsby / sveltekit / remix / angular / vue / react-spa / vite-spa / cra / static |
| Rendering mode | csr / ssr / ssg / isr / hybrid |
| Files scanned | N |
| Public routes found | N |
| Routes with prerendering | N of N |
| Findings: HIGH | N |
| Findings: WARN | N |
| Findings: INFO | N |

### Findings

#### [HIGH] app/layout.tsx:12
Category: HTML Semantics & W3C
Confidence: definitive
Pattern: `<html>` element missing `lang` attribute
W3C Rule: HTML5 §3.2.6
Fix: Add `lang="en"` (or appropriate BCP 47 code) to the `<html>` element.
See: reference/w3c-guidelines.md#lang-attribute

#### [HIGH] components/HomeHero.tsx:24
Category: Core Web Vitals (LCP)
Confidence: definitive
Pattern: Above-the-fold `<img>` with `loading="lazy"`
Rule: LCP anti-pattern — lazy loading the LCP element delays it
Fix: Remove `loading="lazy"`, add `fetchpriority="high"`. For Next.js use `<Image priority />`.
See: reference/core-web-vitals.md#above-the-fold

#### [HIGH] src/App.tsx:1
Category: Rendering Mode & SPA Crawlability
Confidence: definitive
Pattern: CSR-only React app (Vite) with no prerender plugin
Rule: Content-site SPAs without SSR/SSG are invisible to most crawlers
Fix: Add `vite-plugin-ssr` or migrate to Next.js/Remix; OR add `react-snap` for build-time prerender.
See: reference/spa-ssg-patterns.md#react-spa-migration

Confidence values:

• definitive — regex match against a known-bad pattern with high precision.
• heuristic — co-occurrence / absence / ordering / above-the-fold inference — may be false positive.

Exit codes (when --output json):

• 0 — no HIGH findings.
• 1 — one or more HIGH findings.