Geo SEO

GEO/SEO: AI Search Visibility Audit & Artifact Generator

Audit a website for AI search visibility across 7 research-grounded dimensions, generate deployable artifacts (llms.txt, schema JSON-LD, robots.txt), and produce a prioritized action plan — all tailored to the site's type and scale.

Complementary to agentic-seo: This skill measures whether content gets cited when humans search via ChatGPT/Perplexity/Google AI Overviews. agentic-seo (run separately via npx agentic-seo ./out) measures whether AI agents can interact with the site (including agent.json manifests, skill discovery, permission systems). Run both for complete coverage.

Arguments

Parse `` for:

• path: Project root to audit (default: current working directory)
• --type: Override auto-detected site type
• --size: Override auto-detected size tier
• --mode: audit (scorecard only), generate (artifacts only), full (both, default), monitor (compare to previous snapshot)

Workflow

Execute these phases in order: Detect → Audit → Classify → Generate → Report → Cross-reference.

Mode-to-Phase Mapping

Phase 1: Detect Site Profile

Auto-detect site type, size, and framework from codebase signals. Report findings before proceeding.

Site Type Detection

Examine the project for these signals (override with --type):

# Detection heuristics — run these checks
grep -rl "Product\|AggregateOffer\|AddToCart\|checkout" --include="*.{tsx,jsx,html,json}" . 2>/dev/null | head -5
grep -rl "LocalBusiness\|GeoCoordinates\|serviceArea" --include="*.{tsx,jsx,html,json}" . 2>/dev/null | head -5
find . -path "*/docs/*" -name "*.md" 2>/dev/null | wc -l
find . -path "*/blog/*" -o -path "*/posts/*" 2>/dev/null | wc -l
ls pricing* docs/ api/ blog/ 2>/dev/null

Site Size Detection

Count indexable pages:

# For static sites with build output
find ./out ./dist ./build ./_site -name "*.html" 2>/dev/null | wc -l

# For dynamic sites, count route definitions
grep -r "path:\|route\|getStaticPaths\|generateStaticParams" --include="*.{ts,tsx,js,jsx}" . 2>/dev/null | wc -l

# For content sites, count content files
find . -name "*.md" -o -name "*.mdx" 2>/dev/null | grep -v node_modules | wc -l

Framework Detection

# Check package.json, config files
cat package.json 2>/dev/null | grep -E '"(next|gatsby|nuxt|astro|svelte|remix|vite|hugo|jekyll)"'
ls next.config.* nuxt.config.* astro.config.* svelte.config.* gatsby-config.* vite.config.* 2>/dev/null
cat package.json 2>/dev/null | grep -E '"(react|vue|angular|svelte)"'

Report format:

Site Profile: [type] | [size] tier ([N] pages) | [framework]

Phase 2: Audit — 7-Dimension Scoring

Score each dimension 0–4. The inline tables below are quick-reference summaries. Load references/scoring-rubric.md for the authoritative rubric with research citations and detailed check procedures — the reference version takes precedence when they differ.

Dimension 1: AI Crawler Access (0–4)

Check robots.txt for the 9 critical AI crawlers. Distinguish training bots (safe to block) from search/retrieval bots (blocking = invisible to AI search).

Crawlers to check (three tiers): See references/ai-crawlers.md for the full registry.

Search-critical (blocking loses AI search): OAI-SearchBot, PerplexityBot, Claude-SearchBot, Bingbot, Googlebot, Bravebot, YouBot.

User-triggered fetch (recommended to allow, not search-critical): ChatGPT-User, Perplexity-User, Claude-User.

Training-only (safe to block): GPTBot, ClaudeBot, Google-Extended, CCBot, Bytespider, Amazonbot, Diffbot, Applebot-Extended.

# Check robots.txt
cat robots.txt public/robots.txt static/robots.txt 2>/dev/null

# Check for CDN bot blocking (Cloudflare Bot Fight Mode, Vercel firewall)
grep -ri "bot.*fight\|bot.*manage\|firewall" wrangler.toml vercel.json netlify.toml _headers 2>/dev/null

P0 check — JavaScript-only rendering: AI crawlers do not execute JavaScript. If the site is client-side rendered (CSR/SPA) without SSR/SSG, flag as P0.

