aeo-competitor-monitor
Skill13 starsChanged 6 months agoMITView on GitHub
Track competitor citations in AI Overviews over time. Runs prompts through Gemini 3 Flash with grounding and records which competitor domains get cited, how often, and with what snippets. Saves results to an append-only JSON data file for trend analysis. Generates comparison reports showing citation share changes over time. Use when a user wants to: track competitors' AI visibility, compare citation share across brands, monitor who's winning AI Overviews for key prompts, or detect when competitors gain or lose AI citations.
- Reads credentials
In this repository22 other files it gives its agents.
- aeo-ai-overview-simulatorSkill
- aeo-analytics-freeSkill
- aeo-baselineSkill
- aeo-cannibalization-detectorSkill
- aeo-citation-gap-finderSkill
- aeo-content-freeSkill
- aeo-entity-extractorSkill
- aeo-freshness-decay-trackerSkill
- aeo-grounding-query-mapperSkill
- aeo-initSkill
- aeo-multi-prompt-strategySkill
- aeo-optimizeSkill
- aeo-pack-ai-toolsSkill
- aeo-pack-b2b-saasSkill
- aeo-pack-local-servicesSkill
- aeo-prompt-frequency-analyzerSkill
- aeo-prompt-question-finderSkill
- aeo-prompt-research-freeSkill
- aeo-reportSkill
- aeo-schemaSkill
- aeo-source-authority-profilerSkill
- aeo-trackSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
No pip dependencies (stdlib only)
- Very specific: line 74
Run from the skill directory.
- Very specific: line 106
Create an alerts.json file with threshold rules.
- Distinctive: line 149
After each scan, prints a quick summary:
- Distinctive: line 241
Run scans weekly or biweekly for meaningful trend data
- Distinctive: line 243
After publishing new content, wait 2-4 weeks before expecting citation changes
- Very specific: line 244
Use alongside aeo-analytics-free for your own brand tracking
- Very specific: line 245
Use aeo-ai-overview-simulator for deep-dive into specific prompts
- Distinctive: line 256
Never overwrites historical data — each scan appends
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AEO Competitor Monitor
Source: github.com/psyduckler/aeo-skills Part of: AEO Skills Suite
Track which competitors get cited in AI Overviews — and how that changes over time.
Why This Matters
AI Overviews create a new competitive landscape. Influence happens at retrieval, not inside the model — the sources Gemini cites for your key prompts form the recurring retrieval set, and those are your real competitors. Gemini is search-first, searching before nearly every answer — influence compounds through repeated inclusion in this set. Tracking citation share over time reveals shifts in the recurring retrieval set:
- Who's gaining ground — new content entering the recurring retrieval set
- Who's losing ground — previously-cited pages dropping out of the candidate set
- Market dynamics — how the retrieval set shifts with content updates, algorithm changes
- Your relative position — where you stand in the candidate set vs competitors
Requirements
- Gemini API key (free) — set as
GEMINI_API_KEYenv var - Python 3.9+
- No pip dependencies (stdlib only)
Usage
Scan — Run a new competitive scan
# Scan two prompts, tracking three competitors
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/monitor.py scan \
--prompts "best SEO tools" "content optimization software" \
--competitors acme.com surferseo.com semrush.com \
--data-file monitor-data.json
# With custom run count
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/monitor.py scan \
--prompts "best SEO tools" \
--competitors acme.com surferseo.com \
--data-file monitor-data.json \
--runs 30Report — Generate a comparison report
# Text report
python3 scripts/monitor.py report --data-file monitor-data.json
# JSON report
python3 scripts/monitor.py report --data-file monitor-data.json --output jsonAlerts — Check for threshold violations
# Check alerts against thresholds
python3 scripts/monitor.py alerts --data-file monitor-data.json --config alerts.json
# JSON output
python3 scripts/monitor.py alerts --data-file monitor-data.json --config alerts.json --output jsonRun from the skill directory. Resolve scripts/monitor.py relative to this SKILL.md.
Options
Scan Options
| Option | Default | Description |
--prompts | (required) | One or more prompts to scan |
--competitors | (required) | One or more competitor domains to track |
--data-file | monitor-data.json | Path to the data file (created if missing) |
--runs | 20 | Runs per prompt |
--model | gemini-3-flash-preview | Gemini model |
--concurrency | 5 | Max parallel API calls |
Report Options
| Option | Default | Description |
--data-file | monitor-data.json | Path to the data file |
--output | text | Output format: text or json |
Alerts Options
| Option | Default | Description |
--data-file | monitor-data.json | Path to the data file |
--config | alerts.json | Alert config file path |
--output | text | Output format: text or json |
Alert Configuration
Create an alerts.json file with threshold rules. Alerts monitor shifts in the recurring retrieval set:
{
"alerts": [
{"type": "competitor_above", "domain": "competitor.com", "threshold": 50, "prompt": "*"},
{"type": "self_below", "domain": "mybrand.com", "threshold": 30, "prompt": "*"},
{"type": "position_drop", "domain": "mybrand.com", "positions": 3, "prompt": "*"},
{"type": "new_competitor", "prompt": "*", "min_citation_rate": 20}
]
}Alert Types
| Type | Fires when | What it means |
competitor_above | A competitor's citation rate exceeds threshold % | Competitor has entered or solidified their position in the recurring retrieval set |
self_below | Your own citation rate drops below threshold % | You're falling out of the candidate set — content refresh needed |
position_drop | Your citation position drops by N positions | Your structural influence is declining even if still cited |
new_competitor | A domain not seen in previous scans appears with >N% citation rate | New entrant into the recurring retrieval set — potential threat |
Set prompt to "*" to check all tracked prompts, or specify a single prompt string.
Alert Output Example
⚠️ 3 alert(s) triggered:
============================================================
🔴 COMPETITOR ABOVE THRESHOLD
semrush.com citation rate (85%) exceeds threshold (50%) for "best SEO tools"
🟡 SELF BELOW THRESHOLD
mybrand.com citation rate (15%) below threshold (30%) for "content optimization"
🆕 NEW COMPETITOR
New competitor newsite.io appeared with 35% citation rate for "best SEO tools"Output
Scan Output
After each scan, prints a quick summary:
Scan complete: 2 prompts × 20 runs
Saved to monitor-data.json (scan #3)
Quick Results:
"best SEO tools":
acme.com — 75% citation rate
surferseo.com — 60% citation rate
semrush.com — 85% citation rate
"content optimization software":
acme.com — 80% citation rate
surferseo.com — 45% citation rate
semrush.com — 55% citation rateReport Output
Competitor Monitor Report
Data: monitor-data.json (3 scans, 14 days)
================================================================
CITATION SHARE BY PROMPT:
"best SEO tools" (3 scans):
Competitor Latest Avg Trend
─────────────────────────────────────────
semrush.com 85% 80% ↑ +10%
acme.com 75% 70% → stable
surferseo.com 60% 65% ↓ -5%
"content optimization software" (3 scans):
Competitor Latest Avg Trend
─────────────────────────────────────────
acme.com 80% 75% ↑ +10%
semrush.com 55% 60% ↓ -10%
surferseo.com 45% 50% ↓ -5%
OVERALL CITATION SHARE (across all prompts):
semrush.com — 70% avg citation rate
acme.com — 78% avg citation rate
surferseo.com — 53% avg citation rate
NOTABLE CHANGES:
↑ acme.com gained +10% on "content optimization software"
↓ semrush.com dropped -10% on "content optimization software"
CITED URLS:
acme.com:
- https://acme.com/blog/content-optimization (12x)
- https://acme.com/product (5x)
...Data File Format
The data file is append-only JSON. Each scan adds an entry:
{
"scans": [
{
"timestamp": "2025-03-15T14:30:00Z",
"model": "gemini-3-flash-preview",
"runs_per_prompt": 20,
"results": {
"best SEO tools": {
"successful_runs": 20,
"competitors": {
"acme.com": {
"citation_rate": 75,
"citation_count": 15,
"cited_urls": {"https://acme.com/blog/seo-tools": 10},
"mentioned": true,
"excerpts": ["Acme is a leading content optimization..."]
}
},
"other_sources": [
{"domain": "g2.com", "citation_rate": 40}
]
}
}
}
]
}Tips
- Run scans weekly or biweekly for meaningful trend data
- Track 5-10 prompts and 3-5 competitors for focused insights
- After publishing new content, wait 2-4 weeks before expecting citation changes
- Use alongside
aeo-analytics-freefor your own brand tracking - Use
aeo-ai-overview-simulatorfor deep-dive into specific prompts - Citation rates fluctuate naturally (±5-10%) — look for sustained trends over 3+ scans
Further Reading
Notes
- Gemini API key in macOS Keychain under
google-api-key - Data file is created automatically on first scan
- Never overwrites historical data — each scan appends
- Retries with exponential backoff for API failures
- API cost: ~400 calls per scan (20 prompts × 20 runs). Free tier supports this.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

