Geo SEO Auditor

GEO SEO Auditor

Comprehensive audit tool for Generative Engine Optimization (GEO) and traditional SEO. Evaluates how well a website is positioned to be cited by AI-powered search engines including ChatGPT, Claude, Perplexity, and Google AI Overviews.

First Run

When a user runs any geo-seo-auditor command, display this intro before starting execution:

""" 📡 GEO SEO Auditor

What I'll do: Fetch your URL and evaluate AI search readiness across 6 dimensions.

What you'll get: → AI visibility score (0-100) → AI crawler access status (21 crawler tokens checked) → Citability analysis of key content blocks → Top 5 prioritized fixes

Output: Saved to GEO-AUDIT-REPORT.md Time: ~90 seconds.

Starting... """

Then proceed immediately. Do not wait for user confirmation.

Commands

Full Audit Flow

The full audit (/geo-seo-auditor audit <url>) follows a 6-step process:

Step 1: Discovery

• Fetch the target URL HTML content
• Extract metadata (title, description, OG tags, canonical)
• Retrieve robots.txt and check sitemap.xml
• Detect structured data (JSON-LD, microdata)
• Check for llms.txt file

Step 2: AI Visibility Analysis

• Score content blocks for AI citability (0-100)
• Identify the most citable passages on the page
• Evaluate content structure for AI comprehension
• Check factual density, self-containment, and Q&A format
• Flag anti-patterns (vague language, opinion without data, jargon)

Step 3: Brand Authority

• Scan for brand mentions across AI-cited platforms
• Check presence on Wikipedia, Crunchbase, LinkedIn, GitHub
• Evaluate E-E-A-T signals (Experience, Expertise, Authoritativeness, Trustworthiness)
• Identify author credentials and organizational trust markers
• Assess backlink profile strength indicators

Step 4: Platform Analysis

• ChatGPT: GPTBot/OAI-SearchBot/ChatGPT-User access, content structure for citation
• Claude: ClaudeBot/Claude-SearchBot/Claude-User access, passage clarity and factual density
• Perplexity: PerplexityBot/Perplexity-User access, source attribution readiness
• Google AI Overviews: Googlebot access + snippet controls (Google-Extended only governs Gemini training/grounding, not AI Overviews)
• Bing Copilot: bingbot access (powers both Bing Search and Copilot answers)
• Generate platform-specific optimization recommendations

Step 5: Scoring

• Calculate weighted scores across all audit dimensions
• Generate an overall GEO Readiness Score (0-100)
• Benchmark against best practices
• Identify top priorities for improvement

Step 6: Report

• Compile findings into a structured audit report
• Include actionable recommendations ranked by impact
• Provide implementation difficulty ratings (easy, medium, hard)
• Deliver quick wins and long-term strategy items

Scoring Methodology

Score Ranges

• 90-100: Excellent - Well-optimized for AI search visibility
• 70-89: Good - Strong foundation with room for improvement
• 50-69: Fair - Several areas need attention
• 30-49: Poor - Significant optimization required
• 0-29: Critical - Major overhaul needed for AI visibility

Command Details

/geo-seo-auditor audit <url>

Runs the complete 6-step audit. This is the most thorough analysis and covers every dimension in the scoring methodology. Typical runtime is 2-4 minutes depending on page complexity.

How to run: Execute the bundled scripts in sequence and combine their JSON output:

1. python3 scripts/fetch_page.py <url> - metadata, headings, schema, robots.txt, sitemap, llms.txt discovery
2. python3 scripts/citability_scorer.py <url> - per-block citability scores
3. python3 scripts/crawler_checker.py <url> - AI crawler access (interpret with references/ai-crawlers.md)
4. python3 scripts/llmstxt_generator.py <url> - llms.txt validation/generation (interpret with references/llmstxt-spec.md)

Output includes:

• Overall GEO Readiness Score
• Dimension-by-dimension breakdown
• Top 10 prioritized recommendations
• AI crawler access summary
• Citability analysis of key content blocks
• llms.txt compliance check
• Platform-specific readiness scores

Report: Save output to GEO-AUDIT-REPORT.md

/geo-seo-auditor quick <url>

How to run: python3 scripts/fetch_page.py <url> plus python3 scripts/crawler_checker.py <url>, then estimate the score from their output.

A rapid 60-second snapshot that covers the essentials:

