Diagnose GEO gaps with evidence-backed audits

Where this fits

You've launched a site, but AI assistants and answer engines don't cite it. Your team needs to know why — not guesses, but concrete gaps in how your content is structured, sourced, and referenced. geo-diagnose takes a URL, HTML file, or raw evidence and runs a reproducible audit that surfaces missing entity signals, citation-worthy facts, and content patterns that AI platforms reward. It's the diagnostic step before you change anything.

Why agents benefit

• Replayable evidence: Every run snapshots source HTML and normalizes input, so an agent can re-audit after changes and compare exact diffs without re-fetching pages.
• Deterministic or research modes: Choose legacy compatibility or a stricter deterministic pipeline — useful for CI-style checks or exploratory deep dives.
• Structured output contract: The artifact bus returns quality reports, run lineage, and remediation query maps, making it easy for downstream agents to act on findings programmatically.
• Explicit scope boundaries: It excludes live AI-platform recall or ranking measurement, so an agent won't overclaim or blur diagnostic evidence with performance data.
• Bilingual readiness: The method and catalog support Chinese and English contexts (品牌诊断, 网站诊断), covering a wider set of client scenarios.

Practical scenarios

Pre-launch brand audit for a new domain

Before a startup's site goes live, an agent runs geo-diagnose on the staging URL. The report flags missing author bios, absent schema for key entities, and thin citation-worthy statistics. The team fixes these before launch instead of patching after AI assistants ignore them.

Competitive gap analysis for a content refresh

You have a competitor's page and your own. Feed both URLs into the skill. The structured diagnosis shows which evidence types (quotes, studies, internal links) your page lacks relative to the competitor, and the remediation query map suggests targeted content additions.

Post-update regression check

After rewriting a product page, an agent reruns the audit with the same brief. The run lineage and quality report confirm whether new entity signals and evidence markers actually improved, without needing to wait for AI-platform ranking changes.

Add it to your agent workflow

Install directly into your agent environment:

npx skills add yaojingang/GEOHub --skill geo-diagnose

Then prepare a brief JSON with the target URL and run:

python3 scripts/run_diagnose.py --input brief.json --output ./runs --execution-mode deterministic

Inspect quality-report.json and the remediation query map before taking any action. Full usage details live in the skill listing and the GitHub repo.

Compare before adopting

Evaluate geo-diagnose against alternatives by checking: quality signals — does the report include source status and limitation sections? Maintenance freshness — is the diagnosis method updated as AI platforms evolve? Alternatives — simpler URL-scraping tools may lack replayable evidence or structured remediation maps. Workflow fit — does your agent need deterministic output for CI, or is a research-oriented mode more useful?

Why it is worth tracking

With 152 stars and active development under yaojingang/GEOHub, geo-diagnose shows steady community interest in evidence-backed GEO auditing. Its distinction between diagnosis and live measurement fills a real gap — most tools either scrape blindly or promise ranking data they can't deliver. Track it if you're building agents that need to justify content changes with reproducible evidence, and re-evaluate when the skill adds new audit components or adapts to emerging AI-platform citation patterns.