# Technical Documentation: zubair-trabzada/geo-seo-claude > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/zubair-trabzada/geo-seo-claude) ### Overview (`README.md`)

GEO-SEO Claude Code Skill

GEO-first, SEO-supported. Optimize websites for AI-powered search engines
(ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) while maintaining traditional SEO foundations.

AI search is eating traditional search. This tool optimizes for where traffic is going, not where it was.

--- ## Star History Star History Chart --- ## Why GEO Matters (2026) | Metric | Value | |--------|-------| | GEO services market | $850M+ (projected $7.3B by 2031) | | AI-referred traffic growth | +527% year-over-year | | AI traffic conversion rate vs organic | 4.4x higher | | Gartner: search traffic drop by 2028 | -50% | | Brand mentions vs backlinks for AI | 3x stronger correlation | | Marketers investing in GEO | Only 23% | --- ## Quick Start ### One-Command Install (macOS/Linux) ```bash curl -fsSL https://raw.githubusercontent.com/zubair-trabzada/geo-seo-claude/main/install.sh | bash ``` ### Manual Install ```bash git clone https://github.com/zubair-trabzada/geo-seo-claude.git cd geo-seo-claude ./install.sh ``` ### Windows (Git Bash) Requires [Git for Windows](https://git-scm.com/downloads) which includes Git Bash. ```bash # Option 1: One-command install (run from Git Bash, not PowerShell/CMD) curl -fsSL https://raw.githubusercontent.com/zubair-trabzada/geo-seo-claude/main/install-win.sh | bash # Option 2: Manual install git clone https://github.com/zubair-trabzada/geo-seo-claude.git cd geo-seo-claude ./install-win.sh ``` > **Note:** Right-click the folder and select "Open Git Bash here", or open Git Bash and navigate to the directory. Do not use PowerShell or Command Prompt. ### Requirements - Python 3.10+ (on Debian/Ubuntu also `python3-venv`) - Claude Code CLI - Git - Optional: [`uv`](https://docs.astral.sh/uv/) — if present, the installer uses it for a faster dependency install - Optional: Playwright (for screenshots) ### Isolated install Python dependencies are installed into a dedicated virtual environment at `~/.claude/skills/geo/.venv/`. Your system Python is **not** touched, and uninstalling the skill removes the venv together with the rest of the files. Skill and agent files reference that venv directly, so the tool works regardless of what `python3` resolves to on your `PATH`. --- ## Commands Open Claude Code and use these commands: | Command | What It Does | |---------|-------------| | `/geo audit ` | Full GEO + SEO audit with parallel subagents | | `/geo quick ` | 60-second GEO visibility snapshot | | `/geo citability ` | Score content for AI citation readiness | | `/geo crawlers ` | Check AI crawler access (robots.txt) | | `/geo llmstxt ` | Analyze or generate llms.txt | | `/geo brands ` | Scan brand mentions across AI-cited platforms | | `/geo platforms ` | Platform-specific optimization | | `/geo schema ` | Structured data analysis & generation | | `/geo technical ` | Technical SEO audit | | `/geo content ` | Content quality & E-E-A-T assessment | | `/geo report ` | Generate client-ready GEO report | | `/geo report-pdf` | Generate professional PDF report with charts & visualizations | --- ## Architecture ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ## Data Storage The CRM and reporting skills (`/geo prospect`, `/geo proposal`, `/geo compare`) store runtime data outside the Claude Code directory: ``` ~/.geo-prospects/ ├── prospects.json # Client/prospect pipeline data ├── proposals/ # Generated proposal documents │ └── -proposal-.md └── reports/ # Monthly delta reports └── -monthly-.md ``` This directory is **not removed** by the uninstaller — delete it manually if you no longer need your prospect data. --- ## How It Works ### Full Audit Flow When you run `/geo audit https://example.com`: 1. **Discovery** — Fetches homepage, detects business type, crawls sitemap 2. **Parallel Analysis** — Launches 5 subagents simultaneously: - AI Visibility (citability, crawlers, llms.txt, brand mentions) - Platform Analysis (ChatGPT, Perplexity, Google AIO readiness) - Technical SEO (Core Web Vitals, SSR, security, mobile) - Content Quality (E-E-A-T, readability, freshness) - Schema Markup (detection, validation, generation) 3. **Synthesis** — Aggregates scores, generates composite GEO Score (0-100) 4. **Report** — Outputs prioritized action plan with quick wins ### Scoring Methodology | Category | Weight | |----------|--------| | AI Citability & Visibility | 25% | | Brand Authority Signals | 20% | | Content Quality & E-E-A-T | 20% | | Technical Foundations | 15% | | Structured Data | 10% | | Platform Optimization | 10% | --- ## Key Features ### Citability Scoring Analyzes content blocks for AI citation readiness. Optimal AI-cited passages are 134-167 words, self-contained, fact-rich, and directly answer questions. ### AI Crawler Analysis Checks robots.txt for 14+ AI crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.) and provides specific allow/block recommendations. ### Brand Mention Scanning Brand mentions correlate 3x more strongly with AI visibility than backlinks. Scans YouTube, Reddit, Wikipedia, LinkedIn, and 7+ other platforms. ### Platform-Specific Optimization Only 11% of domains are cited by both ChatGPT and Google AI Overviews for the same query. Provides tailored recommendations per platform. ### llms.txt Generation Generates the emerging llms.txt standard file that helps AI crawlers understand your site structure. ### Client-Ready Reports Generates professional GEO reports in markdown or PDF format. PDF reports include score gauges, bar charts, platform readiness visualizations, color-coded tables, and prioritized action plans — ready to deliver to clients. --- ## Use Cases - **GEO Agencies** — Run client audits and generate deliverables - **Marketing Teams** — Monitor and improve AI search visibility - **Content Creators** — Optimize content for AI citations - **Local Businesses** — Get found by AI assistants - **SaaS Companies** — Improve entity recognition across AI platforms - **E-commerce** — Optimize product pages for AI shopping recommendations --- ## Uninstall ```bash ./uninstall.sh ``` Or manually: ```bash rm -rf ~/.claude/skills/geo ~/.claude/skills/geo-* ~/.claude/agents/geo-*.md ``` --- ## Want to Turn This Into a Business? The tool is free. Learning how to monetize it is where the community comes in. **[Join the AI Workshop Community →](https://skool.com/aiworkshop)** Inside you'll get: - **Video walkthroughs** — Step-by-step setup, running audits, reading results - **Client acquisition playbook** — How to find prospects, pitch GEO services, and close deals - **Live office hours** — Bring your audit results, get direct help - **GEO agency pricing & templates** — Proposal docs, cold outreach scripts, onboarding workflows GEO agencies charge $2K–$12K/month. This tool does the audit. The community teaches you how to sell it. --- ## License MIT License --- ## Contributing Contributions welcome! --- Built for the AI search era. --- ### Overview (`docs/README.md`) # GEO-SEO Claude Code Skill — Documentation `geo-seo-claude` is a Claude Code skill bundle that runs GEO (Generative Engine Optimization) and SEO audits against a website. It orchestrates 13 sub-skills, 5 parallel subagents, and a set of Python utilities to produce a composite GEO Score (0–100) and a prioritized action plan. If you are new here, start with **Getting Started**. If you are contributing, skim **Architecture** and **Skills & Agents** first. ## Contents | Doc | What's in it | |-----|--------------| | [Getting Started](getting-started.md) | Prerequisites, install (macOS/Linux/Windows), first audit, troubleshooting, uninstall. | | [Commands Reference](commands-reference.md) | Every `/geo` slash command with usage, arguments, output, and when to use it. | | [Architecture](architecture.md) | Repo layout, audit flow, parallel subagent dispatch, data storage. | | [Skills & Agents](skills-and-agents.md) | Reference for every sub-skill, subagent, Python script, and schema template. | | [Scoring Methodology](scoring-methodology.md) | How the composite GEO Score is computed, per-category signals, caveats. | | [FAQ](faq.md) | Common questions for users and contributors. | | [Contributing](../CONTRIBUTING.md) | How to report bugs, propose features, and open PRs. | ## Quick links - First audit: [Getting Started → Your First Audit](getting-started.md#your-first-audit) - Full command list: [Commands Reference](commands-reference.md) - Weight table: [Scoring Methodology](scoring-methodology.md) - Parallel audit flow: [Architecture → Full Audit Flow](architecture.md) --- ### Overview (`white-label/README.md`) # White-Label Branding for GEO Reports A small, framework-agnostic helper that lets agencies and resellers rebrand the GEO reports they generate — agency name, contact details, and colors — from a single `brand.json` file, **without editing any generator code**. This is useful because GEO agencies built on this tool typically deliver reports under their own brand. Today that means editing colors in the generator by hand; this drops that into one config file each reseller can keep. ## How it works `brand_config.py` exposes one function, `load_brand()`, that returns a plain dict and deep-merges an optional `brand.json` over sensible defaults: ```python from brand_config import load_brand brand = load_brand("brand.json") # or load_brand() for defaults agency = brand["name"] # "Your Agency Inc." primary = brand["colors"]["primary"] # "#19C3B2" contact = brand["contact_name"] ``` Because it's just a dict, you can feed it into any report generator — ReportLab, HTML/Playwright, or anything else — wherever you currently hard-code colors or a company name. ## Config Copy `brand.example.json` to `brand.json` and edit. Any field you omit keeps its default, so a reseller can override as little as a single color: ```json { "name": "Your Agency Inc.", "website": "youragency.com", "phone": "555-123-4567", "contact_name": "Your Name", "colors": { "primary": "#19C3B2", "text_accent": "#19C3B2" } } ``` Keys: `name`, `cover_tag`, `website`, `phone`, `contact_name`, and a `colors` object (merged key-by-key). Keys starting with `_` (like `_comment`) are ignored. ## Try it ```bash python brand_config.py brand.json # prints the merged brand dict ``` ## Credit Contributed as a thank-you by Millisa Nwokolo (La Crown Inc.), built on top of the GEO-SEO Claude engine by Zubair Trabzada. MIT licensed. --- ### Getting Started (`docs/getting-started.md`) # Getting Started ## Prerequisites | Requirement | Why it's needed | |---|---| | Python 3.10+ | Runs the utility scripts (page fetching, citability scoring, PDF generation, etc.) | | Claude Code CLI | The skills and agents are loaded and invoked through Claude Code | | Git | Used by the installer to clone the repository | | Playwright (optional) | Enables screenshot capture; install separately after the main install | Install Claude Code if you haven't already: ```bash npm install @anthropic-ai/claude-code ``` --- ## Installation ### macOS / Linux — one-liner ```bash curl -fsSL https://raw.githubusercontent.com/zubair-trabzada/geo-seo-claude/main/install.sh | bash ``` ### macOS / Linux — manual ```bash git clone https://github.com/zubair-trabzada/geo-seo-claude.git cd geo-seo-claude ./install.sh ``` ### Windows — Git Bash PowerShell and Command Prompt are not supported. You must use [Git Bash](https://git-scm.com/downloads) (included with Git for Windows). ```bash # One-liner (run from Git Bash) curl -fsSL https://raw.githubusercontent.com/zubair-trabzada/geo-seo-claude/main/install-win.sh | bash # Manual git clone https://github.com/zubair-trabzada/geo-seo-claude.git cd geo-seo-claude ./install-win.sh ``` Right-click the cloned folder and choose "Open Git Bash here", or navigate to it inside an existing Git Bash session. ### What the installer does - Copies the `geo` orchestrator skill to `~/.claude/skills/geo/` - Copies 13 sub-skills to `~/.claude/skills/geo-*/` - Copies 5 subagent definitions to `~/.claude/agents/` - Installs Python dependencies via `pip install --user` - Optionally installs the Playwright Chromium browser for screenshots --- ## Verify the Install After installation, open Claude Code in any project directory and run: ``` /geo quick https://example.com ``` If the skill is wired up correctly, Claude Code will start a 60-second GEO visibility snapshot. If you see "unknown command" or nothing happens, restart Claude Code — it reads skills and agents at startup. To confirm the files landed in the right place: ```bash ls ~/.claude/skills/geo/ ls ~/.claude/skills/ | grep geo ls ~/.claude/agents/ | grep geo ``` --- ## Your First Audit ### Quick path — 60-second snapshot ``` /geo quick https://yoursite.com ``` Returns a high-level GEO visibility score and the top issues. Good for a first look or a fast client check. ### Full path — complete audit ``` /geo audit https://yoursite.com ``` Launches 5 parallel subagents covering AI visibility, platform optimization, technical SEO, content quality, and structured data. Produces a prioritized action plan with a composite GEO score (0–100). The full audit takes several minutes depending on the site. See [scoring-methodology.md](scoring-methodology.md) for how the score is calculated and [commands-reference.md](commands-reference.md) for all available commands. --- ## Troubleshooting **Python not found during install** - Symptom: installer exits with `Python 3.10+ is required but not found` - Cause: Python is not installed or not on `PATH` - Fix: install from [python.org](https://www.python.org/downloads/); on Windows check "Add Python to PATH" during setup; then reopen your terminal **Claude Code CLI not found** - Symptom: installer warns `Claude Code CLI not found in PATH` - Cause: `claude` is not installed or not on `PATH` - Fix: `npm install @anthropic-ai/claude-code`; confirm with `claude --version` **Skills not showing up in Claude Code** - Symptom: `/geo quick` produces "unknown command" or no response - Cause: Claude Code reads skills at startup; it won't see files added after launch - Fix: fully quit and reopen Claude Code **Permission denied on `./install.sh`** - Symptom: `bash: ./install.sh: Permission denied` - Cause: execute bit not set - Fix: `chmod +x install.sh && ./install.sh` **Wrong shell on Windows** - Symptom: `curl` not recognized, or script syntax errors - Cause: running `install-win.sh` in PowerShell or Command Prompt - Fix: use Git Bash only — right-click the folder, "Open Git Bash here" **Playwright not available / screenshots missing** - Symptom: screenshot-related steps silently skip or error - Cause: Playwright was skipped during install (non-interactive or answered no) - Fix: install it manually: ```bash python3 -m playwright install chromium ``` **Python dependencies failed during install** - Symptom: installer prints `Some Python dependencies failed to install` - Cause: pip error (network, permissions, or virtualenv conflict) - Fix: run manually from the cloned repo or from `~/.claude/skills/geo/`: ```bash python3 -m pip install --user -r requirements.txt ``` --- ## Uninstall ### Scripted Run from the cloned repository directory: ```bash ./uninstall.sh ``` This removes `~/.claude/skills/geo/`, all `~/.claude/skills/geo-*/` sub-skills, and all `~/.claude/agents/geo-*.md` agent files. Python packages are not removed. ### Manual ```bash rm -rf ~/.claude/skills/geo ~/.claude/skills/geo-* ~/.claude/agents/geo-*.md ``` ### Runtime data The directory `~/.geo-prospects/` (used by `/geo prospect`, `/geo proposal`, and `/geo compare`) is **not** removed by the uninstaller. Delete it manually if you no longer need the data: ```bash rm -rf ~/.geo-prospects ``` --- See also: [architecture.md](architecture.md) | [commands-reference.md](commands-reference.md) | [scoring-methodology.md](scoring-methodology.md) | [skills-and-agents.md](skills-and-agents.md) --- ### Architecture (`docs/architecture.md`) # Architecture & Design The repository is structured to seamlessly provide GEO+SEO support by using Claude's tool capabilities alongside agents and python utility scripts. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Full Audit Flow When you run `/geo audit https://example.com`: 1. **Discovery** — Fetches homepage, detects business type, crawls sitemap 2. **Parallel Analysis** — Launches 5 subagents simultaneously: - AI Visibility (citability, crawlers, llms.txt, brand mentions) - Platform Analysis (ChatGPT, Perplexity, Google AIO readiness) - Technical SEO (Core Web Vitals, SSR, security, mobile) - Content Quality (E-E-A-T, readability, freshness) - Schema Markup (detection, validation, generation) 3. **Synthesis** — Aggregates scores, generates composite GEO Score (0-100) 4. **Report** — Outputs prioritized action plan with quick wins ### Data Storage The CRM and reporting skills (`/geo prospect`, `/geo proposal`, `/geo compare`) store runtime data outside the Claude Code directory: ``` ~/.geo-prospects/ ├── prospects.json # Client/prospect pipeline data ├── proposals/ # Generated proposal documents │ └── -proposal-.md └── reports/ # Monthly delta reports └── -monthly-.md ``` This directory is **not removed** by the uninstaller — delete it manually if you no longer need your prospect data. --- ### Commands Reference (`docs/commands-reference.md`) # Commands Reference This file documents every command in the `geo-seo-claude` skill bundle. Commands are invoked inside Claude Code using the `/geo` prefix. The main skill at `geo/SKILL.md` acts as a router: it reads the first argument after `/geo` and delegates to the matching sub-skill under `skills/`. All commands accept a URL as their primary argument; CRM commands operate on domain names or prospect IDs instead. Every command that produces a score references the weighting model described in [scoring-methodology.md](scoring-methodology.md). The parallel subagent architecture used by `/geo audit` is described in [architecture.md](architecture.md). --- ## Command categories **Audit** — full-site and focused analysis | Command | Description | |---------|-------------| | `/geo audit ` | Full GEO + SEO audit with parallel subagents | | `/geo quick ` | 60-second GEO visibility snapshot | | `/geo citability ` | Score a single page for AI citation readiness | | `/geo crawlers ` | Check AI crawler access via robots.txt and meta tags | | `/geo llmstxt ` | Analyze an existing llms.txt or generate one from scratch | | `/geo brands ` | Scan brand mentions across AI-cited platforms | | `/geo platforms ` | Platform-specific readiness scores (AIO, ChatGPT, Perplexity, Gemini, Copilot) | **Diagnostics** — targeted technical and content checks | Command | Description | |---------|-------------| | `/geo schema ` | Detect, validate, and generate Schema.org structured data | | `/geo technical ` | Technical SEO audit with GEO-specific checks | | `/geo content ` | Content quality and E-E-A-T assessment | **Reports** — client-ready deliverables | Command | Description | |---------|-------------| | `/geo report ` | Generate a client-ready GEO report in Markdown | | `/geo report-pdf ` | Generate a professional PDF report with charts and visualizations | **CRM** — prospect and client pipeline management | Command | Description | |---------|-------------| | `/geo prospect ` | Manage prospects through the sales pipeline | | `/geo proposal ` | Auto-generate a client proposal from audit data | | `/geo compare ` | Monthly delta report showing score improvements | --- ## /geo audit Performs a comprehensive GEO + SEO audit of a website using five parallel subagents. **Usage** ``` /geo audit https://example.com ``` **What it does** - Phase 1 (sequential): fetches the homepage, detects business type (SaaS, Local, E-commerce, Publisher, Agency), and crawls up to 50 pages from the sitemap or internal links. - Phase 2 (parallel): delegates to five specialized subagents simultaneously — AI visibility, platform analysis, technical SEO, content E-E-A-T, and schema markup. See [architecture.md](architecture.md) for the subagent flow. - Phase 3 (sequential): aggregates subagent scores into a weighted composite GEO Score (0–100). See [scoring-methodology.md](scoring-methodology.md) for the weighting formula. - Classifies every issue by severity: Critical, High, Medium, or Low. - Produces a 30-day action plan with weekly themes. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Homepage URL of the site to audit | **Output** Writes `GEO-AUDIT-REPORT.md` to the working directory. Contains: executive summary, score breakdown table, per-category deep dives, issue list by severity, quick wins, and a week-by-week 30-day action plan. Inline summary is also printed to the terminal. **When to use it** Run this first for any new client or site; it is the entry point for all other analysis. --- ## /geo quick Delivers a 60-second GEO visibility snapshot without writing any output file. **Usage** ``` /geo quick https://example.com ``` **What it does** - Fetches the homepage and a small sample of key pages. - Runs a lightweight pass across the main GEO signals: AI crawler access, llms.txt presence, schema on the homepage, and a rough citability read on the hero content. - Produces an approximate GEO score and a short list of the highest-impact gaps. - Feeds directly into `/geo prospect audit` when called from the CRM workflow. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | URL to snapshot | **Output** Inline terminal summary only — no file is written. Score is stored in the prospect record when invoked via `/geo prospect audit`. **When to use it** Use this for a fast qualification check before committing to a full audit, or when the `/geo prospect audit` subcommand calls it automatically. --- ## /geo citability Scores a single page for AI citation readiness using a five-dimension rubric. **Usage** ``` /geo citability https://example.com/blog/my-article ``` **What it does** - Fetches the page and segments content into blocks at each H2/H3 boundary. - Scores each block across: answer block quality (30%), passage self-containment (25%), structural readability (20%), statistical density (15%), and uniqueness/original data (10%). - Identifies the top three strongest and the three weakest blocks. - Generates specific rewrite suggestions — including a suggested opening sentence — for every block scoring below 60. See [scoring-methodology.md](scoring-methodology.md) for the rubric detail. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | URL of the specific page to score | **Output** Writes `GEO-CITABILITY-SCORE.md`. Contains: overall citability score, weighted score table, strongest/weakest block analysis with quoted excerpts, rewrite suggestions, and a per-section score table. **When to use it** Use this on any content page before publishing, or to prioritize which existing pages to rewrite for AI citation. --- ## /geo crawlers Analyzes which AI crawlers can access the site and provides a recommended robots.txt configuration. **Usage** ``` /geo crawlers https://example.com ``` **What it does** - Fetches and parses `robots.txt`, mapping every User-agent directive to the 14 known AI crawlers. - Checks a sample of key pages for `` overrides and `X-Robots-Tag` HTTP headers. - Detects Cloudflare's managed robots.txt, which silently prepends AI crawler blocks to the site's own file. - Checks for the presence of `/llms.txt` and `/.well-known/ai-plugin.json`. - Assesses whether key content requires JavaScript rendering (AI crawlers do not execute JS). - Scores crawler access in three tiers: Tier 1 (ChatGPT, Claude, Perplexity — critical for AI search), Tier 2 (Gemini, Copilot, Apple Intelligence, Meta AI), and Tier 3 (training-only crawlers). **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain root URL | **Output** Writes `GEO-CRAWLER-ACCESS.md`. Contains: access summary table per crawler, an AI visibility score (0–100), critical issues list, and a complete ready-to-paste robots.txt block configured for maximum AI visibility. **When to use it** Use this as a quick standalone check when a client reports they are not appearing in AI search results, or to verify a robots.txt change before deploying. --- ## /geo llmstxt Analyzes an existing `llms.txt` file for quality, or generates a new one from scratch if none exists. **Usage** ``` /geo llmstxt https://example.com ``` **What it does** - Fetches `https://example.com/llms.txt` and `llms-full.txt` and checks HTTP status. - **Analysis mode** (file exists): validates format (H1 title, blockquote description, H2 sections, absolute URLs, entry descriptions, Key Facts, Contact section); scores completeness (40%), accuracy (35%), and usefulness (25%); identifies important pages missing from the file. - **Generation mode** (file absent): crawls the sitemap and homepage, prioritizes pages by type, writes 10-30 word descriptions for each selected page, gathers key business facts, and assembles a complete `llms.txt` ready to deploy. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain root URL | **Output** - Analysis mode: writes `GEO-LLMSTXT-ANALYSIS.md` with validation results, missing pages, and a suggested updated file. - Generation mode: writes the ready-to-deploy `llms.txt` file and a brief `GEO-LLMSTXT-GENERATION.md` summarizing prioritization decisions. **When to use it** Use this on any site to either validate an existing `llms.txt` or produce a new one. Fewer than 5% of sites had an `llms.txt` as of early 2026, making it an accessible quick win. --- ## /geo brands Scans brand mentions across the platforms AI systems rely on for entity recognition and citation decisions. **Usage** ``` /geo brands https://example.com ``` **What it does** - Checks brand presence on YouTube (channel existence, subscriber count, third-party video mentions), Reddit (thread volume, sentiment, official presence, subreddit), Wikipedia/Wikidata (article existence, Wikidata Q-number, quality class), and LinkedIn (company page, follower count, post frequency). - Uses the Wikipedia API directly (`en.wikipedia.org/w/api.php`) to avoid false negatives from web search. - Also scans supplementary platforms: Quora, Stack Overflow, GitHub, Hacker News, and press/news. - Calculates a composite Brand Authority Score: YouTube 25%, Reddit 25%, Wikipedia/Wikidata 20%, LinkedIn 15%, other platforms 15%. See [scoring-methodology.md](scoring-methodology.md). **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain URL (brand name is inferred from the site) | **Output** Writes `GEO-BRAND-MENTIONS.md`. Contains: Brand Authority Score (0–100), per-platform breakdown tables, sentiment assessment, competitive context table (if competitors are identified), and prioritized recommendations grouped by time horizon (week 1–2, month 1–3, month 3–12). **When to use it** Use this when a site has technically sound content but is not appearing in AI-generated recommendations, or as part of an entity-building strategy. --- ## /geo platforms Audits readiness for each major AI search platform individually and produces per-platform scores. **Usage** ``` /geo platforms https://example.com ``` **What it does** - Runs a separate checklist and scoring rubric for each of five platforms: Google AI Overviews, ChatGPT Web Search, Perplexity AI, Google Gemini, and Bing Copilot. - Google AIO checklist covers: top-10 organic ranking, question-based headings, direct answer structure, tables, FAQ sections, statistics with attribution, author bylines, and publication dates. - ChatGPT checklist covers: Wikipedia/Wikidata entity, Bing index coverage, Reddit mentions, YouTube presence, entity consistency, and content comprehensiveness. - Perplexity checklist covers: Reddit presence, forum mentions, content freshness, original research, quotable paragraphs, and multi-source claim validation. - Gemini checklist covers: Google Knowledge Panel, Google Business Profile, YouTube strategy, Schema.org markup, and Google ecosystem presence. - Copilot checklist covers: Bing Webmaster Tools, IndexNow implementation, LinkedIn page, meta descriptions, and page load speed. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Homepage URL of the site | **Output** Writes `GEO-PLATFORM-OPTIMIZATION.md`. Contains: an overall combined score, per-platform score table, per-platform gap analysis with specific actions, and a prioritized action plan (quick wins, medium-term, strategic). See [scoring-methodology.md](scoring-methodology.md) for platform weight in the composite score. **When to use it** Use this when you need to know which specific AI platforms a site is underperforming on, or to build a platform-targeted optimization roadmap. --- ## /geo schema Detects all structured data on a site, validates it against Schema.org specifications, and generates ready-to-paste JSON-LD blocks for missing or incomplete schemas. **Usage** ``` /geo schema https://example.com ``` **What it does** - Fetches raw HTML using `fetch_page.py` (not WebFetch, which strips `` content) to extract all JSON-LD, Microdata, and RDFa blocks. - Validates each schema: JSON syntax, valid `@type`, required properties, recommended properties, `sameAs` links, URL validity, nesting, and whether the schema is server-rendered or JS-injected. - Checks for GEO-critical schema types: Organization, LocalBusiness, Article with Author, Product, FAQPage, SoftwareApplication, WebSite with SearchAction, and BreadcrumbList. - Audits the `sameAs` property against a priority list of 14 platforms (Wikipedia, Wikidata, LinkedIn, YouTube, Twitter/X, GitHub, Crunchbase, etc.). - Generates complete JSON-LD code blocks using the `@graph` pattern for any missing or incomplete schemas. See [scoring-methodology.md](scoring-methodology.md) for how schema score feeds the composite GEO Score. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | URL of the page or domain to audit | **Output** Writes `GEO-SCHEMA-REPORT.md`. Contains: schema score (0–100), detected schemas table, per-property validation results, missing schema list, sameAs audit table, and ready-to-paste JSON-LD code blocks with implementation notes. **When to use it** Use this to give a developer team a self-contained implementation ticket, or to verify schema quality after a CMS migration. --- ## /geo technical Performs a technical SEO audit across eight categories with special emphasis on server-side rendering and AI crawler access. **Usage** ``` /geo technical https://example.com ``` **What it does** - Crawlability (15 pts): robots.txt validity, AI crawler access for 11 named bots, XML sitemap presence and validity, crawl depth, noindex directives. - Indexability (12 pts): canonical tags, duplicate content (www/HTTP/trailing-slash), pagination, hreflang. - Security (10 pts): HTTPS enforcement, HSTS, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, CSP. - URL structure (8 pts): clean readable URLs, logical hierarchy, redirect chains, parameter handling. - Mobile optimization (10 pts): viewport meta tag, responsive layout, tap target sizing, font legibility. - Core Web Vitals (15 pts): LCP < 2.5s, INP < 200ms, CLS < 0.1 using 2026 thresholds. - Server-side rendering (15 pts): compares `curl` output to rendered DOM; flags client-rendered content that AI crawlers cannot read. - Page speed and server performance (15 pts): TTFB, page weight, image optimization, JS bundle size, compression, caching, CDN. See [scoring-methodology.md](scoring-methodology.md) for how the technical score feeds the composite. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain root URL | **Output** Writes `GEO-TECHNICAL-AUDIT.md`. Contains: technical score (0–100), per-category score table with Pass/Warn/Fail status, AI crawler access table, critical issues list, warnings, and recommendations. **When to use it** Use this when a site's content is strong but AI visibility is poor, or to produce a developer-facing remediation checklist. --- ## /geo content Evaluates content quality through the E-E-A-T framework (Experience, Expertise, Authoritativeness, Trustworthiness) and assesses AI citability and topical authority. **Usage** ``` /geo content https://example.com ``` **What it does** - Scores each of the four E-E-A-T dimensions on a 25-point scale: Experience (first-person accounts, original data, case studies), Expertise (author credentials, technical depth, methodology, data-backed claims), Authoritativeness (inbound citations, press mentions, awards, Wikipedia presence), Trustworthiness (contact info, privacy policy, HTTPS, editorial standards, accurate claims). - Applies a topical authority modifier: +10 for 20+ pages with strong clustering, down to −5 for fewer than 5 pages on the topic. - Assesses content freshness for each page (< 3 months through no-date/24+ months). - Flags low-quality AI-generated content patterns (generic phrasing, no original insight, hedging overload) and identifies high-quality signals. - Checks word count benchmarks per page type and paragraph structure for AI extraction. See [scoring-methodology.md](scoring-methodology.md) for how content score feeds the composite. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain root URL (analyzes homepage plus key content pages) | **Output** Writes `GEO-CONTENT-ANALYSIS.md`. Contains: content score (0–100), E-E-A-T breakdown table, pages-analyzed table, detailed findings per dimension, content quality issues with rewrite suggestions, AI content concerns, freshness assessment, most and least citable passages, content gap recommendations, and E-E-A-T improvement steps. **When to use it** Use this when a site has good technical fundamentals but is not being cited by AI systems, indicating a content quality problem. --- ## /geo report Aggregates outputs from all audit skills into a single professional, client-facing Markdown report. **Usage** ``` /geo report https://example.com ``` **What it does** - Reads existing `GEO-*.md` audit files from the working directory; runs missing audits automatically if needed. - Calculates a composite GEO Readiness Score: AI Platform Readiness 25%, Content E-E-A-T 25%, Technical Foundation 20%, Schema 15%, Brand Authority 15%. See [scoring-methodology.md](scoring-methodology.md). - Translates all technical findings into business-impact language aimed at owners and marketing leaders, not developers. - Produces 12 structured sections: executive summary, score dashboard, AI visibility dashboard (per platform), AI crawler access table, brand authority analysis, citability analysis (top 5 / bottom 5 pages), technical health summary, schema status, llms.txt status, prioritized action plan (quick wins / medium / strategic), competitor comparison (if competitors were analyzed), and glossary appendix. - Includes conservative traffic and revenue impact estimates tied to score improvements. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain URL; existing audit files in the working directory are consumed automatically | **Output** Writes `GEO-CLIENT-REPORT.md`. The report is 3,000–6,000 words, self-contained, and ready to deliver without further editing. **When to use it** Use this to produce the final deliverable after running the full audit suite, or at the end of each monthly engagement cycle. --- ## /geo report-pdf Converts GEO audit data into a professionally formatted PDF with charts, score gauges, and color-coded tables. **Usage** ``` /geo report-pdf https://example.com ``` **What it does** - Checks the working directory for existing `GEO-CLIENT-REPORT.md` or `GEO-AUDIT-REPORT.md`; if none are found, runs a full audit first. - Parses the Markdown report to extract scores, platform readiness numbers, crawler status, findings, and action items. - Assembles the data into the JSON schema expected by the PDF generation script. - Calls `python3 ~/.claude/skills/geo/scripts/generate_pdf_report.py` (requires `pip install reportlab`). - The PDF uses US Letter size with a navy/blue/coral color palette; score gauges use traffic-light colors (green 80+, blue 60–79, yellow 40–59, red below 40). **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain URL; used to locate or generate audit data | **Output** Writes `GEO-REPORT-.pdf` to the working directory. The PDF contains: cover page with score gauge, executive summary, score breakdown bar chart, AI platform readiness horizontal bar chart, crawler access color-coded table, key findings by severity, prioritized action plan, and a methodology/glossary appendix. File path and size are reported on completion. **When to use it** Use this when the deliverable needs to be emailed directly to a client who expects a polished document rather than a Markdown file. --- ## /geo prospect A CRM-lite pipeline manager for tracking prospects and clients from initial discovery through contract. **Usage** ``` /geo prospect new /geo prospect list [] /geo prospect show /geo prospect audit /geo prospect note "" /geo prospect status /geo prospect won /geo prospect lost "" /geo prospect pipeline ``` **What it does** - Stores all prospect data in `~/.geo-prospects/prospects.json` as persistent JSON records containing ID, company, domain, status, GEO score, audit file path, proposal file path, monthly contract value, and timestamped notes. - Tracks five pipeline stages: `lead`, `qualified`, `proposal`, `won`, `lost`. - `prospect audit` calls `/geo quick` and saves the resulting score to the prospect record. - `prospect pipeline` prints a revenue-focused summary showing committed MRR, pipeline value, and suggested next actions per record. - All subcommands print a confirmation and the current prospect status to the terminal; no external files are written except audit snapshots and proposals. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Subcommand: `new`, `list`, `show`, `audit`, `note`, `status`, `won`, `lost`, `pipeline` | | `` | Contextual | Prospect ID (e.g., `PRO-001`) or domain name | | `` | For `status`, `list` | Pipeline stage: `lead`, `qualified`, `proposal`, `won`, `lost` | | `` | For `won` | Numeric monthly contract value | | `""` | For `note`, `lost` | Free-text note or lost reason | **Output** Updates `~/.geo-prospects/prospects.json`. Audit snapshots saved to `~/.geo-prospects/audits/`. Terminal output for all subcommands. **When to use it** Use this to manage an ongoing GEO agency sales pipeline and track client history across sessions. --- ## /geo proposal Auto-generates a fully customized, client-ready GEO service proposal from audit data. **Usage** ``` /geo proposal /geo proposal --tier basic|standard|premium --client-name "Name" --monthly EUR ``` **Examples** ``` /geo proposal example.com /geo proposal example.com --tier standard --client-name "Acme Corp" /geo proposal ~/.geo-prospects/audits/example.com-2026-03-12.md ``` **What it does** - Loads the most recent audit file from `~/.geo-prospects/audits/*.md` (or runs `/geo quick` if none exists). - Selects a recommended service tier based on GEO score: 0–40 → Premium, 41–60 → Standard, 61–75 → Basic. - Populates a 12-section proposal template: executive summary, market context tables, audit findings, three-tier service packages with pricing (Basic €2,500/mo, Standard €5,000/mo, Premium €9,500/mo), ROI projection table, six-month engagement timeline, investment summary, and terms. - Updates the prospect record status to `proposal` and saves the proposal file path. **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes | Domain name or path to an audit file | | `--tier` | No | Force a specific tier instead of using score-based recommendation | | `--client-name` | No | Override the auto-detected company name | | `--monthly` | No | Override the estimated monthly contract value | **Output** Writes `~/.geo-prospects/proposals/-proposal-.md`. Prints confirmation with the recommended package and price. The proposal is ready to send without editing. **When to use it** Use this immediately after a prospect audit when the GEO score indicates a clear sales opportunity (score below 75). --- ## /geo compare Generates a monthly delta report comparing a baseline audit to a current audit, showing score improvements to the client. **Usage** ``` /geo compare /geo compare /geo compare --month march-2026 ``` **What it does** - Locates audit files in `~/.geo-prospects/audits/` matching the domain; uses the oldest as baseline and the newest as current. If only one file exists, runs a fresh quick audit as the current snapshot. - Extracts overall GEO score, all six category scores, all five platform scores, and AI crawler status from both files. - Calculates deltas and assigns trend symbols (▲▲ strong improvement, ▲ improvement, ── unchanged, ▼ decline, ▼▼ significant decline). - Tracks completion status of quick wins, medium-term, and strategic action items. - Includes a six-month trajectory table and a conservative business impact estimate (AI citation likelihood change, crawler coverage, estimated traffic value). **Inputs** | Argument | Required | Description | |----------|----------|-------------| | `` | Yes (or two file paths) | Domain name, or explicit paths to baseline and current audit files | | `--month` | No | Month label for the report filename | **Output** Writes `~/.geo-prospects/reports/-monthly-.md`. Prints a summary to the terminal showing score change, quick wins completion rate, new issues found, and whether the six-month target is on track. **When to use it** Run this on the first of each month for every active client to generate the progress report that justifies the retainer. --- ## Discrepancies The following discrepancies were found between `geo/SKILL.md` and the `skills/` directory: - **`/geo quick`**: Listed in `geo/SKILL.md` and referenced throughout the codebase (by `geo-prospect` and `geo-compare`), but there is no `skills/geo-quick/SKILL.md`. The quick-scan behavior is documented only through the orchestration instructions in `geo/SKILL.md` and the `geo-prospect` skill. This command is documented above based on those references. - **`/geo page`**: Listed in `geo/SKILL.md`'s quick reference table (as `/geo page ` — deep single-page GEO analysis) and in the output files table (produces `GEO-PAGE-ANALYSIS.md`), but there is no `skills/geo-page/SKILL.md`. No implementation exists. This command is **not documented** in the reference above because there is no skill file to draw from. - **`/geo quick` in original `docs/commands-reference.md`**: The old table listed `/geo quick` but `geo/SKILL.md` does not list it in the sub-skills table (only in the quick reference table). It is referenced as a real behavior in the prospect and compare skills, so it is retained above. --- ### Faq (`docs/faq.md`) # Frequently Asked Questions --- ## General ### What is GEO and how is it different from SEO? SEO (Search Engine Optimization) targets ranking in traditional search engines like Google's blue-link results. GEO (Generative Engine Optimization) targets visibility inside AI-generated answers from systems like ChatGPT, Perplexity, Claude, Gemini, and Google AI Overviews. The two disciplines overlap — technical foundations and content quality matter for both — but GEO adds concerns specific to AI retrieval: citability scoring, brand mention density, llms.txt, and entity recognition across AI-cited platforms. ### Is this a paid tool or service? The tool itself is free and MIT-licensed. It runs entirely within your own Claude Code session using your existing Anthropic subscription. There is no separate API key, usage meter, or subscription for the skill bundle itself. ### Who is this for? GEO agencies running client audits, in-house marketing teams monitoring AI search visibility, content creators optimizing individual pages for AI citations, and developers building or maintaining web properties who want actionable GEO and SEO feedback without a SaaS subscription. ### Does this replace my existing SEO stack? No. It complements existing tools. The `/geo technical` command covers technical SEO foundations, but the tool does not replace crawlers like Screaming Frog, keyword research platforms, or rank trackers. Its primary value is the GEO layer — AI citability, crawler access, brand signals, and platform readiness — that most traditional SEO tools do not cover. --- ## Installation & Setup ### Why do I need Claude Code CLI? The skill bundle is implemented as Claude Code slash commands. All commands (`/geo audit`, `/geo quick`, etc.) are routed through Claude Code's skill and agent system. The CLI is the runtime; without it, there is nothing to execute the skill files. Install it with `npm install @anthropic-ai/claude-code`. ### Can I run this on Windows without WSL? Yes, but you must use Git Bash, not PowerShell or Command Prompt. The Windows installer is `install-win.sh` and requires Git for Windows (which bundles Git Bash). Right-click the repo folder and select "Open Git Bash here", then run `./install-win.sh`. WSL is not required. ### What does `install.sh` actually do? It checks for Git, Python 3.10+, and Claude Code CLI, then copies files into your Claude configuration directory (`~/.claude/`). Specifically: the main skill goes to `~/.claude/skills/geo/`, each of the 13 sub-skills goes to `~/.claude/skills/geo-/`, and the 5 agent files go to `~/.claude/agents/`. It then installs Python dependencies from `requirements.txt` using `pip install --user`. If you run it interactively, it also offers to install the Playwright Chromium browser for screenshot support. The installer works both from a cloned local directory and via a `curl | bash` pipe from the repository URL. ### Do I need Playwright? Playwright is optional. The installer prompts you to install it (`python3 -m playwright install chromium`). Without it, screenshot-based features are unavailable but all other audit and analysis commands function normally. You can install it later at any time. --- ## Usage ### What is the difference between `/geo quick` and `/geo audit`? `/geo quick` produces a 60-second inline visibility snapshot and writes no output file. It is useful for a fast read on a URL before committing to a full run. `/geo audit` is the full workflow: it fetches the site, detects the business type, launches 5 parallel subagents, aggregates scores across all categories, and writes a `GEO-AUDIT-REPORT.md` with a prioritized action plan. See [commands-reference.md](commands-reference.md) for the complete command list. ### Where does the composite GEO Score come from? The score (0-100) is a weighted aggregate across six categories: AI Citability & Visibility (25%), Brand Authority Signals (20%), Content Quality & E-E-A-T (20%), Technical Foundations (15%), Structured Data (10%), and Platform Optimization (10%). See [scoring-methodology.md](scoring-methodology.md) for how individual signals within each category are measured. ### How do the parallel subagents work? During a full audit, five subagents run simultaneously after the initial discovery phase: `geo-ai-visibility`, `geo-platform-analysis`, `geo-technical`, `geo-content`, and `geo-schema`. Each maps to an agent definition file in `~/.claude/agents/` and is responsible for a distinct slice of the analysis. Claude Code's agent system handles the parallel dispatch; the orchestrator then collects all five reports and synthesizes the composite score. See [architecture.md](architecture.md) for the full flow. ### Where is prospect, proposal, and report data stored? Data from `/geo prospect`, `/geo proposal`, and `/geo compare` is written to `~/.geo-prospects/` outside the Claude Code directory. The structure is: ``` ~/.geo-prospects/ ├── prospects.json ├── proposals/-proposal-.md └── reports/-monthly-.md ``` This directory is intentionally not removed by `uninstall.sh`. Delete it manually with `rm -rf ~/.geo-prospects` if you want to discard your prospect data. --- ## Contributing ### How do I add a new sub-skill? Create a new directory under `skills/` following the naming pattern `geo-/`. Add a `SKILL.md` inside it that defines the skill's name, description, and logic. If the skill should participate in the full audit, register it in the appropriate agent file under `agents/`. Follow the structure of an existing sub-skill such as `skills/geo-citability/` as a reference. See [skills-and-agents.md](skills-and-agents.md) for a map of how skills and agents relate. ### How do I test my changes before opening a PR? Run `./install.sh` from your local clone — the script detects a local `geo/SKILL.md` and installs from the working directory rather than cloning from GitHub. Open Claude Code and exercise the affected commands against a real URL. Verify that all status checks pass before submitting your pull request, as noted in `CONTRIBUTING.md`. ### Where do I report bugs or request features? Open an issue on GitHub. For bugs, include a clear description, the URL you were auditing if relevant, and any error output. For feature requests, explain the use case and why it matters. Search existing issues first to avoid duplicates. Both are tracked under the repository's Issues tab. --- ## Limitations ### Can this tool guarantee AI citations or rankings? No. The tool audits signals that correlate with AI visibility and provides recommendations to improve them, but no tool can guarantee that any AI system will cite or surface a specific domain. AI retrieval is probabilistic and varies by query, platform, and model version. ### Does it submit anything to third-party services? The skill uses `WebFetch` and `Bash` (via `curl`) to fetch the URLs you provide, and the brand mention scanner checks publicly accessible platforms (YouTube, Reddit, Wikipedia, LinkedIn, and others) for brand signals. No audit data is sent to any Anthropic-operated or third-party analytics endpoint. Your data stays within your Claude Code session and your local filesystem. --- ### Scoring Methodology (`docs/scoring-methodology.md`) # Scoring Methodology The GEO Score is a single composite number from 0 to 100 that summarises how well a website is optimised for discovery, citation, and recommendation by AI systems such as ChatGPT, Perplexity, Claude, and Google AI Overviews. It is computed as a weighted average of six category sub-scores, each evaluated independently by a specialised subagent. A high score signals strong readiness for generative-engine visibility; a low score points to concrete gaps with an accompanying prioritised action plan. --- ## Weight table | Category | Weight | |---|---| | AI Citability & Visibility | 25% | | Brand Authority Signals | 20% | | Content Quality & E-E-A-T | 20% | | Technical Foundations | 15% | | Structured Data | 10% | | Platform Optimization | 10% | --- ## How the composite score is computed Each subagent returns a sub-score on a 0–100 scale. The orchestrator in [`skills/geo-audit/SKILL.md`](../skills/geo-audit/SKILL.md) multiplies each sub-score by its weight and sums the results. **Formula (from `skills/geo-audit/SKILL.md`):** ``` GEO_Score = (Citability * 0.25) + (Brand * 0.20) + (EEAT * 0.20) + (Technical * 0.15) + (Schema * 0.10) + (Platform * 0.10) ``` **Pseudo-code:** ```python weights = { "citability": 0.25, "brand": 0.20, "eeat": 0.20, "technical": 0.15, "schema": 0.10, "platform": 0.10, } geo_score = sum(sub_scores[k] * w for k, w in weights.items()) # geo_score is in [0, 100] ``` **Score interpretation (from `skills/geo-audit/SKILL.md`):** | Range | Rating | Meaning | |---|---|---| | 90–100 | Excellent | Highly likely to be cited by AI | | 75–89 | Good | Strong foundation with room for improvement | | 60–74 | Fair | Moderate presence; significant opportunities | | 40–59 | Poor | Weak signals; AI systems may struggle to cite | | 0–39 | Critical | Largely invisible to AI systems | --- ## AI Citability & Visibility (25%) **Implemented by:** [`agents/geo-ai-visibility.md`](../agents/geo-ai-visibility.md) and [`scripts/citability_scorer.py`](../scripts/citability_scorer.py) ### What the scorer looks at The citability sub-score is itself a weighted composite of four components (weights from `agents/geo-ai-visibility.md`): | Component | Weight | |---|---| | Citability Score | 35% | | Brand Mention Score | 30% | | Crawler Access Score | 25% | | llms.txt Score | 10% | **Citability scoring** (`scripts/citability_scorer.py`) analyses every substantive content block on the page — sections bounded by headings — and scores each one across five dimensions: | Dimension | Max points | Key signals | |---|---|---| | Answer Block Quality | 30 | Definition patterns ("X is a…", "X refers to…"), answer appearing in the first 60 words, question-based heading, short clear sentences (5–25 words), attributed claims ("research shows…") | | Self-Containment | 25 | Word count in the 134–167 word optimal range (10 pts), 100–200 word range (7 pts), 80–250 word range (4 pts); pronoun density below 2% (8 pts); 3+ proper nouns (7 pts) | | Structural Readability | 20 | Average sentence length 10–20 words (8 pts); list-like transition words (4 pts); numbered items or step references (4 pts); paragraph breaks (4 pts) | | Statistical Density | 15 | Percentages (3 pts each, max 6); dollar amounts (3 pts each, max 5); numbers with unit context (2 pts each, max 4); year references (2 pts); named sources (2 pts) | | Uniqueness Signals | 10 | Original-research language ("our study found…") (5 pts); case study or real-world example references (3 pts); specific tool/product mentions (2 pts) | The passage score is the sum of all five dimensions (maximum 100). The page-level citability score is the average of the top five scoring blocks, or all blocks when fewer than five exist. **Crawler Access Score** (`agents/geo-ai-visibility.md`) starts at 100 and deducts: - 15 points per critical crawler blocked (GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, GoogleBot) - 5 points per secondary crawler blocked - 10 points if no sitemap is referenced in robots.txt - Floor at 0 **llms.txt Score** (`agents/geo-ai-visibility.md` and `scripts/llmstxt_generator.py`): - 0 — absent - 30 — present but malformed - 50 — present, valid format, minimal content - 70 — present, valid, covers primary content areas - 90–100 — comprehensive, with `/llms-full.txt` also available ### What good vs bad looks like A good AI Citability score (70+) means the page has multiple passages that are self-contained, fact-dense, and directly answer questions; all major AI crawlers are allowed in robots.txt; and an llms.txt file is present and well-structured. A poor score (below 40) typically indicates thin or highly context-dependent prose, blocked AI crawlers, and no llms.txt. --- ## Brand Authority Signals (20%) **Implemented by:** [`agents/geo-ai-visibility.md`](../agents/geo-ai-visibility.md) and [`scripts/brand_scanner.py`](../scripts/brand_scanner.py) ### What the scorer looks at Brand authority is assessed by checking the brand's presence on platforms that AI models draw on heavily when forming entity knowledge. The Brand Mention Score (used as input to the AI Visibility composite above) is built from: | Platform | Points available | Method | |---|---|---| | Wikipedia | 30 | Wikipedia API search; Wikidata entity lookup (`scripts/brand_scanner.py`) | | Industry / niche sources | 25 | Review platforms (G2, Trustpilot, Capterra), press mentions, authoritative industry sites | | Reddit | 20 | Presence, recency, and sentiment of brand discussions | | YouTube | 15 | Official channel existence and third-party video coverage | | LinkedIn | 10 | Company page presence and activity | The correlation values cited in `scripts/brand_scanner.py` come from an Ahrefs December 2025 study of 75,000 brands: YouTube shows the strongest correlation (0.737) with AI citations; domain rating / backlinks show a weak correlation (0.266). ### What good vs bad looks like A strong brand authority score requires an active Wikipedia presence (the highest-weight signal), community-level discussion on Reddit, and a YouTube presence with educational or review content. A brand with no Wikipedia page, no Reddit discussion, and no YouTube presence will score near 0 on this sub-score regardless of how well-known it is in traditional search. --- ## Content Quality & E-E-A-T (20%) **Implemented by:** [`agents/geo-content.md`](../agents/geo-content.md) ### What the scorer looks at The content agent evaluates the page against Google's E-E-A-T framework. Each of the four dimensions is scored 0–25 and then normalised to 0–15 for weighting within the content score: | Dimension | Max (raw) | Key signals checked | |---|---|---| | Experience | 25 | Original research or data, case studies with measurable outcomes, first-hand accounts, before/after comparisons, specific names and figures | | Expertise | 25 | Named author with credentials, linked author page with biography, technical depth, methodology transparency, Person schema | | Authoritativeness | 25 | About page quality, external citations, industry recognition, media mentions, sameAs schema links | | Trustworthiness | 25 | HTTPS, visible contact information, privacy policy, editorial standards, transparent sourcing, publication and update dates | Beyond E-E-A-T, the full content score (0–100) also incorporates: | Component | Weight | Signals | |---|---|---| | E-E-A-T (combined, normalised) | 60% | Four dimensions above | | Content Metrics | 15% | Word count classification (thin < 300 words; deep-dive 3000+ words), approximate Flesch readability, paragraph length, heading hierarchy | | AI Content Assessment | 10% | Absence of generic AI-pattern phrases, presence of authorial voice, original data | | Topical Authority | 10% | Content breadth (related pages), internal linking depth, hub-and-cluster structure | | Content Freshness | 5% | Publication and modification dates visible, recency for time-sensitive topics | ### What good vs bad looks like A score of 70+ requires a clearly identified author with verifiable credentials, original data or case studies, transparent sourcing, HTTPS, and content that goes beyond surface-level coverage of the topic. A score below 30 typically means no author attribution, no external sources, no HTTPS, and content that could have been written by anyone with no subject-matter exposure. --- ## Technical Foundations (15%) **Implemented by:** [`agents/geo-technical.md`](../agents/geo-technical.md) ### What the scorer looks at The technical agent computes a score from nine weighted components: | Component | Weight | |---|---| | Server-Side Rendering / JS dependency | 25% | | Meta tags & indexability | 15% | | Crawlability (robots.txt, sitemap) | 15% | | Security headers | 10% | | Core Web Vitals risk | 10% | | Mobile optimization | 10% | | URL structure | 5% | | Response headers & status | 5% | | Additional checks | 5% | Server-side rendering carries the highest weight because AI crawlers (GPTBot, ClaudeBot, PerplexityBot) generally do not execute JavaScript. A page that requires JS to render its main content is effectively invisible to AI crawlers regardless of how well the content itself is written. Security header deductions (from `agents/geo-technical.md`): - No HTTPS: -30 points - No HSTS: -10 points - No CSP: -10 points - No X-Frame-Options: -5 points - No X-Content-Type-Options: -5 points - No Referrer-Policy: -5 points - No Permissions-Policy: -3 points Core Web Vitals (LCP, INP, CLS) are assessed as Low / Medium / High risk from static HTML analysis. The agent notes explicitly that actual measurements require field data (PageSpeed Insights or CrUX). ### What good vs bad looks like A high technical score requires full server-side rendering, a well-formed robots.txt that allows AI crawlers, a referenced XML sitemap, HTTPS with HSTS, and clean meta tags. A critical finding is any client-side-only SPA where the HTML body is empty without JavaScript execution — in that state, no amount of content optimisation helps AI discoverability. --- ## Structured Data (10%) **Implemented by:** [`agents/geo-schema.md`](../agents/geo-schema.md) ### What the scorer looks at The schema agent detects JSON-LD, Microdata, and RDFa structured data in the page source and scores completeness across ten components: | Component | Max points | Criteria | |---|---|---| | Organization / LocalBusiness | 20 | Present (10 pts); sameAs linking to 3+ platforms (20 pts) | | Article / content schema | 15 | Present (8 pts); author as Person object (12 pts); dateModified present (15 pts) | | Person schema for author | 15 | Present (8 pts); sameAs present (12 pts); jobTitle and knowsAbout present (15 pts) | | sameAs completeness | 15 | 1–2 platforms (5 pts); 3–4 platforms (10 pts); 5+ platforms including Wikipedia (15 pts) | | speakable property | 10 | Present and targeting content sections (10 pts) | | BreadcrumbList | 5 | Present and valid (5 pts) | | WebSite + SearchAction | 5 | Present and valid (5 pts) | | No deprecated schemas | 5 | No HowTo (removed Sep 2023) or SpecialAnnouncement schemas present | | JSON-LD format | 5 | All schemas in JSON-LD rather than Microdata or RDFa | | Validation (no errors) | 5 | All schemas pass syntax and property validation | The agent also flags schemas that are injected by JavaScript rather than present in the initial HTML response, because AI crawlers will not execute JavaScript and will miss those schemas entirely. Deprecated and restricted statuses checked (from `agents/geo-schema.md`): - HowTo: removed from Google rich results September 2023 - FAQPage: restricted to government and health authority sites since August 2023 - SpecialAnnouncement: deprecated ### What good vs bad looks like A high schema score requires an Organization schema with sameAs links to at least five platforms including Wikipedia, properly nested Person schemas for all content authors, Article schema with dateModified, and all schemas delivered as server-rendered JSON-LD. A score near zero means no structured data at all, which removes any explicit entity-linking signal for AI models. --- ## Platform Optimization (10%) **Implemented by:** [`agents/geo-platform-analysis.md`](../agents/geo-platform-analysis.md) ### What the scorer looks at The platform agent scores readiness for five AI search platforms independently and aggregates them. Each platform has its own sub-scoring breakdown: **Google AI Overviews:** Content structure (40 pts) — question-based headings, direct answer paragraphs, comparison tables; source authority signals (30 pts); technical signals (30 pts). **ChatGPT web search:** Entity recognition (35 pts) — Wikipedia and Wikidata presence, sameAs schema; content preferences (40 pts) — factual, citable statements with attribution; crawler access (25 pts) — OAI-SearchBot and ChatGPT-User allowed in robots.txt. **Perplexity AI:** Community validation (Reddit, Quora, Stack Overflow) and source directness scored separately. **Google Gemini and Bing Copilot:** Each platform evaluated against its documented sourcing and ranking signals. The README notes that only 11% of domains are cited by both ChatGPT and Google AI Overviews for the same query, which motivates treating platform readiness as a distinct scoring dimension rather than folding it into technical or content categories. ### What good vs bad looks like A strong platform score requires passing the crawler-access and entity-recognition checks that appear in the other categories, plus platform-specific structural patterns: question-answering headings and direct-answer paragraphs for Google AIO, Wikipedia and Wikidata presence for ChatGPT, and community-platform presence for Perplexity. Because this category overlaps with several other categories, a site that scores well on AI Citability and Brand Authority will often score reasonably here too. --- ## Caveats **Deterministic vs LLM-judged scoring.** The citability scorer (`scripts/citability_scorer.py`) and the llms.txt validator (`scripts/llmstxt_generator.py`) are fully deterministic: given the same HTML, they return the same numerical result every time. The Brand Authority, Content E-E-A-T, Technical, Schema, and Platform scores are produced by LLM subagents following documented rubrics; they are guided evaluations rather than reproducible computations. Two runs on the same URL may produce small differences in LLM-judged categories. **Weights are opinionated.** The 25/20/20/15/10/10 weight distribution reflects the judgement of the tool's authors about the relative importance of each category for AI citation likelihood at the time of writing. These weights are not derived from a controlled study and are subject to change as AI search platforms evolve. **Diagnostic, not a guarantee.** The GEO Score is a diagnostic instrument. A high score improves the structural conditions for AI citation but does not guarantee that any particular AI system will cite or recommend the site. AI model behaviour depends on many factors outside the scope of this tool, including model training data, query phrasing, and competitor content. **Schema validation is structural, not semantic.** The schema agent checks that JSON-LD is syntactically valid, uses recognised Schema.org types and properties, and includes required fields. It does not verify that the values are accurate or that the described entity matches the actual organisation or person. A schema block that passes validation may still contain incorrect information. **llms.txt is an emerging standard.** The llms.txt specification referenced by `scripts/llmstxt_generator.py` and `agents/geo-ai-visibility.md` is not yet universally adopted by AI crawlers. Its presence or absence does not guarantee any specific crawler behaviour at this time. --- ### Skills And Agents (`docs/skills-and-agents.md`) # Skills, Agents, Scripts, and Schemas This reference describes every moving part in the `geo-seo-claude` skill bundle. The bundle optimizes websites for Generative Engine Optimization (GEO) — making content discoverable and citable by AI search platforms (ChatGPT, Perplexity, Google AI Overviews, Gemini, Bing Copilot) — while maintaining traditional SEO foundations. It is structured as one orchestrator skill, 14 sub-skills, 5 parallel subagents, 6 Python helper scripts, and 6 JSON-LD schema templates. See [commands-reference.md](commands-reference.md) for the full slash-command reference and [architecture.md](architecture.md) for how the parallel subagent flow works during a full audit. --- ## Orchestrator - **geo** (`geo/SKILL.md`) — Entry point for all GEO commands. Detects business type, dispatches sub-skills for individual commands, and coordinates the three-phase full-audit flow: discovery, parallel subagent delegation, and score synthesis. Produces a composite GEO Score (0–100) weighted across six categories. --- ## Sub-skills ### geo-audit **Purpose:** Orchestrates a full GEO + SEO audit of a website by running discovery, delegating to five parallel subagents, and aggregating their scores into a single composite GEO Score. **Inputs:** A URL. Optionally, pre-crawled page data. **Outputs:** `GEO-AUDIT-REPORT.md` — composite score, per-category breakdown, issue severity list (Critical / High / Medium / Low), 30-day action plan, and an appendix of pages analyzed. **Scoring weights:** - AI Citability 25%, Brand Authority 20%, Content E-E-A-T 20%, Technical GEO 15%, Structured Data 10%, Platform Optimization 10% **Dependencies:** Delegates to all five subagents (`geo-ai-visibility`, `geo-platform-analysis`, `geo-technical`, `geo-content`, `geo-schema`). See [commands-reference.md](commands-reference.md) for `/geo audit`. --- ### geo-citability **Purpose:** Scores individual content passages on a 0–100 scale for AI citation readiness. Measures how likely an AI system is to extract and quote a passage verbatim. **Inputs:** A URL (fetched with WebFetch). **Outputs:** `GEO-CITABILITY-SCORE.md` — per-section scores, top citation-ready passages, weakest blocks with rewrite suggestions, and a citability coverage percentage. **Scoring dimensions (per passage):** Answer Block Quality (30%), Self-Containment (25%), Structural Readability (20%), Statistical Density (15%), Uniqueness (10%). **Key threshold:** Optimal AI-cited passages are 134–167 words, self-contained, fact-rich, and answer a question in the first 1–2 sentences. See [commands-reference.md](commands-reference.md) for `/geo citability`. --- ### geo-crawlers **Purpose:** Audits which AI crawlers can access the site by parsing `robots.txt`, meta robots tags, and HTTP `X-Robots-Tag` headers, and flags Cloudflare's managed robots.txt when it is silently blocking AI crawlers. Produces a complete access map across 14 crawlers in three tiers. **Inputs:** A domain URL. **Outputs:** `GEO-CRAWLER-ACCESS.md` — per-crawler status (Allowed / Blocked / Not Mentioned), AI Visibility Score, recommended `robots.txt` configuration, and JavaScript rendering assessment. **Crawler tiers:** - Tier 1 (search visibility): GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, PerplexityBot - Tier 2 (broader AI ecosystem): Google-Extended, GoogleOther, Applebot-Extended, Amazonbot, FacebookBot - Tier 3 (training-only): CCBot, anthropic-ai, Bytespider, cohere-ai See [commands-reference.md](commands-reference.md) for `/geo crawlers`. --- ### geo-llmstxt **Purpose:** Analyzes an existing `llms.txt` file for format compliance and completeness, or generates a new one from scratch by crawling the site. The `llms.txt` standard gives AI systems explicit guidance on site structure and key pages. **Inputs:** A domain URL. Operates in analysis mode (file exists) or generation mode (file absent). **Outputs (analysis mode):** `GEO-LLMSTXT-ANALYSIS.md` — format validation table, missing pages, overall llms.txt score (Completeness 40%, Accuracy 35%, Usefulness 25%). **Outputs (generation mode):** A ready-to-deploy `llms.txt` file and `GEO-LLMSTXT-GENERATION.md` explaining page selection rationale. **Dependencies:** `scripts/llmstxt_generator.py` provides validation and generation helpers. See [commands-reference.md](commands-reference.md) for `/geo llmstxt`. --- ### geo-brand-mentions **Purpose:** Scans brand presence across platforms that AI models use for entity recognition and citation decisions. Produces a Brand Authority Score based on platform-weighted presence. **Inputs:** Brand name, domain URL, industry (gathered from the site if not provided). **Outputs:** `GEO-BRAND-MENTIONS.md` — per-platform scores (YouTube 25%, Reddit 25%, Wikipedia/Wikidata 20%, LinkedIn 15%, Other 15%), sentiment assessment, composite Brand Authority Score, and prioritized recommendations. **Key insight:** YouTube mention correlation with AI citation is ~0.737; Domain Rating correlation is ~0.266 (Ahrefs, December 2025 study of 75,000 brands). **Dependencies:** `scripts/brand_scanner.py` provides the platform-check framework. Wikipedia checks use the Wikipedia API directly via Bash (web search alone produces false negatives). See [commands-reference.md](commands-reference.md) for `/geo brands`. --- ### geo-platform-optimizer **Purpose:** Audits readiness for each of the five major AI search platforms individually, since only 11% of domains are cited by both ChatGPT and Google AI Overviews for the same query. **Inputs:** A URL and the site's primary topic or industry. **Outputs:** `GEO-PLATFORM-OPTIMIZATION.md` — per-platform scores and gaps for Google AI Overviews, ChatGPT Web Search, Perplexity AI, Google Gemini, and Bing Copilot; a cross-platform priority action plan. **Platform-specific top factors:** AIO → top-10 ranking + Q&A structure; ChatGPT → Wikipedia entity; Perplexity → Reddit presence + original research; Gemini → YouTube + Knowledge Panel; Bing Copilot → IndexNow + Bing Webmaster Tools. See [commands-reference.md](commands-reference.md) for `/geo platforms`. --- ### geo-schema **Purpose:** Detects, validates, and generates Schema.org structured data (JSON-LD preferred). Structured data is the primary machine-readable signal AI models use to identify and trust entities. **Inputs:** A URL. Uses `scripts/fetch_page.py` to retrieve raw HTML including `` content (WebFetch strips it). **Outputs:** `GEO-SCHEMA-REPORT.md` — detected schemas with validation results, `sameAs` entity-linking audit, deprecated schema flags (HowTo removed Sep 2023, FAQPage restricted Aug 2023), and ready-to-paste JSON-LD code blocks. **GEO-critical schemas:** Organization + `sameAs`, Article + Author (Person), speakable property, BreadcrumbList, WebSite + SearchAction. **Dependencies:** `scripts/fetch_page.py` (raw HTML extraction); `schema/*.json` templates (used as generation references). See [commands-reference.md](commands-reference.md) for `/geo schema`. --- ### geo-technical **Purpose:** Audits eight categories of technical health with emphasis on factors that uniquely affect AI crawler visibility: server-side rendering and AI crawler access. **Inputs:** A homepage URL plus 2–3 key inner pages. **Outputs:** `GEO-TECHNICAL-AUDIT.md` — category scores, AI crawler access table, SSR assessment, Core Web Vitals risk (LCP / INP / CLS), security headers, and mobile optimization status. **Scoring categories (max points):** Server-Side Rendering 15, Core Web Vitals 15, Crawlability 15, Indexability 12, Security 10, Mobile 10, Page Speed 15, URL Structure 8. **Critical check:** AI crawlers do not execute JavaScript. A client-side SPA with no SSR renders an empty page to GPTBot, ClaudeBot, and PerplexityBot. See [commands-reference.md](commands-reference.md) for `/geo technical`. --- ### geo-content **Purpose:** Evaluates content quality through the E-E-A-T framework (Experience, Expertise, Authoritativeness, Trustworthiness) and measures content depth, readability, AI content indicators, and topical authority. **Inputs:** A URL (fetched with WebFetch). **Outputs:** `GEO-CONTENT-ANALYSIS.md` — E-E-A-T scores (25 points each), content metrics table, AI content assessment, topical authority rating, freshness assessment, and rewrite recommendations. **Score modifiers:** Topical authority adds +10 to −5 points on top of the base 100-point E-E-A-T score. See [commands-reference.md](commands-reference.md) for `/geo content`. --- ### geo-report **Purpose:** Aggregates outputs from all audit sub-skills into a single client-facing deliverable written for business owners, not developers — technical findings are translated into business impact and dollar-value framing. **Inputs:** Output files from `geo-platform-optimizer`, `geo-schema`, `geo-technical`, `geo-content`, and optionally `geo-llmstxt` and `geo-brand-mentions`. **Outputs:** `GEO-CLIENT-REPORT.md` — executive summary, GEO Readiness Score, AI Visibility Dashboard, crawler access table, brand authority table, citability analysis, technical health summary, schema status, action plan with effort and platform impact, and a full glossary appendix. Target length: 3,000–6,000 words. See [commands-reference.md](commands-reference.md) for `/geo report`. --- ### geo-report-pdf **Purpose:** Generates a professionally formatted, client-ready PDF from GEO audit data using ReportLab. Includes score gauges, bar charts, and color-coded tables. **Inputs:** Existing `GEO-AUDIT-REPORT.md` or `GEO-CLIENT-REPORT.md` files in the current directory. If a URL is passed, runs the full audit first. **Outputs:** `GEO-REPORT-[brand].pdf` — cover page with score gauge, score breakdown with bar chart, AI platform readiness chart, crawler access table (green/red coded), findings by severity, action plan, and methodology appendix. **Dependencies:** `scripts/generate_pdf_report.py` (requires `pip install reportlab`). See [commands-reference.md](commands-reference.md) for `/geo report-pdf`. --- ### geo-prospect **Purpose:** CRM-lite for managing GEO agency prospects through a five-stage sales pipeline (lead → qualified → proposal → won → lost). Persists all data in `~/.geo-prospects/prospects.json`. **Inputs:** Domain names, contact details, status updates, and notes entered via sub-commands. **Outputs:** Updates to `prospects.json`; audit snapshots in `~/.geo-prospects/audits/`; pipeline summary table printed to terminal. **Key sub-commands:** `new`, `list`, `show`, `audit`, `note`, `status`, `won`, `lost`, `pipeline`. **Dependencies:** `scripts/crm_dashboard.py` provides a rich terminal dashboard (requires `pip install rich`). See [commands-reference.md](commands-reference.md) for `/geo prospect`. --- ### geo-proposal **Purpose:** Auto-generates a client-ready GEO service proposal from audit data, including executive summary, score breakdown, three service tiers with pricing, ROI projection, and engagement timeline. **Inputs:** Domain name or path to an existing audit file. Reads prospect record from `~/.geo-prospects/prospects.json` if available. **Outputs:** `~/.geo-prospects/proposals/-proposal-.md` — a complete proposal ready to send. Also updates the prospect record status to `proposal`. **Tier recommendation logic:** Score 0–40 → Premium (€9,500/mo); 41–60 → Standard (€5,000/mo); 61–75 → Basic (€2,500/mo). See [commands-reference.md](commands-reference.md) for `/geo proposal`. --- ### geo-compare **Purpose:** Generates a monthly delta report comparing two GEO audits (baseline vs. current), tracking score improvements across all categories and action-item completion status. **Inputs:** A domain name or two audit file paths. Reads files from `~/.geo-prospects/audits/` sorted by date if only domain is provided. **Outputs:** `~/.geo-prospects/reports/-monthly-.md` — score progress bar, before/after breakdown table, platform and crawler delta tables, action plan status, wins section, new issues discovered, and 6-month trajectory. See [commands-reference.md](commands-reference.md) for `/geo compare`. --- ## Parallel Subagents These five agents run simultaneously during a `/geo audit` to reduce total runtime. Each returns a structured markdown section and a category score (0–100) that feeds the composite GEO Score. See [architecture.md](architecture.md) for the parallel flow diagram. ### geo-ai-visibility **File:** `agents/geo-ai-visibility.md` **Role:** GEO specialist covering the four highest-weighted AI visibility dimensions. **Dispatched when:** Phase 2 of `/geo audit` begins. **What it does:** Scores every content block for citability (5-dimension rubric), parses `robots.txt` for 12 AI crawlers, validates `llms.txt` format and completeness, and scans brand presence on YouTube, Reddit, Wikipedia, and LinkedIn. **Returns:** AI Visibility Score = Citability (35%) + Brand Mentions (30%) + Crawler Access (25%) + llms.txt (10%). **Sub-skills used:** geo-citability, geo-crawlers, geo-llmstxt, geo-brand-mentions. --- ### geo-platform-analysis **File:** `agents/geo-platform-analysis.md` **Role:** Platform optimization specialist. **Dispatched when:** Phase 2 of `/geo audit` begins (concurrent with other agents). **What it does:** Evaluates readiness for each of the five AI search platforms — Google AI Overviews, ChatGPT Web Search, Perplexity AI, Google Gemini, and Bing Copilot — using platform-specific scoring rubrics and signal checks. **Returns:** Per-platform scores (0–100 each) and a Platform Readiness Average; cross-platform synergy actions. **Sub-skill used:** geo-platform-optimizer. --- ### geo-technical **File:** `agents/geo-technical.md` **Role:** Technical SEO specialist. **Dispatched when:** Phase 2 of `/geo audit` begins (concurrent with other agents). **What it does:** Fetches raw HTML and response headers; audits SSR vs. CSR rendering (the highest-weight check), crawlability, meta tags, security headers, Core Web Vitals risk indicators, mobile optimization, and URL structure. **Returns:** Technical Score (0–100) with per-category breakdown; SSR severity rating (Critical / High / Medium / Low). **Sub-skill used:** geo-technical. --- ### geo-content **File:** `agents/geo-content.md` **Role:** Content quality specialist. **Dispatched when:** Phase 2 of `/geo audit` begins (concurrent with other agents). **What it does:** Evaluates E-E-A-T across all four dimensions (25 points each), measures word count, readability (Flesch), heading structure, and internal linking, detects AI content quality signals, assesses topical authority and content freshness. **Returns:** Content Score (0–100); E-E-A-T breakdown; AI content assessment label. **Sub-skill used:** geo-content. --- ### geo-schema **File:** `agents/geo-schema.md` **Role:** Schema markup specialist. **Dispatched when:** Phase 2 of `/geo audit` begins (concurrent with other agents). **What it does:** Uses `fetch_page.py` to retrieve raw HTML, detects all JSON-LD / Microdata / RDFa blocks, validates each against Schema.org specifications, audits `sameAs` entity links, flags deprecated or JS-injected schemas, and generates ready-to-paste JSON-LD templates for missing schemas. **Returns:** Schema Score (0–100); validated schema inventory; generated JSON-LD code blocks. **Sub-skill used:** geo-schema. --- ## Python Scripts | Script | Purpose | Used by | |--------|---------|---------| | `scripts/fetch_page.py` | Fetches a URL and returns structured data including raw HTML, meta tags, heading structure, word count, and parsed JSON-LD blocks. Bypasses the markdown conversion that WebFetch applies, preserving `` content. | geo-schema (skill + agent), geo-technical | | `scripts/citability_scorer.py` | Scores individual text passages for AI citation readiness using five weighted dimensions (answer quality, self-containment, structure, statistical density, uniqueness). Provides `score_passage()` as a callable function. | geo-citability | | `scripts/brand_scanner.py` | Checks brand presence across AI-cited platforms (YouTube, Reddit, Wikipedia, LinkedIn). Provides per-platform check functions and instructions for WebFetch-based verification. Requires `requests` and `beautifulsoup4`. | geo-brand-mentions | | `scripts/llmstxt_generator.py` | Validates an existing `llms.txt` against the spec (H1 title, blockquote description, H2 sections, absolute URLs, descriptions) and generates a new file from site crawl data. | geo-llmstxt | | `scripts/generate_pdf_report.py` | Generates a multi-page PDF from a JSON audit data file using ReportLab. Renders score gauges, bar charts, color-coded tables, and an action plan. Accepts the JSON file path as a CLI argument or via stdin. Requires `reportlab`. | geo-report-pdf | | `scripts/crm_dashboard.py` | Renders a rich terminal dashboard for the prospect CRM. Reads `~/.geo-prospects/prospects.json` and displays pipeline stages, MRR, and prospect detail views. Requires `rich`. | geo-prospect | --- ## Schema Templates These JSON-LD files in `schema/` serve as generation references when `geo-schema` or `geo-report` need to produce ready-to-paste structured data. All placeholders follow the pattern `YOUR_FIELD_NAME` or `REPLACE_WITH_VALUE`. | Template | When to use | |----------|-------------| | `schema/organization.json` | Any business site; provides the full Organization type with `sameAs` links to Wikipedia, Wikidata, LinkedIn, YouTube, GitHub, and Crunchbase, plus `knowsAbout` for entity topic signals. | | `schema/local-business.json` | Businesses with a physical location; extends Organization with address, `geo` coordinates, opening hours, service area, aggregate rating, and an offer catalog. | | `schema/article-author.json` | Publisher and blog pages; Article type with a fully populated Person author (credentials, `sameAs`, `alumniOf`, `knowsAbout`) and a `speakable` specification for AI assistant readability. | | `schema/product-ecommerce.json` | E-commerce product pages; Product type with Offer (including shipping details and return policy), AggregateRating, and individual Review entries. | | `schema/software-saas.json` | SaaS product pages; SoftwareApplication type with tiered AggregateOffer pricing, `featureList`, screenshot, and `sameAs` links to G2, Capterra, ProductHunt, and GitHub. | | `schema/website-searchaction.json` | Every site's homepage; WebSite type with a SearchAction `potentialAction` to enable sitelinks search box and provide AI systems with the site's search endpoint. | --- --- METRICS --- - Files Extracted: 9 - Estimated Token Budget: ~21820 tokens - Canonical Reference: https://codewiki.google/github.com/zubair-trabzada/geo-seo-claude