agentleFS
psyducklerpsyduckler/aeo-skills/aeo-competitor-monitor/SKILL.md

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

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
  1. Distinctive:

    No pip dependencies (stdlib only)

    line 33
  2. Very specific:

    Run from the skill directory.

    line 74
  3. Very specific:

    Create an alerts.json file with threshold rules.

    line 106
  4. Distinctive:

    After each scan, prints a quick summary:

    line 149
  5. Distinctive:

    Run scans weekly or biweekly for meaningful trend data

    line 241
  6. Distinctive:

    After publishing new content, wait 2-4 weeks before expecting citation changes

    line 243
  7. Very specific:

    Use alongside aeo-analytics-free for your own brand tracking

    line 244
  8. Very specific:

    Use aeo-ai-overview-simulator for deep-dive into specific prompts

    line 245
  9. Distinctive:

    Never overwrites historical data — each scan appends

    line 256

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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_KEY env 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 30

Report — 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 json

Alerts — 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 json

Run from the skill directory. Resolve scripts/monitor.py relative to this SKILL.md.

Options

Scan Options

OptionDefaultDescription
--prompts(required)One or more prompts to scan
--competitors(required)One or more competitor domains to track
--data-filemonitor-data.jsonPath to the data file (created if missing)
--runs20Runs per prompt
--modelgemini-3-flash-previewGemini model
--concurrency5Max parallel API calls

Report Options

OptionDefaultDescription
--data-filemonitor-data.jsonPath to the data file
--outputtextOutput format: text or json

Alerts Options

OptionDefaultDescription
--data-filemonitor-data.jsonPath to the data file
--configalerts.jsonAlert config file path
--outputtextOutput 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

TypeFires whenWhat it means
competitor_aboveA competitor's citation rate exceeds threshold %Competitor has entered or solidified their position in the recurring retrieval set
self_belowYour own citation rate drops below threshold %You're falling out of the candidate set — content refresh needed
position_dropYour citation position drops by N positionsYour structural influence is declining even if still cited
new_competitorA domain not seen in previous scans appears with >N% citation rateNew 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 rate

Report 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-free for your own brand tracking
  • Use aeo-ai-overview-simulator for 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.