Grok Geo

grok-geo Skill

> Pattern: Pipeline + Inversion + Reviewer > This skill enforces a strict multi-step pipeline with gate conditions. > It interviews the user for missing inputs before acting (Inversion). > It runs a quality review checklist before finalizing the report (Reviewer).

Objective

Produce a traceable AI-search/GEO audit for one brand using current web search, deterministic metric calculation, and evidence-backed recommendations.

Required tools

• web_search
• shell

If websearch is unavailable, switch to OFFLINEIMPORT mode. Never fabricate search results or citations.

Required input

Minimum:

• brand_name
• website
• industry
• target_customer

Recommended:

• target_region
• competitors
• brand_aliases
• products
• known_facts
• forbidden_claims

Operating modes

• quick: 10 questions, 1 query per question, 60-second snapshot
• standard: 30 questions, up to 2 variants, full diagnostic
• offline_import: analyze provided search results without new web searches

Paths

• Skill root: directory containing this SKILL.md
• Scripts: scripts/
• Modules: modules/ (v1.1+ optional extensions)
• Default run base (hosted): /mnt/data/geo-audit-runs
• Local override: environment variable GEO_AUDIT_RUNS_DIR or ./geo-audit-runs
• Python: use the runtime interpreter (python3 / python)

---

Phase 0 — Input Collection (Inversion Pattern)

DO NOT start the audit until all required inputs are confirmed.

If the user provides a partial input, ask for missing fields in this order:

1. brand_name: "What is the exact brand or company name to audit?"
2. website: "What is the official website URL?"
3. industry: "What industry or product category? (e.g., SaaS, e-commerce, local service)"
4. target_customer: "Who is the target customer? (e.g., SMB teams, enterprise, consumers)"
5. target_region: "Which geographic region(s)? (default: global)"
6. competitors: "Any known competitors to compare against?"

Once all minimum fields are confirmed, proceed to Phase 1. If the user wants a quick snapshot, set mode=quick and skip Phase 0 questions.

---

Phase 1 — Validation & Initialization

python /scripts/validate_input.py \
  --input /path/to/input.json \
  --output /intermediate/normalized_input.json

python /scripts/initialize_run.py \
  --input /intermediate/normalized_input.json \
  --base-dir "$GEO_AUDIT_RUNS_DIR"

Gate: Do NOT proceed to Phase 2 unless validate_input returns ok: true.

---

Phase 2 — Brand Research

1. Use web_search to research the official brand website.
2. Extract and verify key facts (founding year, products, pricing, certifications).
3. Save verified facts to brand.json known_facts field.
4. Detect business type from industry signals:

| Business Type | Signals | Question Bias | |---|---|---| | SaaS | Pricing page, free trial, API docs, dashboard | Comparison, use-case, integration | | E-commerce | Product pages, cart, reviews, price elements | Purchase, trust, comparison | | Local Service | Phone, address, service area, Google Maps | Recommendation, location, trust | | Publisher | Blog, articles, bylines, publication dates | Authority, content quality | | Agency | Portfolio, case studies, client logos | Credibility, results, comparison |

Gate: Do NOT proceed to Phase 3 without at least 2 verified facts.

> Optional extensions (run after core research): > - v1.1-v1.3 Deep Scoring: see [modules/brand-depth-scoring.md](modules/brand-depth-scoring.md) — site readiness, freshness, citability, trust stack > - v1.9 GEO Lint: see [modules/geo-lint.md](modules/geo-lint.md) — 92-rule pre-publish compliance check > - v2.1 Entity KG: see [modules/entity-kg.md](modules/entity-kg.md) — entity completeness & knowledge graph scoring

---

Phase 3 — Question Map Generation

Generate questions following these constraints:

• quick mode: 10 questions, 1 query variant each
• standard mode: 30 questions, up to 2 query variants each
• At least 70% must NOT contain the target brand name
• At least 30% must be recommendation/comparison/purchase intent
• Brand-fact intent must not exceed 20%
• Bias questions based on detected business type (see Phase 2 table)

python /scripts/validate_questions.py \
  --questions /intermediate/questions.json \
  --input /input/brand.json

Gate: Do NOT proceed to Phase 4 unless validate_questions returns ok: true.

> Optional: v1.7 Funnel Stage Classification — see [modules/funnel-journey.md](modules/funnel-journey.md)

---

Phase 4 — Search Execution

Execute searches in batches of 5 questions per batch.

1. For each question: call web_search, persist result immediately via scripts/append_search_result.py
2. A failed question must NOT abort the whole run
3. Do NOT fabricate search results or citations

Gate: At least 80% of questions must have successful results before proceeding.

> Optional extensions: > - v1.4-v1.5 Enhanced Pipeline: see [modules/search-pipeline.md](modules/search-pipeline.md) — signal extraction, query templates, quality scoring, retry, drift detection > - v2.0 Multi-Engine: see [modules/multi-engine.md](modules/multi-engine.md) — 6 AI engine API queries with auto-fallback

---

Phase 5 — Entity & Citation Analysis

1. Analyze each search result for brand/competitor mentions (Agent task)

• Extract: recommendation_type, sentiment_score, competitor_co_mentions

1. Write entity analysis to intermediate/entity_analysis.jsonl
2. Classify citations:

