Geo

GEO-SEO Analysis Tool — Codex Skill

> Philosophy: GEO-first, SEO-supported. AI search is eating traditional search. > This tool optimizes for where traffic is going, not where it was.

---

Quick Reference

| Invocation | What It Does | |---------|-------------| | $geo-setup | Initialize plugin/classic runtime dependencies | | $geo-audit | Full GEO + SEO audit with parallel agents first; skills fallback | | $geo page | Deep single-page GEO analysis (listed for orchestrator routing; no dedicated sub-skill yet) | | $geo-citability | Score content for AI citation readiness | | $geo-crawlers | Check AI crawler access (robots.txt analysis) | | $geo-llmstxt | Analyze or generate llms.txt file | | $geo-brand-mentions | Scan brand mentions across AI-cited platforms | | $geo-platform-optimizer | Platform-specific optimization (ChatGPT, Perplexity, Google AIO) | | $geo-schema | Detect, validate, and generate structured data | | $geo-technical | Traditional technical SEO audit | | $geo-content | Content quality and E-E-A-T assessment | | $geo-report | Generate client-ready GEO deliverable | | $geo-report-pdf | Generate professional PDF report with charts and scores | | $geo quick | 60-second GEO visibility snapshot | | $geo-prospect | CRM-lite: manage prospects through the sales pipeline | | $geo-proposal | Auto-generate client proposal from audit data | | $geo-compare | Monthly delta report: show score improvements to client | | $geo-update | Pull latest GEO skill updates from upstream |

---

Market Context (Why GEO Matters)

| Metric | Value | Source | |--------|-------|--------| | GEO services market (2025) | $850M-$886M | Yahoo Finance / Superlines | | Projected GEO market (2031) | $7.3B (34% CAGR) | Industry analysts | | AI-referred sessions growth | +527% (Jan-May 2025) | SparkToro | | AI traffic conversion vs organic | 4.4x higher | Industry data | | Google AI Overviews reach | 1.5B users/month, 200+ countries | Google | | ChatGPT weekly active users | 900M+ | OpenAI | | Perplexity monthly queries | 500M+ | Perplexity | | Gartner: search traffic drop by 2028 | -50% | Gartner | | Marketers investing in GEO | Only 23% | Industry surveys | | Brand mentions vs backlinks for AI | 3x stronger correlation | Ahrefs (Dec 2025) |

---

Orchestration Logic

Full Audit ($geo-audit )

Phase 1: Discovery (Sequential)

1. Fetch homepage HTML (curl or WebFetch)
2. Detect business type (SaaS, Local, E-commerce, Publisher, Agency, Other)
3. Extract key pages from sitemap.xml or internal links (up to 50 pages)

Phase 2: Parallel Agents First, Skills Fallback Run these 5 analysis tracks. Prefer launching the matching TOML agents in parallel when they are available under ~/.codex/agents/ or the active Codex environment. If an agent is missing or unavailable, execute only that track directly through the listed skills and rubrics. The scoring formula, findings structure, and output contract are identical in both modes.

| Track | Preferred Agent | Fallback Skills / Responsibility | |-------|-----------------|----------------------------------| | AI Visibility | agents/geo-ai-visibility.toml | geo-citability, geo-crawlers, geo-llmstxt, geo-brand-mentions | | Platform Analysis | agents/geo-platform-analysis.toml | geo-platform-optimizer for ChatGPT, Perplexity, Google AIO, Gemini, Bing Copilot | | Technical GEO | agents/geo-technical.toml | geo-technical for Core Web Vitals, crawlability, indexability, rendering | | Content Quality | agents/geo-content.toml | geo-content for E-E-A-T, readability, source quality, freshness | | Structured Data | agents/geo-schema.toml | geo-schema for schema detection, validation, and generation |

Phase 3: Synthesis (Sequential)

1. Collect all analysis-track reports
2. Calculate composite GEO Score (0-100)
3. Generate prioritized action plan
4. Output client-ready report

Scoring Methodology

