Geo Optimizer Skill

Make websites visible to AI search engines

Audit, fix, and optimize any website to be cited by ChatGPT, Perplexity, Claude, and Gemini.

Quick Start · Live Demo · Documentation · Changelog

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, AutoGEO ICLR 2026) and generates the fixes.

Quick Start

pip install geo-optimizer-skill

# 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

# 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

Score bands: 86-100 Excellent · 68-85 Good · 36-67 Foundation · 0-35 Critical

Bonus checks (informational, do not affect score):

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

geo coherence --sitemap https://example.com/sitemap.xml  # Cross-page terminology consistency
geo logs --file access.log                                # AI crawler log analysis

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

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

CI/CD Integration

# .github/workflows/geo.yml
- uses: Auriti-Labs/geo-optimizer-skill@v1
  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:

geo audit --url https://yoursite.com --save-history --regression

MCP Server

Use GEO Optimizer from Claude, Cursor, Windsurf, or any MCP client:

pip install geo-optimizer-skill[mcp]
claude mcp add geo-optimizer -- geo-mcp

Then ask: "audit my site and fix what's missing"

Use as AI Context

Load the right file into your AI assistant for GEO expertise:

Internal Skill System

The repository now includes a structured internal skill catalog for maintainers at src/geo_optimizer/skills/catalog/ plus validation rules and examples. See docs/skill-system.md for the v1 architecture.

Python API

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:

from geo_optimizer import audit_async
result = await audit_async("https://example.com")

Dynamic Badge

Show your GEO score in your README:

![GEO Score](https://geoready.dev/badge?url=https://yoursite.com)

Colors: 86-100 green · 68-85 cyan · 36-67 yellow · 0-35 red. Cached 1h.

Plugin System

Extend the audit with custom checks via entry points:

[project.entry-points."geo_optimizer.checks"]
my_check = "mypackage:MyCheck"

See examples/example_plugin.py for a working example.

Research Foundation

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.

Roadmap

This project follows a deliberate release cadence — focused waves, not noisy patches.

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

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 for reporting vulnerabilities.

Contributing

git clone https://github.com/YOUR_USERNAME/geo-optimizer-skill.git
cd geo-optimizer-skill && pip install -e ".[dev]"
pytest tests/ -v   # 1309 tests, all mocked

Bug reports · Feature requests · CONTRIBUTING.md

MIT License · Built by Auriti Labs

If this saved you time, a star helps others find it.

Star History