python /scripts/classify_citations.py \
  --run-dir  \
  --output /intermediate/citations.json

1. Verify claims against known facts (Agent task)
2. Write claims to intermediate/claims.json

> Optional: v1.3 AI Perception, v1.7 Attribute Analysis, v1.8 Publisher Influence — see [modules/funnel-journey.md](modules/funnel-journey.md)

---

Phase 6 — Metric Calculation

All numeric metrics MUST be produced by the script. Do NOT hand-calculate.

python /scripts/calculate_metrics.py \
  --questions /intermediate/questions.json \
  --entities /intermediate/entity_analysis.jsonl \
  --citations /intermediate/citations.json \
  --claims /intermediate/claims.json \
  --output /intermediate/metrics.json

> Optional: v1.7 Funnel-Stage Metrics, v1.8 Journey Metrics — see [modules/funnel-journey.md](modules/funnel-journey.md)

---

Phase 7 — Opportunity Generation

1. Generate no more than 10 opportunities (Agent task)
2. Rank by score:

python /scripts/rank_opportunities.py \
  --input /intermediate/opportunities.draft.json \
  --output /intermediate/opportunities.json

1. Generate no more than 5 content briefs (Agent task)

---

Phase 8 — Quality Review (Reviewer Pattern)

Before generating the final report, run this quality checklist:

| # | Check | Severity | Action if Fail | |---|---|---|---| | 1 | All required output files will be generated | ERROR | Fix before rendering | | 2 | Metrics.json exists and is valid JSON | ERROR | Re-run calculatemetrics | | 3 | At least 80% search success rate | WARNING | Mark as PARTIAL | | 4 | No fabricated URLs in evidence | ERROR | Remove fabricated URLs | | 5 | Limitation statement will be included | ERROR | Add LIMITATIONTEXT | | 6 | Opportunities /scripts/render_report.py --run-dir

> **Optional**: v1.9 Schema Automation (AI-readable file generation) — see [modules/schema-automation.md](modules/schema-automation.md)

---

## Phase 10 — Continuous Monitoring & Scheduled Audits

### 10a. Baseline Metrics Storage

After Phase 9 completes, persist metrics to history for drift detection:

```bash
python /scripts/monitor.py 

This stores current metrics in /metrics_history.jsonl for future comparison.

10b. Visibility Alert Check

Compare current metrics against baseline thresholds:

python /scripts/monitor.py  --check-alerts

Alert rules (configurable):

• geo_score /alerts.json`

10c. Scheduled Audit Setup

To set up recurring audits, use the scheduler:

# Add a daily audit at 02:00
python /scripts/scheduler.py --add "brand-weekly" \
  --brand-config /input/brand.json \
  --cron "0 2 * * 1"

# List configured schedules
python /scripts/scheduler.py --list

# Run a specific schedule on-demand
python /scripts/scheduler.py --run "brand-weekly"

# Run all enabled schedules
python /scripts/scheduler.py --run-all

Windows Task Scheduler integration:

python /scripts/scheduler.py --add "brand-daily" \
  --brand-config /input/brand.json
# Then register: schtasks /create /tn "GEOAudit_brand-daily" /tr "..." /sc daily /st 02:00

10d. Drift Detection (requires baseline run)

Compare current run against a previous baseline:

python /scripts/detect_drift.py --baseline  --current 
python /scripts/detect_visibility_alerts.py --baseline  --current 
python /scripts/chain_runs.py --baseline  --current 

10e. Closed-Loop Optimization

Generate actionable improvement plans from drift analysis:

python /scripts/generate_improvement_plan.py --run-dir 
python /scripts/generate_closed_loop_actions.py --run-dir 
python /scripts/generate_optimization_actions.py --run-dir 

> Gate: Phase 10 is optional. Skip if user only needs a one-time audit.

---

Phase 11 — Final Validation

python /scripts/validate_report.py --run-dir  --update-manifest
python /scripts/package_outputs.py --run-dir 

Gate: Mark COMPLETED only if validate_report returns ok: true. **Gate: If search success rate //output/manifest.json`.

1. Continue from the incomplete stage.
2. Do not re-search questions already present in raw/search_results.jsonl.
3. Failed questions may be retried at most once.

Completion

Return paths to:

• output/report.md
• output/report.json
• output/questions.csv
• output/evidence.csv
• output/opportunities.csv
• output/manifest.json
• output/geo_lint_report.json (if GEO Lint module enabled)
• output/llms.txt (if Schema Automation module enabled)
• output/llms-full.txt (if Schema Automation module enabled)
• output/entity.json (if Schema Automation module enabled)
• output/brand.json (if Schema Automation module enabled)
• output/aeo.json (if Schema Automation module enabled)

References & Metrics

• Methodology docs: See references/methodology/ (20 scoring models & frameworks)
• Specifications: See references/specification/ (10 formal contracts & rules)
• Research notes: See references/research/ (13 external tool research notes)
• Full index: See references/INDEX.md
• Metric definitions: See [METRICS.md](METRICS.md) for all 60+ metric definitions across v1.1-v5.0
• JSON contracts: See schemas/
• Optional modules: See modules/ for v1.1+ extension documentation

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xuboboo
• Source: xuboboo/grok-geo
• License: MIT
• Homepage: https://github.com/xuboboo/grok-geo

Install and usage instructions live in the source repository linked above.