geo-optimizer-skill
<div align="center"> <img src="assets/logo.svg" alt="GEO Optimizer" width="480"/> ### Open-source GEO audit engine for AI search visibility and citability. [](https://pypi.org/project/geo-optimizer-skill/) [](https://python.org) [](https://github.com/auriti-labs/geo-optimizer-skill/actions) [](https://app.codecov.io/gh/Auriti-Labs/geo-optimizer-skill) [](https://github.com/Auriti-Labs/geo-optimizer-skill/actions/workflows/ci.yml) [](LICENSE) [](https://modelcontextprotocol.io) [](https://buymeacoffee.com/auritidesign) **GEO Optimizer helps you audit whether a website can be crawled, understood, cited, and monitored by AI answer engines.** [Quick Start](#quick-start) · [Live Demo](https://geoready.dev) · [Pricing](https://geoready.dev/pricing) · [Sign Up](https://app.geoready.dev/signup) · [Documentation](https://auriti-labs.github.io/geo-optimizer-skill/) · [Changelog](CHANGELOG.md) <img src="assets/demo.gif" alt="geo audit demo — score 0-100 with prioritized fixes in one command" width="800"/> </div> --- ## Why this exists AI search engines give direct answers and **cite their sources**. If your site isn't optimized, you're invisible — even if you rank #1 on Google. ``` User: "What's the best mortgage calculator?" Perplexity: "According to [Competitor.com], the formula is..." ↑ They appear. You don't. ``` GEO Optimizer audits your site against **47 research-backed methods** ([Princeton KDD 2024](https://arxiv.org/abs/2311.09735), [AutoGEO ICLR 2026](https://arxiv.org/abs/2510.11438)) and generates the fixes. ### Why this matters in 2026 - ChatGPT alone serves [**900M weekly users**](https://llmrefs.com/generative-engine-optimization) — a growing share of sessions that used to be Google searches. - [**28.3% of ChatGPT's most-cited pages have *zero* organic visibility on Google**](https://llmrefs.com/generative-engine-optimization) (Ahrefs) — AI engines reward different signals than classic SEO. - Proper JSON-LD schema lifts LLM extraction accuracy [**from 16% to 54%**](https://dev.to/geobuddy/llmstxt-schema-markup-and-technical-geo-what-actually-works-in-2026-o63) (Semrush test on GPT-4). - [**844,000+ sites**](https://webflow.com/blog/llms-txt) already ship an `llms.txt`. Yours? --- ## GEO is not traditional SEO SEO and GEO answer different questions: - **SEO** optimizes for ranking and visibility in traditional search result pages — crawlability, backlinks, keyword signals. - **GEO** measures whether an AI answer engine can read, parse, understand, and cite your content when generating a response. - A site can rank well on Google and still be largely opaque to AI systems — missing structured data, no llms.txt, bot access blocked, thin factual density. GEO Optimizer focuses on the technical and structural signals that AI answer engines use: robots.txt bot permissions, llms.txt presence and depth, JSON-LD schema richness, brand entity coherence, and content citability across 47 methods. These complement traditional SEO work rather than replacing it. --- ## Try it online | | | |---|---| | **Free audit** | [geoready.dev](https://geoready.dev) — single-URL GEO score, no account required | | **Free tools** | [llms.txt generator](https://geoready.dev/tools/llms-txt-generator/) — build a starter llms.txt from your sitemap | | **Pricing** | [geoready.dev/pricing](https://geoready.dev/pricing) — plans and feature comparison | | **Sign up** | [app.geoready.dev/signup](https://app.geoready.dev/signup) — Pro/Studio/Agency available now | --- ## Open-source vs GeoReady Platform | | GEO Optimizer CLI | GeoReady.dev Free | GeoReady Pro / Studio / Agency | |---|---|---|---| | **License / access** | MIT, open-source | Free, no account | Self-serve — [sign up](https://app.geoready.dev/signup) | | **Core use** | Local audit engine, CI/CD integration, JSON output | Web audit, score preview, educational pages | Monitoring, score history, regression alerts, agency reporting | | **Target** | Developers, automation | Developers, SEO specialists | Ongoing clients, multi-site portfolios | | **Pricing** | Free forever | Free forever | From $19/month — see [geoready.dev/pricing](https://geoready.dev/pricing) | The CLI and web audit remain MIT-licensed and free. The GeoReady platform adds server-side continuity — monitoring, history, and team features — that a local CLI cannot provide on its own. --- ## Quick Start ```bash pip install geo-optimizer-skill ``` No install? One-shot audit with [uv](https://docs.astral.sh/uv/): ```bash uvx --from geo-optimizer-skill geo audit --url https://yoursite.com ``` ```bash # Audit any site — get a score 0-100 with actionable recommendations geo audit --url https://yoursite.com # Audit a full sitemap and surface weakest pages first geo audit --sitemap https://yoursite.com/sitemap.xml --max-urls 25 # Compare before/after versions of a page geo diff --before https://yoursite.com/page-old --after https://yoursite.com/page-new # Save history and detect regressions over time geo audit --url https://yoursite.com --save-history --regression # Show the saved trend for a site geo history --url https://yoursite.com # Passive AI visibility snapshot for a domain geo monitor --domain yoursite.com # Ask real AI engines: is my brand mentioned? Is my domain cited as a source? # BYO API key — PERPLEXITY_API_KEY recommended (real web citations) geo citations --brand "YourBrand" --domain yoursite.com --topic "your product category" # Save or query archived AI answer snapshots geo snapshots --query "best GEO tool" --from 2026-03-01 --to 2026-03-30 # Score citation quality inside an archived answer snapshot geo snapshots --quality --snapshot-id 12 --target-domain yoursite.com # Run recurring monitoring and generate an HTML trend report geo track --url https://yoursite.com --report --output ./geo-track-report.html # Auto-generate all missing files (robots.txt, llms.txt, schema, meta) geo fix --url https://yoursite.com --apply # Generate llms.txt from sitemap geo llms --base-url https://yoursite.com --output ./public/llms.txt # Generate JSON-LD schema geo schema --type faq --url https://yoursite.com ``` --- ## What it checks | Area | Points | What GEO Optimizer looks for | |------|--------|------------------------------| | **Robots.txt** | /18 | 27 AI bots across 3 tiers (training, search, user). Citation bots explicitly allowed? | | **llms.txt** | /18 | Present, has H1 + blockquote, sections, links, depth. Companion llms-full.txt? | | **Schema JSON-LD** | /16 | WebSite, Organization, FAQPage, Article. Schema richness (5+ attributes)? | | **Meta Tags** | /14 | Title, description, canonical, Open Graph complete? | | **Content** | /12 | H1, statistics, external citations, heading hierarchy, lists/tables, front-loading? | | **Brand & Entity** | /10 | Brand name coherence, Knowledge Graph links (Wikipedia/Wikidata/LinkedIn/Crunchbase), about page, geo signals, topic authority | | **Signals** | /6 | `<html lang>`, RSS/Atom feed, dateModified freshness? | | **AI Discovery** | /6 | `.well-known/ai.txt`, `/ai/summary.json`, `/ai/faq.json`, `/ai/service.json`? | **Score bands:** 86-100 Excellent · 68-85 Good · 36-67 Foundation · 0-35 Critical **Bonus checks** (informational, do not affect score): | Check | What it detects | |-------|-----------------| | **CDN Crawler Access** | Does Cloudflare/Akamai/Vercel block GPTBot, ClaudeBot, PerplexityBot? | | **JS Rendering** | Is content accessible without JavaScript? SPA framework detection | | **WebMCP Readiness** | Chrome WebMCP support: `registerTool()`, `toolname` attributes, `potentialAction` schema | | **Negative Signals** | 8 anti-citation signals: CTA overload, popups, thin content, keyword stuffing, missing author, boilerplate ratio | | **Prompt Injection Detection** | 8 manipulation patterns: hidden text, invisible Unicode, LLM instructions, HTML comment injection, monochrome text, micro-font, data-attr injection, aria-hidden abuse | | **Trust Stack Score** | 5-layer trust aggregation (Technical, Identity, Social, Academic, Consistency) — composite grade A-F | | **RAG Chunk Readiness** | Content segmentation for RAG retrieval: section word counts, definition openings, heading boundaries, anchor sentences `🆕 v4.7` | | **Content Decay Prediction** | Detects temporal, statistical, version, event, and price decay patterns — evergreen score 0-100 `🆕 v4.7` | | **Platform Citation Profile** | Per-platform readiness scores for ChatGPT, Perplexity, Google AI `🆕 v4.7` | | **Multimodal Readiness** | Image alt coverage, captions, VideoObject/AudioObject schema, subtitle tracks, transcripts — the text scaffolding multimodal engines (Gemini, GPT-4o) need `🆕` | Plus a separate **Citability Score** (0-100) measuring content quality across 47 methods: Quotation +41% · Statistics +33% · Fluency +29% · Cite Sources +27% · and 43 more. ### Additional tools ```bash geo coherence --sitemap https://example.com/sitemap.xml # Cross-page terminology consistency geo logs --file access.log # AI Crawler Activity — crawler evidence from user-agent logs geo access --url https://example.com # Agent Access Audit — browser vs AI bot access simulation geo citations --brand "Acme" --domain acme.com # AI Citation Check — are you cited by answer engines? (BYO key) geo authority --sitemap https://example.com/sitemap.xml # Topic Authority — multi-page entity coverage, clusters, pillars ``` GEO Optimizer checks whether websites can be **crawled, understood, cited, and monitored** by AI answer engines: - **Crawled** — robots.txt, CDN access, AI-bot reachability - **Understood** — schema, llms.txt, content structure - **Cited** — citability signals across 47 research-backed methods - **Monitored** — `geo logs` (crawler evidence) and `geo access` (access simulation) Note on wording: AI Crawler Activity reports crawler evidence from server-log user-agents. Agent Access Audit reports *citation readiness* (whether bots can reach and parse the page). For actual answer-engine checking — "does the AI mention my brand and cite my domain?" — use `geo citations` with your own API key (Perplexity Sonar returns the real source URLs; OpenAI/Anthropic/Groq reveal parametric brand knowledge). Optional LLM-powered analysis (`pip install geo-optimizer-skill[llm]`): brand sentiment, citation attribution, multi-turn persistence, cross-platform citation map, prompt library. --- ## Output formats ```bash geo audit --url https://example.com --format text # Human-readable (default) geo audit --url https://example.com --format json # Machine-readable geo audit --sitemap https://example.com/sitemap.xml # Batch sitemap audit (text) geo audit --sitemap https://example.com/sitemap.xml --format json # Batch sitemap audit (JSON) geo audit --url https://example.com --format rich # Colored terminal geo audit --url https://example.com --format html # Self-contained report geo audit --url https://example.com --format sarif # GitHub Code Scanning geo audit --url https://example.com --format junit # Jenkins, GitLab CI geo audit --url https://example.com --format github # GitHub Actions annotations geo monitor --domain example.com # Passive AI visibility readiness geo snapshots --query "best GEO tool" # Saved AI answer archive geo snapshots --quality --snapshot-id 12 # Citation quality tiers for a saved answer geo history --url https://example.com # Saved score trend geo track --url https://example.com --report # Monitoring HTML report ``` The JSON output format is intended to remain stable across minor versions and acts as the machine-readable integration contract for the GeoReady platform. --- ## CI/CD Integration ```yaml # .github/workflows/geo.yml - uses: Auriti-Labs/[email protected] with: url: https://yoursite.com min-score: 70 # Fail if score drops below 70 format: sarif # Upload to GitHub Security tab ``` Works with GitHub Actions, GitLab CI, Jenkins, CircleCI, and any CI that runs Python. For longitudinal checks, persist snapshots and fail on regressions: ```bash geo audit --url https://yoursite.com --save-history --regression ``` --- ## MCP Server Use GEO Optimizer from Claude, Cursor, Windsurf, or any MCP client: ```bash pip install geo-optimizer-skill[mcp] claude mcp add geo-optimizer -- geo-mcp ``` Then ask: *"audit my site and fix what's missing"* | Tool | Purpose | |------|---------| | `geo_audit` | Full audit with score + recommendations | | `geo_fix` | Generate fix files | | `geo_llms_generate` | Generate llms.txt | | `geo_citability` | Content citability analysis (47 methods) | | `geo_schema_validate` | Validate JSON-LD | | `geo_compare` | Compare multiple sites | | `geo_gap_analysis` | Explain the gap between two sites and prioritize fixes | | `geo_ai_discovery` | Check AI discovery endpoints | | `geo_check_bots` | Check bot access via robots.txt | | `geo_trust_score` | 5-layer trust signal aggregation | | `geo_negative_signals` | 8 anti-citation signal detection | | `geo_factual_accuracy` | Audit unsourced claims, contradictions, and broken citations | --- ## Use as AI Context Load the right file into your AI assistant for GEO expertise: | Platform | File | |----------|------| | Claude Projects | [`ai-context/claude-project.md`](ai-context/claude-project.md) | | ChatGPT Custom GPT | [`ai-context/chatgpt-custom-gpt.md`](ai-context/chatgpt-custom-gpt.md) | | Cursor | [`ai-context/cursor.mdc`](ai-context/cursor.mdc) | | Windsurf | [`ai-context/windsurf.md`](ai-context/windsurf.md) | | Kiro | [`ai-context/kiro-steering.md`](ai-context/kiro-steering.md) | --- ## Internal Skill System The repository now includes a structured internal skill catalog for maintainers at [`src/geo_optimizer/skills/catalog/`](src/geo_optimizer/skills/catalog/) plus validation rules and examples. See [`docs/skill-system.md`](docs/skill-system.md) for the v1 architecture. --- ## Python API ```python from geo_optimizer import audit result = audit("https://example.com") print(result.score) # 85 print(result.band) # "good" print(result.citability.total_score) # 72 print(result.score_breakdown) # {"robots": 18, "llms": 14, ...} print(result.recommendations) # ["Add FAQPage schema..."] ``` Async variant: ```python from geo_optimizer import audit_async result = await audit_async("https://example.com") ``` --- ## Show your GEO score Add a live GEO score badge to your README — like a coverage badge, but for AI visibility:  ```markdown [](https://geoready.dev?utm_source=badge) ``` HTML variant for docs sites: ```html <a href="https://geoready.dev?utm_source=badge"><img src="https://geoready.dev/badge?url=https://yoursite.com" alt="GEO Score"></a> ``` Colors: 86-100 green · 68-85 cyan · 36-67 yellow · 0-35 red. Re-audited and cached hourly — improve your site, watch the badge change. No account needed. --- ## Plugin System Extend the audit with custom checks via entry points: ```toml [project.entry-points."geo_optimizer.checks"] my_check = "mypackage:MyCheck" ``` See [`examples/example_plugin.py`](examples/example_plugin.py) for a working example. --- ## Research Foundation | Paper | Venue | Key Finding | |-------|-------|-------------| | [GEO: Generative Engine Optimization](https://arxiv.org/abs/2311.09735) | **KDD 2024** | 9 methods tested on 10k queries. Cite Sources: +115%, Statistics: +40% | | [AutoGEO](https://arxiv.org/abs/2510.11438) | **ICLR 2026** | Automatic rule extraction. +50.99% over Princeton baseline | | [C-SEO Bench](https://arxiv.org/abs/2506.11097) | **2025** | Most content manipulation is ineffective. Infrastructure matters most | We focus on **technical infrastructure** (robots.txt, llms.txt, schema, meta) over content rewriting. The research confirms: if crawlers can't find and parse your content, prose optimization doesn't matter. GEO Optimizer translates these findings into technical and content-level signals that can be operationally audited and tracked over time. --- ## Roadmap This project follows a deliberate release cadence — focused waves, not noisy patches. | Version | Window | Codename | Status | |---------|--------|----------|--------| | v4.10.0 | Apr 2026 | Veil | Shipped | | v4.11.0 | May 2026 | Static | Shipped | | v4.12.0 | May 2026 | Ledger | Shipped | | v4.13.0 | Jun 2026 | Echo | Shipped | | v4.14.0 | Nov 2026 | Quiet Glass | Planned | | v4.15.0-rc1 | Jan 2027 | Threshold | Planned | | v4.15.0-rc2 / v4.16.0 | Mar 2027 | Pale Signal | Planned | | v5.0.0 | May 2027 | Black Archive | Exploring | Next focus areas: signal architecture, retrieval surface analysis, scoring recalibration, and structural pattern recognition. The v5.0 cycle represents a broader architectural evolution. Full release calendar, philosophy, and direction → [docs/ROADMAP.md](docs/ROADMAP.md) --- ## Security All URL inputs are validated against private IP ranges (RFC 1918, loopback, link-local, cloud metadata) with DNS pinning before any request. See [SECURITY.md](SECURITY.md) for reporting vulnerabilities. --- ## Contributing ```bash git clone https://github.com/YOUR_USERNAME/geo-optimizer-skill.git cd geo-optimizer-skill && pip install -e ".[dev]" pytest tests/ -v # 1682 tests, all mocked ``` [Bug reports](https://github.com/Auriti-Labs/geo-optimizer-skill/issues/new?template=bug_report.yml) · [Feature requests](https://github.com/Auriti-Labs/geo-optimizer-skill/issues/new?template=feature_request.yml) · [CONTRIBUTING.md](CONTRIBUTING.md) --- <div align="center"> Run the [CLI locally](#quick-start), try the [free audit online](https://geoready.dev), see [pricing](https://geoready.dev/pricing), or [sign up](https://app.geoready.dev/signup) for Pro monitoring. --- **MIT License** · Built by [Auriti Labs](https://github.com/auriti-labs) If this saved you time, a star helps others find it. [](https://github.com/auriti-labs/geo-optimizer-skill/stargazers) </div> ## Star History <a href="https://www.star-history.com/?repos=Auriti-Labs%2Fgeo-optimizer-skill&type=timeline&logscale=&legend=bottom-right"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Auriti-Labs/geo-optimizer-skill&type=timeline&theme=dark&logscale&legend=bottom-right" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Auriti-Labs/geo-optimizer-skill&type=timeline&logscale&legend=bottom-right" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=Auriti-Labs/geo-optimizer-skill&type=timeline&logscale&legend=bottom-right" /> </picture> </a>