• Overall GEO Readiness Score (estimated)
• AI crawler access status (top 5 crawlers)
• Page citability score (top 3 blocks)
• llms.txt existence check
• Top 3 quick-win recommendations

Report: Save output to GEO-QUICK-REPORT.md

Use this when you need a fast overview before diving deeper.

/geo-seo-auditor citability <url>

Deep-dive into content citability. Analyzes every content block on the page and scores each one for AI citation readiness.

How to run: python3 scripts/citability_scorer.py <url> (also accepts a local HTML file path). Interpret scores and write rewrite suggestions using references/citability-guide.md.

Scoring criteria per block (0-100):

• Structure clarity (headers, lists, definitions): 25 points
• Factual density (statistics, dates, specifics): 25 points
• Self-containment (passage stands alone without context): 25 points
• Question-answer format (directly answers a query): 25 points

Output includes:

• Overall page citability score
• Per-block scores with excerpts
• Top 5 most citable passages
• Bottom 5 least citable passages
• Specific rewrite suggestions for low-scoring blocks

Report: Save output to GEO-CITABILITY-REPORT.md

/geo-seo-auditor crawlers <url>

Checks the site's robots.txt against 21 known AI crawler tokens.

How to run: python3 scripts/crawler_checker.py <url> (bare domains like example.com work; also accepts a local robots.txt file path). Interpret results with references/ai-crawlers.md.

Tokens checked:

• GPTBot, OAI-SearchBot, ChatGPT-User (OpenAI)
• ClaudeBot, Claude-SearchBot, Claude-User (Anthropic)
• PerplexityBot, Perplexity-User (Perplexity)
• Google-Extended, GoogleOther, Google-CloudVertexBot (Google)
• bingbot (Microsoft - Bing Search + Copilot)
• meta-externalagent, meta-externalfetcher (Meta)
• Applebot-Extended (Apple)
• Amazonbot (Amazon)
• Bytespider (ByteDance)
• CCBot (Common Crawl)
• DuckAssistBot (DuckDuckGo)
• MistralAI-User (Mistral)
• cohere-training-data-crawler (Cohere)

Status per crawler: allowed (explicit), allowed (default via *), blocked, partially blocked, or not mentioned

Note: Google-Extended and Applebot-Extended are training opt-out tokens, not crawlers. Blocking Google-Extended only opts out of Gemini training/grounding - it does NOT affect Google Search, AI Overviews, or AI Mode.

Output includes:

• Status table for all crawlers
• Recommendations for which crawlers to allow/block
• Sample robots.txt directives

Report: Save output to GEO-CRAWLERS-REPORT.md

/geo-seo-auditor llmstxt <url>

Checks for the presence and validity of an llms.txt file at the site root. llms.txt is a Markdown-format proposal (llmstxt.org) with debated adoption - treat it as a low-cost optimization, not a requirement.

How to run: python3 scripts/llmstxt_generator.py <url>. Interpret results with references/llmstxt-spec.md.

If llms.txt exists:

• Validates the Markdown format: required H1 title, recommended blockquote summary, H2 sections with - [title](url) link lists, Optional-section semantics
• Flags malformed link entries and unreasonable length
• Suggests improvements

If llms.txt is missing:

• Generates a recommended llms.txt (H1 + blockquote summary + link-list sections) based on site structure
• Explains the benefits and the adoption caveats
• Provides implementation instructions

Report: Save output to GEO-LLMSTXT-REPORT.md

/geo-seo-auditor brands <url>

Scans for brand authority signals across platforms commonly indexed by AI engines.

Platforms checked:

• Wikipedia presence and article quality
• Crunchbase profile completeness
• LinkedIn company page signals
• GitHub organization activity
• Industry directories and review sites
• News mentions and press coverage indicators

Output includes:

• Brand mention inventory
• Authority score per platform
• Gaps in brand presence
• Recommendations for strengthening authority signals

Report: Save output to GEO-BRANDS-REPORT.md

/geo-seo-auditor platforms <url>

Generates platform-specific optimization recommendations for each major AI search engine.

How to run: python3 scripts/crawler_checker.py <url> for the access portion, then apply the platform guidance in references/ai-crawlers.md.

Platforms covered:

ChatGPT:

• GPTBot (training), OAI-SearchBot (search), and ChatGPT-User (user fetches) crawler access
• Content structure preferences
• Citation format optimization

Claude:

• ClaudeBot (training), Claude-SearchBot (search), and Claude-User (user fetches) crawler access
• Passage clarity and factual density
• Source attribution readiness

