convez.ai
MCP Server
Auriti-Labs

geo-optimizer-skill

Auriti-Labs/geo-optimizer-skill

Ver no GitHub
Muito bomPluginScore · de 0 a 100

GEO (Generative Engine Optimization) toolkit — audit, optimize, and make websites visible to AI search engines (ChatGPT, Perplexity, Claude, Gemini). Based on Princeton KDD 2024 research.

Instalação

$npx convez-ai Auriti-Labs/geo-optimizer-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1,3 mil
Forks
159
Acompanhando
11
Saúde
75%
Último commit
há 3 dias
Versão
v4.23.0
Issues abertas
8
Contribuidores
4

README

A tradução para o português deste README ainda está na fila.

Open-source GEO audit engine for AI search visibility and citability.

PyPI Python 3.9+ CI codecov Tests License: MIT MCP Compatible Buy Me a Coffee

GEO Optimizer helps you audit whether a website can be crawled, understood, cited, and monitored by AI answer engines.

Quick Start · Live Demo · Pricing · Sign Up · 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.

Why this matters in 2026


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 auditgeoready.dev — single-URL GEO score, no account required
Free toolsllms.txt generator — build a starter llms.txt from your sitemap
Pricinggeoready.dev/pricing — plans and feature comparison
Sign upapp.geoready.dev/signup — Pro/Studio/Agency available now

Open-source vs GeoReady Platform

GEO Optimizer CLIGeoReady.dev FreeGeoReady Pro / Studio / Agency
License / accessMIT, open-sourceFree, no accountSelf-serve — sign up
Core useLocal audit engine, CI/CD integration, JSON outputWeb audit, score preview, educational pagesMonitoring, score history, regression alerts, agency reporting
TargetDevelopers, automationDevelopers, SEO specialistsOngoing clients, multi-site portfolios
PricingFree foreverFree foreverFrom $19/month — see 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

pip install geo-optimizer-skill

No install? One-shot audit with uv:

uvx --from geo-optimizer-skill geo audit --url https://yoursite.com
# 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

AreaPointsWhat GEO Optimizer looks for
Robots.txt/1827 AI bots across 3 tiers (training, search, user). Citation bots explicitly allowed?
llms.txt/18Present, has H1 + blockquote, sections, links, depth. Companion llms-full.txt?
Schema JSON-LD/16WebSite, Organization, FAQPage, Article. Schema richness (5+ attributes)?
Meta Tags/14Title, description, canonical, Open Graph complete?
Content/12H1, statistics, external citations, heading hierarchy, lists/tables, front-loading?
Brand & Entity/10Brand 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):

CheckWhat it detects
CDN Crawler AccessDoes Cloudflare/Akamai/Vercel block GPTBot, ClaudeBot, PerplexityBot?
JS RenderingIs content accessible without JavaScript? SPA framework detection
WebMCP ReadinessChrome WebMCP support: registerTool(), toolname attributes, potentialAction schema
Negative Signals8 anti-citation signals: CTA overload, popups, thin content, keyword stuffing, missing author, boilerplate ratio
Prompt Injection Detection8 manipulation patterns: hidden text, invisible Unicode, LLM instructions, HTML comment injection, monochrome text, micro-font, data-attr injection, aria-hidden abuse
Trust Stack Score5-layer trust aggregation (Technical, Identity, Social, Academic, Consistency) — composite grade A-F
RAG Chunk ReadinessContent segmentation for RAG retrieval: section word counts, definition openings, heading boundaries, anchor sentences 🆕 v4.7
Content Decay PredictionDetects temporal, statistical, version, event, and price decay patterns — evergreen score 0-100 🆕 v4.7
Platform Citation ProfilePer-platform readiness scores for ChatGPT, Perplexity, Google AI 🆕 v4.7
Multimodal ReadinessImage 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

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

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

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

ToolPurpose
geo_auditFull audit with score + recommendations
geo_fixGenerate fix files
geo_llms_generateGenerate llms.txt
geo_citabilityContent citability analysis (47 methods)
geo_schema_validateValidate JSON-LD
geo_compareCompare multiple sites
geo_gap_analysisExplain the gap between two sites and prioritize fixes
geo_ai_discoveryCheck AI discovery endpoints
geo_check_botsCheck bot access via robots.txt
geo_trust_score5-layer trust signal aggregation
geo_negative_signals8 anti-citation signal detection
geo_factual_accuracyAudit unsourced claims, contradictions, and broken citations

Use as AI Context

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

PlatformFile
Claude Projectsai-context/claude-project.md
ChatGPT Custom GPTai-context/chatgpt-custom-gpt.md
Cursorai-context/cursor.mdc
Windsurfai-context/windsurf.md
Kiroai-context/kiro-steering.md

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")

Show your GEO score

Add a live GEO score badge to your README — like a coverage badge, but for AI visibility:

GEO Score

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

HTML variant for docs sites:

<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:

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

See examples/example_plugin.py for a working example.


Research Foundation

PaperVenueKey Finding
GEO: Generative Engine OptimizationKDD 20249 methods tested on 10k queries. Cite Sources: +115%, Statistics: +40%
AutoGEOICLR 2026Automatic rule extraction. +50.99% over Princeton baseline
C-SEO Bench2025Most 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.

VersionWindowCodenameStatus
v4.10.0Apr 2026VeilShipped
v4.11.0May 2026StaticShipped
v4.12.0May 2026LedgerShipped
v4.13.0Jun 2026EchoShipped
v4.14.0Nov 2026Quiet GlassPlanned
v4.15.0-rc1Jan 2027ThresholdPlanned
v4.15.0-rc2 / v4.16.0Mar 2027Pale SignalPlanned
v5.0.0May 2027Black ArchiveExploring

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   # 1682 tests, all mocked

Bug reports · Feature requests · CONTRIBUTING.md


Run the CLI locally, try the free audit online, see pricing, or sign up for Pro monitoring.


MIT License · Built by Auriti Labs

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

Star on GitHub

Star History

Ver o original no GitHub

Bom para

Relacionados