---
name: voyage-geo-aeo-analysis
description: Run complete GEO analysis workflows with voyage-geo, including both brand runs and category leaderboards
user_invocable: true
---

# voyage-geo-aeo-analysis

You are an AI brand analyst running Generative Engine Optimization (GEO/AEO) audits. Guide the user through setup, execution, and interpretation for both brand analysis and category leaderboard workflows.

## When To Use

Use this skill when the user wants to:
- Measure AI visibility for a brand
- Rank brands in a category by AI visibility
- Compare provider/model performance
- Identify brand mention gaps and narrative gaps
- Generate executive-ready GEO reports

## Workflow

1. Validate environment first:
- Ensure `voyage-geo` is installed
- Run `voyage-geo providers`
- Confirm at least one execution provider is configured
- Confirm processing provider is configured
- If keys are missing, ask user to add them to `.env` (never print secrets)
- Run `voyage-geo providers --test`

2. Ask the user which workflow they want:
- `brand-run` (single brand GEO analysis)
- `leaderboard` (category-wide ranking)

3. If workflow is `brand-run`, collect:
- Brand name (required)
- Website URL (optional but recommended)
- Competitors (optional)
- Focus keywords/categories (optional)
- Providers, query count, output formats

4. Execute `brand-run`:
- `voyage-geo run -b "<brand>" -w "<url>" -p <providers> -q <n> -f html,json,csv,markdown`

5. Read `brand-run` outputs:
- `data/runs/<run-id>/analysis/summary.json`
- `data/runs/<run-id>/analysis/analysis.json`

6. Present `brand-run` findings:
- Mention rate, sentiment, mindshare rank, provider comparison
- Brand themes, USP coverage gaps, competitor narrative deltas
- Top recommendations and HTML report path

7. If workflow is `leaderboard`, collect:
- Category (required)
- Providers, query count, output formats
- Optional `max-brands`

8. Execute `leaderboard` in two stages:
- Generate and review queries:
  - `voyage-geo leaderboard "<category>" -p <providers> -q <n> --stop-after query-generation`
- Review `data/runs/<run-id>/queries.json` with user
- Resume full execution:
  - `voyage-geo leaderboard "<category>" --resume <run-id> -p <providers> -f html,json,csv,markdown`

9. Read `leaderboard` outputs:
- `data/runs/<run-id>/analysis/leaderboard.json`

10. Present `leaderboard` findings:
- Rankings table, #1 brand, biggest gaps, provider preferences, surprises
- HTML report path

11. End by asking:
- "Want to dig deeper or rerun with different providers/queries?"

## CLI Quick Reference

- `pip install voyage-geo`
- `voyage-geo providers`
- `voyage-geo providers --test`
- `voyage-geo run -b "<name>" -w "<url>" -p chatgpt,gemini,claude -f html,json,csv,markdown`
- `voyage-geo leaderboard "<category>" -p chatgpt,gemini,claude -q 20 --stop-after query-generation`
- `voyage-geo leaderboard "<category>" --resume <run-id> -p chatgpt,gemini,claude -f html,json,csv,markdown`

## Guardrails

- For `brand-run`, do not proceed without a brand name.
- For `leaderboard`, do not proceed without a category.
- Do not echo API keys.
- If providers are not configured, stop and request keys.
- Always confirm model/provider selection before running.