# Check for SSR/SSG configuration
grep -r "getServerSideProps\|getStaticProps\|generateStaticParams\|output.*export\|prerender\|ssr" --include="*.{ts,tsx,js,jsx,mjs}" . 2>/dev/null | head -5

Dimension 2: AI Discovery Infrastructure (0–4)

Check for llms.txt, sitemap, RSS/Atom feeds. Load references/llms-txt-spec.md for validation rules.

# Check for discovery files
ls public/llms.txt public/llms-full.txt llms.txt llms-full.txt 2>/dev/null
ls public/sitemap.xml sitemap.xml out/sitemap.xml 2>/dev/null
grep -r "application/rss\|application/atom\|feed\.xml\|rss\.xml" --include="*.{tsx,jsx,html,xml}" . 2>/dev/null | head -3

llms.txt validation (if present):

• Single H1 title (required)
• Blockquote summary after H1
• H2 sections with Markdown link lists in [name](url): description format
• ## Optional section for lower-priority content

Dimension 3: Structured Data Quality (0–4)

Check JSON-LD structured data completeness. Load references/schema-patterns.md for site-type-specific requirements.

# Find all JSON-LD
grep -rl "application/ld+json" --include="*.{tsx,jsx,html}" . 2>/dev/null
grep -r "@type" --include="*.{tsx,jsx,html}" . 2>/dev/null | grep -o '"@type"[^,]*' | sort -u

Rankeo finding: Minimal/generic schema (41.6% citation rate) performs WORSE than no schema (59.8%). Only award points for complete, attribute-rich schema.

Required @types by site type:

P0 check: Duplicate singleton @types on same page (e.g., two FAQPage) — silently dropped by Google.

Dimension 4: Content Citability (0–4)

Evaluate content structure, passage length, front-loading, statistics density, and attribution patterns. This dimension requires reading actual content pages.

# Sample 3-5 content-heavy pages for analysis
find . -name "*.tsx" -o -name "*.jsx" -o -name "*.html" -o -name "*.md" 2>/dev/null | grep -v node_modules | grep -iE "about|blog|post|article|page|index" | head -5

Research-grounded checks:

• Passage length: 134–167 words optimal for AI extraction
• Front-loading: Key answer in first 30% of content (44.2% of ChatGPT citations come from there)
• Statistics density: Numbers per 150–200 words
• Attribution patterns: "According to [Authority]" — mimics what LLMs recognize from training
• Declarative tone: No hedging ("it seems," "may be") — declarative claims outperform
• Section coherence: Each H2/H3 section independently intelligible (Perplexity treats sections as first-class units)
• Heading hierarchy: Clear, semantic heading structure (44% of all AI citations from pages with clear hierarchy, per Yext 6.8M citation analysis)

Dimension 5: Technical SEO Foundation (0–4)

Lily Ray's constraint: if SEO foundation is broken (score 0–1), flag P0 "Fix SEO before pursuing GEO." RAG requires crawl + index.

# Check meta tags, canonical, sitemap
grep -r "noindex" --include="*.{tsx,jsx,html}" . 2>/dev/null | grep -v node_modules | head -5
grep -r "canonical\|metadataBase" --include="*.{tsx,jsx,ts}" . 2>/dev/null | head -5
grep -r "<title\|metadata.*title\|Head.*title" --include="*.{tsx,jsx,ts}" . 2>/dev/null | head -5
grep -r "description\|meta.*description" --include="*.{tsx,jsx,ts}" . 2>/dev/null | head -5

# Check for Open Graph
grep -r "og:title\|openGraph\|twitter:card" --include="*.{tsx,jsx,ts,html}" . 2>/dev/null | head -5

Dimension 6: Entity & Brand Signals (0–4)

Ahrefs 75K-brand study: unlinked mentions correlate 0.664 with AI visibility; backlinks only 0.218. YouTube mentions strongest single factor (0.737).

# Check Organization/Person schema with sameAs
grep -r "sameAs\|Organization\|Person" --include="*.{tsx,jsx,ts,json}" . 2>/dev/null | head -10

# Check for consistent brand naming
grep -r "publisher\|author\|brand\|organizationName" --include="*.{tsx,jsx,ts,json}" . 2>/dev/null | head -5

Dimension 7: Multi-Engine Readiness (0–4)