| Category | Weight | Measured By | |----------|--------|-------------| | AI Citability & Visibility | 25% | Passage scoring, answer block quality, AI crawler access | | Brand Authority Signals | 20% | Mentions on Reddit, YouTube, Wikipedia, LinkedIn; entity presence | | Content Quality & E-E-A-T | 20% | Expertise signals, original data, author credentials | | Technical Foundations | 15% | SSR, Core Web Vitals, crawlability, mobile, security | | Structured Data | 10% | Schema completeness, JSON-LD validation, rich result eligibility | | Platform Optimization | 10% | Platform-specific readiness (Google AIO, ChatGPT, Perplexity) |

---

Business Type Detection

Analyze homepage for patterns:

| Type | Signals | |------|---------| | SaaS | Pricing page, "Sign up", "Free trial", "/app", "/dashboard", API docs | | Local Service | Phone number, address, "Near me", Google Maps embed, service area | | E-commerce | Product pages, cart, "Add to cart", price elements, product schema | | Publisher | Blog, articles, bylines, publication dates, article schema | | Agency | Portfolio, case studies, "Our services", client logos, testimonials | | Other | Default — apply general GEO best practices |

Adjust recommendations based on detected type. Local businesses need LocalBusiness schema and Google Business Profile optimization. SaaS needs SoftwareApplication schema and comparison page strategy. E-commerce needs Product schema and review aggregation.

---

Runtime Resolution

When a workflow needs bundled scripts, schema templates, or report templates, resolve GEO_ROOT in this order:

1. CODEX_GEO_ROOT if set.
2. The plugin/repository root that contains this skill's skills/geo/SKILL.md plus sibling scripts/, schema/, and templates/.
3. The classic installer path ${CODEX_HOME:-$HOME/.codex}/skills/geo.

Use $geo-setup when dependencies are missing. In plugin mode, the virtual environment can live under ${CODEX_HOME:-$HOME/.codex}/geo-seo-codex/.venv; in classic installer mode it remains under ~/.codex/skills/geo/.venv.

---

Sub-Skills (16 Specialized Components)

| # | Skill | Directory | Purpose | |---|-------|-----------|---------| | 1 | geo-audit | skills/geo-audit/ | Full audit orchestration and scoring | | 2 | geo-citability | skills/geo-citability/ | Passage-level AI citation readiness | | 3 | geo-crawlers | skills/geo-crawlers/ | AI crawler access and robots.txt | | 4 | geo-llmstxt | skills/geo-llmstxt/ | llms.txt standard analysis and generation | | 5 | geo-brand-mentions | skills/geo-brand-mentions/ | Brand presence on AI-cited platforms | | 6 | geo-platform-optimizer | skills/geo-platform-optimizer/ | Platform-specific AI search optimization | | 7 | geo-schema | skills/geo-schema/ | Structured data for AI discoverability | | 8 | geo-technical | skills/geo-technical/ | Technical SEO foundations | | 9 | geo-content | skills/geo-content/ | Content quality and E-E-A-T | | 10 | geo-report | skills/geo-report/ | Client-ready deliverable generation | | 11 | geo-prospect | skills/geo-prospect/ | CRM-lite prospect and client pipeline management | | 12 | geo-proposal | skills/geo-proposal/ | Auto-generate client proposals from audit data | | 13 | geo-compare | skills/geo-compare/ | Monthly delta tracking and progress reports | | 14 | geo-update | skills/geo-update/ | Pull latest updates from upstream repository | | 15 | geo-setup | skills/geo-setup/ | Initialize or repair plugin/classic runtime dependencies |

---

Optional Subagents (5 Parallel Workers)

These agents are the preferred fast path for full audits. Do not require them for plugin-only use; fall back to the matching skills when agents are unavailable.

| Agent | File | Skills Used | |-------|------|-------------| | geo-ai-visibility | agents/geo-ai-visibility.toml | geo-citability, geo-crawlers, geo-llmstxt, geo-brand-mentions | | geo-platform-analysis | agents/geo-platform-analysis.toml | geo-platform-optimizer | | geo-technical | agents/geo-technical.toml | geo-technical | | geo-content | agents/geo-content.toml | geo-content | | geo-schema | agents/geo-schema.toml | geo-schema |

