/seo-audit

name: seo-audit
description: Run SEO audit (39 rules) with AI visibility checks — GEO (20 rules for AI bot access, snippet restrictions) and AEO (4 schema checks). Auto-fix included. Use when user wants to check or improve search visibility.
argument-hint: "<url-or-directory>"
allowed-tools: Bash, Read, Edit, Grep, Glob
paths: ["**/*.html", "**/index.html", "**/*.htm"]

SEO Audit + AI Visibility

Search optimization audit with AI visibility signals. Finds issues AND fixes them.

Process

Phase 1: Scan

Run the SEO scanner on the project:

node ${CLAUDE_PLUGIN_ROOT}/tools/seo-scanner.mjs <project-directory>

Parse the JSON output for findings and scores (seo, geo, aeo).

> **Large sites:** when a site has many pages and each needs page-specific fixes, escalate to a **dynamic Workflow** (describe the audit and include the word "workflow") so the scan-then-fix-then-verify pipeline runs across pages in parallel instead of one at a time.

Phase 2: Report

Present findings grouped by category with severity:

• **SEO**: meta tags, OG tags, headings, alt text, canonical, robots.txt, sitemap
• **GEO**: structured data, llms.txt, content structure for AI
• **AEO**: FAQPage schema, speakable markup, snippet optimization

Phase 3: Fix

For each finding, apply the appropriate fix:

**SEO fixes** (use Edit tool on HTML files):

• Missing title → add `<title>` in `<head>`
• Missing meta description → add `<meta name="description" content="...">`
• Missing OG tags → generate from page content
• Missing H1 → add appropriate heading
• Missing alt text → add descriptive alt attributes
• Missing canonical → add `<link rel="canonical">`
• Missing sitemap → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/sitemap-generator.mjs <dir> <url>`
• Missing robots.txt → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/robots-generator.mjs <dir> <url>`
• Missing favicon → warn user to add one

**GEO fixes**:

• Missing llms.txt → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/llms-txt-generator.mjs <dir>`
• Missing structured data → run: `node ${CLAUDE_PLUGIN_ROOT}/tools/structured-data-generator.mjs <dir> --type=<type>`
• Improve content structure: add clear headings, FAQ sections, definitive statements

**AEO fixes**:

• Missing JSON-LD → generate appropriate schema type
• Missing FAQ schema → create FAQPage structured data from page content
• Snippet optimization → restructure key answers to 40-60 words

Phase 4: Search Engine Registration (GSC + Bing)

**Google Search Console** (requires ULTRASHIP_GSC_CREDENTIALS):

# Submit sitemap
node ${CLAUDE_PLUGIN_ROOT}/tools/gsc-client.mjs submit-sitemap <site-url> <sitemap-url>

# Check if pages are indexed
node ${CLAUDE_PLUGIN_ROOT}/tools/gsc-client.mjs inspect-url <site-url> <page-url>

# See what keywords you rank for
node ${CLAUDE_PLUGIN_ROOT}/tools/gsc-client.mjs query <site-url> 28

# List all submitted sitemaps
node ${CLAUDE_PLUGIN_ROOT}/tools/gsc-client.mjs list-sitemaps <site-url>

**Bing Webmaster Tools** (requires ULTRASHIP_BING_KEY):

# Submit sitemap (also powers DuckDuckGo + ChatGPT Search)
node ${CLAUDE_PLUGIN_ROOT}/tools/bing-webmaster.mjs submit-sitemap <site-url> <sitemap-url>

# Submit specific URLs for fast indexing
node ${CLAUDE_PLUGIN_ROOT}/tools/bing-webmaster.mjs submit-url <site-url> <page-url>

# Batch submit multiple URLs
node ${CLAUDE_PLUGIN_ROOT}/tools/bing-webmaster.mjs submit-url-batch <site-url> <url1> <url2> ...

# Check URL traffic
node ${CLAUDE_PLUGIN_ROOT}/tools/bing-webmaster.mjs url-info <site-url> <page-url>

If credentials are not set, show setup instructions from the tool's error output. Do NOT skip this phase — submitting sitemaps to both GSC and Bing is critical for indexing speed.

**Why Bing matters for AI search:** Bing's index powers ChatGPT Search, DuckDuckGo, and Yahoo. Submitting your sitemap to Bing directly improves AI search visibility.

Phase 4b: Content Quality Analysis

Run content scoring on all pages:

node ${CLAUDE_PLUGIN_ROOT}/tools/content-scorer.mjs <project-directory>

For pages with a known target keyword:

node ${CLAUDE_PLUGIN_ROOT}/tools/content-scorer.mjs <project-directory> --keyword=<keyword>

Report readability scores (Flesch-Kincaid), keyword density, thin content, and GEO heading optimization.

Phase 4c: Social Preview Validation

Validate Open Graph tags and image accessibility:

node ${CLAUDE_PLUGIN_ROOT}/tools/og-validator.mjs <project-directory>

Fix missing OG tags, broken OG images, and oversized preview images.

Phase 4d: Redirect Audit

If a production URL is available, check for redirect chains:

node ${CLAUDE_PLUGIN_ROOT}/tools/redirect-checker.mjs --sitemap=<sitemap-url>

Fix redirect chains (consolidate to single hop), convert 302s to 301s, and resolve mixed HTTP/HTTPS.

Phase 5: Verify

Re-run the scanner to confirm fixes and report before/after scores.

Save scores for historical comparison:

node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> seo <score>
node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> geo <score>
node ${CLAUDE_PLUGIN_ROOT}/tools/audit-history.mjs save <project-dir> aeo <score>

Phase 6: AI Search Content Strategy

After technical fixes, advise on content-level optimizations that the scanner cannot automate:

**GEO Content Patterns (for AI citation):**

• Rewrite key H2 headers as questions: "What is [topic]", "How does [feature] work", "Why use [product]"
• Add 1-2 sentence TL;DR summaries under important H2 sections — AI engines extract these as standalone answers
• Use plain-language definitions before introducing nuance: "[Product] is [clear definition]"
• Write in citation-ready format: concise, factual, quotable — avoid vague marketing copy
• Create comparison tables, statistics pages, and glossaries — these are the most-cited page formats by AI

**E-E-A-T Signals (for AI trust):**

• Add Author/Person schema with credentials