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

| Mode | Detect | Audit | Classify | Generate | Report | Cross-ref | |------|--------|-------|----------|----------|--------|-----------| | full | Yes | Yes | Yes | Yes | Yes | Yes | | audit | Yes | Yes | Yes | Skip | Yes | Yes | | generate | Yes | Skip | Skip | Yes | Yes | Yes | | monitor | Yes | Yes | Yes | Skip | Yes (diff) | Yes |

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):

| Type | Detection Signals | |------|------------------| | ecommerce | Product schema, cart/checkout routes, Shopify/WooCommerce/Stripe markers, product listing templates | | saas | Pricing page, docs section, API references, login/signup routes, dashboard templates | | content | Blog templates, author pages, RSS feeds, high content-to-code ratio, CMS markers | | local | LocalBusiness schema, address/map elements, service area pages, Google Maps embed | | docs | Versioned docs structure, API reference, sidebar nav config, code blocks predominant | | personal | Person schema, about page, project showcase, small page count (<20), portfolio layout |

# 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

| Tier | Pages | Approach | |------|-------|----------| | small | <50 | Manual audit, essential artifacts only, quick wins | | medium | 50–500 | Selective optimization, programmatic schema for templates | | large | 500+ | Template-based fixes, automated pattern detection | | enterprise | 10K+ | Governance focus, CI/CD integration, sampling audit |

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

| Score | Criteria | |-------|----------| | 0 | Search-critical bots blocked, OR CDN bot blocking, OR JS-only rendering (P0) | | 1 | Some search bots allowed but OAI-SearchBot or PerplexityBot blocked | | 2 | All search-critical bots allowed but user-triggered fetch bots blocked | | 3 | All search-critical + user-triggered fetch bots allowed, no CDN blocking | | 4 | All bots allowed + IndexNow configured + <500ms bot response |

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

| Score | Criteria | |-------|----------| | 0 | No llms.txt, no AI-specific discovery files | | 1 | llms.txt present but minimal (just H1) | | 2 | llms.txt with H1 + blockquote + sections; OR sitemap with lastmod | | 3 | Well-structured llms.txt + ## Optional; sitemap with lastmod; RSS/Atom | | 4 | llms.txt + llms-full.txt + sitemap + RSS + comprehensive coverage |

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:

| Type | Required | Bonus | |------|----------|-------| | ecommerce | Product, Organization, BreadcrumbList | AggregateRating, Review, Offer | | saas | Organization, SoftwareApplication, FAQPage | HowTo, Article | | content | Article, Organization, Person |