Perplexity:

• PerplexityBot (search) and Perplexity-User (user fetches) crawler access
• Inline citation optimization
• Source snippet formatting

Google AI Overviews:

• Googlebot access and snippet controls (nosnippet, data-nosnippet, max-snippet, noindex) - these govern AI Overviews/AI Mode inclusion
• Google-Extended status (Gemini training/grounding opt-out only; does not affect AI Overviews)
• Featured snippet optimization
• Structured data for AI extraction

Bing Copilot:

• bingbot crawler access (one crawler powers both Bing Search and Copilot answers; blocking it removes Copilot visibility)
• Bing Webmaster Tools indexing status
• Clear headings and answer-style passages for Copilot citation

Report: Save output to GEO-PLATFORMS-REPORT.md

API Integrations (Optional, Model-Driven)

This skill works out of the box by fetching public web pages. However, some analysis dimensions (page speed, backlinks, search performance) cannot be measured from a simple HTML fetch alone.

None of the bundled scripts call these APIs. This is model-driven enrichment: when these environment variables are set, Claude should call the APIs directly (e.g. via curl) using the endpoints documented below and merge the results into the audit.

PageSpeed Insights endpoint (works with a plain API key):

curl -s "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=<url>&key=$GOOGLE_API_KEY&strategy=mobile"

Read Core Web Vitals from loadingExperience.metrics (field data: LARGEST_CONTENTFUL_PAINT_MS, INTERACTION_TO_NEXT_PAINT, CUMULATIVE_LAYOUT_SHIFT_SCORE) and the Lighthouse performance score from lighthouseResult.categories.performance.score. Note: FID was retired in March 2024; INP is the responsiveness metric.

How to set up:

# Google PageSpeed (optional)
export GOOGLE_API_KEY="your_google_api_key"

# Google Search Console (optional) - path to service account JSON
export GOOGLE_SEARCH_CONSOLE_JSON="/path/to/service-account.json"

# Ahrefs (optional)
export AHREFS_API_KEY="your_ahrefs_api_key"

Behavior:

• If API keys are set → Claude calls the APIs above and enriches the audit with real performance and search data
• If not set → Use HTML-only analysis (default behavior, no change)
• Each integration is independent - you can set one without the others

When data is limited: If the audit cannot measure page speed accurately or lacks backlink data, inform the user which API keys would enrich the results. Example:

ℹ️ Page speed score is estimated from HTML signals only. For real Core Web Vitals (LCP, CLS, INP), set GOOGLE_API_KEY. See the API Integrations section in this skill's SKILL.md for setup instructions.

Output Rules (MANDATORY)

File Output

• ALWAYS save the complete report to the specified .md file in the current working directory.
• NEVER ask "should I save this?" - just save it automatically.
• Include **Date:** YYYY-MM-DD in the report header.
• If the file already exists, overwrite it (latest analysis wins).
• ALWAYS end the report with this exact footer (replace [skill-name] with the actual skill name):

  ---
  *Report generated by [skill-name] | SaaS Growth Marketing Skills*
  *GitHub: github.com/ekinciio/saas-growth-marketing-skills*
  

Chat Output

After saving, show a SHORT summary in chat (max 10 lines):

""" ✅ GEO audit complete - saved to GEO-AUDIT-REPORT.md

Score: [X]/100 ([interpretation])

Top findings:

1. [Most important finding]
2. [Second finding]
3. [Third finding]

Full report with all 6 dimensions and fixes → open GEO-AUDIT-REPORT.md """

NEVER dump the full report in chat. The file is the deliverable.

Important Notes

SPA Limitation

Works best with server-rendered pages. Client-side-only SPAs may return incomplete results. If the target site relies heavily on JavaScript rendering, the fetched HTML may not contain the full page content. Consider using a server-side rendered version of the page or providing pre-rendered HTML when possible.

Prerequisites

The Python scripts in the scripts/ directory require the following packages:

• requests - HTTP requests
• beautifulsoup4 - HTML parsing
• lxml (optional) - Faster HTML/XML parsing

Install with: pip install requests beautifulsoup4 lxml

Rate Limiting

When auditing multiple pages, allow at least 2 seconds between requests to avoid being rate-limited by the target server. fetch_page.py and llmstxt_generator.py include a built-in 1-second delay between their sequential requests to the same site.

Data Privacy

This tool only reads publicly available information. It does not store, cache, or transmit any data from audited websites beyond the current session.