/seo-validate

name: seo-validate
description: "SEO validator: meta/OG, Schema.org, hreflang, Core Web Vitals, crawlability. Triggers: SEO, meta tags, Schema.org, hreflang, LCP, INP, CLS, Core Web Vitals, sitemap, crawlability."
user-invocable: true
effort: medium
disable-model-invocation: true
context: fork
agent: seo-specialist
argument-hint: "[path] [--scope full|technical|content|performance|geo|rendering|topical] [--severity high|warn|info] [--framework auto|next|nuxt|astro|gatsby|sveltekit|remix|angular|vue|react-spa|vite-spa|cra|static] [--rendering auto|csr|ssr|ssg|isr|hybrid] [--output markdown|json]"
allowed-tools: Read, Grep, Glob, Bash

/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`:

| Deps contain | Framework | Default rendering | |--------------|-----------|-------------------| | `next` | `next` | hybrid (per-route) | | `nuxt` | `nuxt` | ssr | | `astro` | `astro` | ssg | | `gatsby` | `gatsby` | ssg | | `@sveltejs/kit` | `sveltekit` | hybrid | | `@remix-run/*` | `remix` | ssr | | `@angular/core` + `@angular/ssr` or `@nguniversal/*` | `angular` | ssr | | `@angular/core` alone | `angular` | csr (flag as SPA) | | `vue` + `nuxt` | see nuxt row | — | | `vue` without `nuxt` | `vue` | csr (flag as SPA) | | `react` + `vite` without Next/Remix | `vite-spa` | csr (flag as SPA) | | `react-scripts` | `cra` | csr (flag as SPA) | | no `package.json` OR no framework deps | `static` | static |

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](reference/scanner-categories.md) in