---

Output Files

All invocations generate structured output:

| Invocation | Output File | |---------|------------| | $geo-audit | GEO-AUDIT-REPORT.md | | $geo page | GEO-PAGE-ANALYSIS.md | | $geo-citability | GEO-CITABILITY-SCORE.md | | $geo-crawlers | GEO-CRAWLER-ACCESS.md | | $geo-llmstxt | llms.txt (ready to deploy) | | $geo-brand-mentions | GEO-BRAND-MENTIONS.md | | $geo-platform-optimizer | GEO-PLATFORM-OPTIMIZATION.md | | $geo-schema | GEO-SCHEMA-REPORT.md + generated JSON-LD | | $geo-technical | GEO-TECHNICAL-AUDIT.md | | $geo-content | GEO-CONTENT-ANALYSIS.md | | $geo-report | GEO-CLIENT-REPORT.md (presentation-ready) | | $geo-report-pdf | GEO-REPORT.pdf (professional PDF with charts) | | $geo quick | Inline summary (no file) | | $geo-prospect | Updates ~/.geo-prospects/prospects.json | | $geo-proposal | ~/.geo-prospects/proposals/-proposal-.md | | $geo-compare | ~/.geo-prospects/reports/-monthly-.md |

---

PDF Report Generation

The $geo-report-pdf invocation converts GEO-AUDIT-REPORT.md into a styled, client-ready PDF.

Requirements

• pandoc — install with Homebrew, Chocolatey, Scoop, apt, or your platform package manager
• Chrome/Chromium-compatible browser — Google Chrome, Microsoft Edge, Chromium, or Brave

No Python dependencies required for PDF generation.

What the PDF Includes

• Cover page — dark navy gradient, GEO score badge, brand/domain/date/location metadata
• Color-coded score tables — cells with XX/100 values are automatically colored green/blue/amber/orange/red
• Severity-tagged findings — Critical/High/Medium/Low sections get colored left-border callout blocks
• Section page breaks — major sections break to new pages automatically
• Styled code blocks — JSON schema templates render with dark monospace theme

Templates

Bundled under ${GEO_ROOT}/templates/:

• geo-report-style.css — stylesheet (edit colors, fonts, layout here)
• geo-report-template.html — pandoc HTML template (edit cover fields here)

Workflow

1. Run $geo-audit to produce GEO-AUDIT-REPORT.md
2. Run $geo-report-pdf — extracts metadata from the report and runs:

```bash pandoc GEO-AUDIT-REPORT.md \ --to html5 --standalone --embed-resources \ --template "$GEOROOT/templates/geo-report-template.html" \ --css "$GEOROOT/templates/geo-report-style.css" \ --metadata brandname="..." --metadata geoscore="..." \ -o GEO-REPORT.html

"$GEO_CHROME" \ --headless=new --disable-gpu --no-sandbox \ --print-to-pdf="$(pwd)/GEO-REPORT.pdf" \ --print-to-pdf-no-header --no-pdf-header-footer \ --virtual-time-budget=5000 \ "file://$(pwd)/GEO-REPORT.html" ```

1. Output: GEO-REPORT.pdf in the current directory

---

Quality Gates

• Crawl limit: Max 50 pages per audit (focus on quality over quantity)
• Timeout: 30 seconds per page fetch
• Rate limiting: 1-second delay between requests, max 5 concurrent
• Robots.txt: Always respect, always check
• Duplicate detection: Skip pages with >80% content similarity

---

Quick Start Examples

# Full GEO audit of a website
$geo-audit https://example.com

# Check if AI bots can see your site
$geo-crawlers https://example.com

# Score a specific page for AI citability
$geo-citability https://example.com/blog/best-article

# Generate an llms.txt file for your site
$geo-llmstxt https://example.com

# Get a 60-second visibility snapshot
$geo quick https://example.com

# Generate a client-ready report
$geo-report https://example.com

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bytefer
• Source: bytefer/geo-seo-codex
• License: MIT
• Homepage: https://www.bestalternative.dev/

Install and usage instructions live in the source repository linked above.