Only 11% domain overlap between Perplexity and ChatGPT (U of Toronto). Engine-specific optimization is structurally required. Load references/engine-profiles.md for per-engine profiles.

# Check for engine-specific signals
grep -r "IndexNow\|indexnow" --include="*.{json,xml,ts,js}" . 2>/dev/null
grep -r "dateModified\|datePublished\|lastmod" --include="*.{tsx,jsx,ts,json,xml}" . 2>/dev/null | head -5

Site-Type Scoring Weights

Apply weight modifiers when interpreting scores. "Critical" dimensions with low scores warrant P0 findings.

Score Bands

Phase 3: Classify Findings

Assign severity levels to each finding based on dimension scores and site-type weights:

Phase 4: Generate Artifacts

Skip this phase in audit mode. In generate or full mode, produce the artifacts below.

4a. llms.txt

Generate llms.txt following Jeremy Howard's spec (AnswerDotAI, Sep 2024). Load references/llms-txt-spec.md for format details.

1. Detect site name from package.json, Organization schema, or site config
2. Write summary from homepage meta description or first content paragraph
3. Categorize pages by type (docs, blog, product, about, API)
4. Prioritize by internal link count and content depth
5. Mark lower-priority pages under ## Optional

Load assets/templates/llms-txt/ for site-type starter templates.

If llms.txt already exists, audit it against the spec instead of overwriting. Report improvements.

4b. Schema JSON-LD

Generate complete, attribute-rich JSON-LD for the detected site type. Load references/schema-patterns.md for patterns and assets/templates/schema/ for starters.

• Detect existing schema and identify gaps
• Generate schema with 8+ attributes per type (per Rankeo: completeness > presence)
• Include sameAs links to known entity references
• Use site-type-specific @types from the rubric
• Validate: no duplicate singleton types per page

If schema already exists, report what's missing rather than overwriting.

4c. robots.txt AI Crawler Directives

Generate directives separating training bots from search bots. Load references/ai-crawlers.md for the full registry.

# AI Search Crawlers — allow for AI search visibility
User-agent: OAI-SearchBot
Allow: /

User-agent: PerplexityBot
Allow: /

# User-triggered fetch — recommended to allow
User-agent: ChatGPT-User
Allow: /

# AI Training Crawlers — block to protect content
User-agent: GPTBot
Disallow: /

User-agent: CCBot
Disallow: /

The inline example above is a minimal subset. Load assets/templates/robots-ai-block.txt for the complete template covering all search, fetch, and training crawlers.

If robots.txt already exists, check for conflicts and report them. Do not overwrite without confirmation.

Phase 5: Report

Load references/research-basis.md when populating the Research Citations section with specific paper references supporting key findings.

Produce the audit report in this format:

## GEO/SEO Audit Report

### Site Profile
- **Type:** [detected/override] | **Size:** [tier] ([N] pages) | **Framework:** [detected]
- **Score:** [X/28] — [Rating]
- **Complementary:** Run `npx agentic-seo ./out` for agent readability scoring

### Scorecard
| # | Dimension | Score | Key Finding |
|---|-----------|-------|-------------|
| 1 | AI Crawler Access | X/4 | ... |
| 2 | AI Discovery Infrastructure | X/4 | ... |
| 3 | Structured Data Quality | X/4 | ... |
| 4 | Content Citability | X/4 | ... |
| 5 | Technical SEO Foundation | X/4 | ... |
| 6 | Entity & Brand Signals | X/4 | ... |
| 7 | Multi-Engine Readiness | X/4 | ... |
| | **Total** | **X/28** | |

### Findings

#### P0 — Critical (blocks AI search visibility)
[findings or "None"]

#### P1 — High (significant citation impact)
[findings]

#### P2 — Medium (optimization opportunity)
[findings]

#### P3 — Low / Informational
[findings]

### Positive Findings
[what's already working well]

### Generated Artifacts
[paths to generated files, if any]

### Recommended Actions (prioritized)
1. [highest impact action]
2. ...

### Research Citations
[cite specific papers/studies supporting key findings]

Phase 6: Cross-Reference

After the report, suggest complementary tools:

• npx agentic-seo ./out — agent readability (run after build)
• /design-audit — visual/UX quality (if available)
• Google Rich Results Test — validate generated JSON-LD
• llm-txt-validator.vercel.app — validate llms.txt

Monitor Mode

When --mode=monitor:

1. Look for .geo-seo-snapshot.json in the project root
2. If found, run full audit and compare scores dimension-by-dimension
3. Report improvements, regressions, and unchanged dimensions
4. Save new snapshot

If no previous snapshot exists, run full audit and save the first snapshot. Save snapshots to .geo-seo-snapshot.json in the project root.

Snapshot format:

{
  "date": "2026-05-12",
  "score": 22,
  "dimensions": {
    "crawler_access": 4,
    "discovery": 3,
    "structured_data": 3,
    "citability": 3,
    "technical_seo": 3,
    "entity_brand": 3,
    "multi_engine": 3
  },
  "site_type": "content",
  "site_size": "medium",
  "finding_count": { "p0": 0, "p1": 2, "p2": 4, "p3": 3 }
}

Gotchas

Failure modes that produce wrong results without this section. Each represents a common mistake in AI search optimization.

1. "Add FAQs everywhere" — FAQ bloat damages traditional SEO, which undermines GEO (Lily Ray, Mar 2026). FAQPage schema lifts citations 2.7x, but filling pages with 50 thin Q&As hurts the overall SEO foundation. Score FAQPage schema appropriately but do not recommend FAQ content universally.

2. Minimal schema worse than none — 41.6% citation rate for generic schema vs 59.8% for no schema (Rankeo). An Organization with just name and url actively hurts. Enforce the 8+ attribute completeness threshold. When existing schema is too thin, recommend removing it or completing it — not leaving it as-is.

3. All AI engines treated the same — Only 11% domain overlap between Perplexity and ChatGPT (U of Toronto, 118K answers). Perplexity has a freshness hard gate; ChatGPT has earned media bias; Google AIO leans on traditional SEO signals. Provide engine-specific analysis, not generic "optimize for AI search."

4. Ignoring earned media — On-page optimization alone cannot overcome the systematic earned media bias that ChatGPT and Google show. Entity & Brand dimension exists to surface this gap. Do not promise citation improvements from on-page work alone when the site has no external mentions.

5. CSR/SPA invisible to AI — AI crawlers do not execute JavaScript. A React SPA with no SSR/SSG is completely invisible. Check rendering mode as the very first thing — all other optimization is pointless if the content can't be crawled.

6. Silent CDN blocking — Cloudflare Bot Fight Mode blocks AI crawlers without any robots.txt evidence. Check for CDN-level blocking, not just robots.txt directives.

7. GEO without SEO foundation — RAG requires crawl + index. If traditional SEO is broken (no sitemap, noindex on main pages, broken canonicals), no GEO optimization will help. Technical SEO Foundation score 0–1 is always P0.

8. robots.txt training/search confusion — Most sites only reference GPTBot, which is training-only. Blocking GPTBot doesn't lose search. Blocking OAI-SearchBot does. Always surface the training vs search distinction — most site owners don't know OpenAI has 3 separate crawlers.

9. dateModified as decoration — Setting dateModified to today's date without changing content is a freshness signal lie. Perplexity will eventually detect and penalize this. Only recommend updating dateModified when content actually changes.

10. Overwriting existing artifacts — When llms.txt or robots.txt already exists, audit and suggest improvements. Do not generate a replacement and overwrite without explicit confirmation. The site owner may have intentional customizations.

11. Perplexity-User ignores robots.txt — Per Perplexity's own documentation, Perplexity-User "generally ignores robots.txt" directives. A Disallow rule for this bot gives false confidence — the site owner thinks they've blocked user-triggered fetches but they haven't. When auditing, flag this distinction: only PerplexityBot reliably respects robots.txt. Server-side User-Agent filtering is the only reliable block for Perplexity-User.

12. Zero-click outcomes are structural — AI search optimization may increase citation frequency while decreasing click-through traffic. This is not a failure of optimization — it is the structural reality of AI-mediated search (Rand Fishkin, SparkToro). Set realistic expectations: GEO success means brand visibility and authority in AI answers, not necessarily more website visits. For sites that depend on direct traffic, note that citation ≠ click.

Reference Documents

Load these on-demand when deeper context is needed:

Asset Templates