| name | aeo-source-authority-profiler |
| description | Analyze WHY certain sources get cited by Gemini over others. Runs a prompt through Gemini 3 Flash with grounding, ranks cited sources by frequency, then fetches and profiles the top pages — word count, headings, structured data (JSON-LD), publication dates, and entity density. Outputs a "citation blueprint" showing what top-cited pages have in common. Optionally highlights where a specific domain's pages stand vs the blueprint. Use when a user wants to: understand what makes pages get cited by AI, reverse-engineer citation patterns, build a content template based on what Gemini prefers, compare their content to competitors' cited pages, or audit page-level factors that correlate with AI citations.
|
AEO Source Authority Profiler
Source: github.com/psyduckler/aeo-skills
Part of: AEO Skills Suite
Reverse-engineer WHY certain pages get cited by Gemini — and build a blueprint to replicate their success.
Background
Influence over AI answers happens at retrieval, not inside the model. You can't edit Gemini's weights, but you can enter the candidate set it selects from when it searches the web. Every prompt triggers a retrieval step — Gemini fires search queries, evaluates the results, and picks sources to ground its answer. The pages it picks consistently form the recurring retrieval set for that topic.
This skill profiles the pages inside that recurring set. By analyzing what they have in common — length, structure, schema, freshness, entity density — you get a concrete blueprint for what it takes to enter and stay in the candidate set. Gemini's search-first architecture creates more entry points than recall-first models like GPT, which means the on-page profile of cited sources matters more than ever: retrievability requires alignment with query patterns, comprehensive coverage, and structural clarity.
Why This Works
Not all pages are created equal. When Gemini answers a prompt, it consistently cites certain sources over others. This skill reveals the common profile of those cited pages: their length, structure, schema markup, freshness, and entity density. By running 20 samples, you see which sources are reliably part of the recurring retrieval set (not just lucky once), then by profiling those pages, you discover the on-page signals that correlate with AI citation.
The result is a citation blueprint — a concrete spec for what your content needs to look like to enter the candidate set for that prompt. Influence compounds through repeated inclusion; one-off citations don't matter, but matching the blueprint puts you in the recurring set.
Defaults
- Model:
gemini-3-flash-preview — the same model powering Google AI Overviews
- Samples: 20 runs per prompt — captures probabilistic citation patterns
- Top pages: 10 — profiles the 10 most-cited URLs
Requirements
- Gemini API key (free from aistudio.google.com) — set as
GEMINI_API_KEY env var
- Python 3.9+
- No pip dependencies (stdlib only)
Usage
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/profile.py "best project management tools for startups"
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/profile.py "best project management tools for startups" --domain monday.com
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/profile.py "best CRM software" --domain hubspot.com --runs 30 --top 15
GEMINI_API_KEY="$GEMINI_API_KEY" python3 scripts/profile.py "best SEO tools" --output json
Run from the skill directory. Resolve scripts/profile.py relative to this SKILL.md.
Options
| Option | Default | Description |
|---|
prompt | (required) | The query to analyze |
--domain | (none) | Domain to highlight vs the blueprint (e.g., example.com) |
--runs | 20 | Number of Gemini runs |
--model | gemini-3-flash-preview | Gemini model to use |
--top | 10 | Number of top URLs to fetch and profile |
--concurrency | 5 | Max parallel requests (keep ≤5 to avoid rate limits) |
--output | text | Output format: text or json |
Output
Text Output
Source Authority Profiler: "best project management tools for startups"
Model: gemini-3-flash-preview
Runs: 20/20 successful
Unique URLs cited: 34
TOP CITED PAGES:
======================================================================
#1 — 85% (17/20 runs)
URL: https://monday.com/blog/project-management/best-tools/
Title: Best Project Management Tools for Startups (2025)
Domain: monday.com
Word count: 3,450
Headings: 18 total (H1:1, H2:8, H3:9)
Schema: ✓ JSON-LD (Article, BreadcrumbList)
Published: 2025-01-15
Modified: 2025-03-01
Entity density: 42 entities detected
#2 — 70% (14/20 runs)
...
CITATION BLUEPRINT:
======================================================================
Based on 8 successfully profiled pages
Word count: avg 2,850 | median 2,600 | range 1,200–5,100
Headings: avg 14 | range 6–24
JSON-LD schema: 75% of pages (6/8)
Schema types: Article(5), BreadcrumbList(4), Organization(2)
Entity density: avg 35 | range 12–58
With pub date: 6/8
With mod date: 5/8
Domain diversity: 7 unique domains in top results
DOMAIN ANALYSIS: monday.com
======================================================================
Pages in top 10: 2
https://monday.com/blog/project-management/best-tools/
Word count: 3,450 (+600 vs avg)
Headings: 18 (+4 vs avg)
Schema: ✓
Entities: 42 (+7 vs avg)
JSON Output
Structured JSON with profiles (per-page data), blueprint (aggregate pattern), and domain_analysis (if domain provided).
How It Works
- Phase 1 — Citation Collection: Sends the prompt to Gemini 20 times with Google Search grounding. Extracts all cited URLs from grounding chunks and ranks by frequency.
- Phase 2 — Page Profiling: Fetches the top 10 most-cited URLs using urllib. For each page, parses HTML to extract:
- Word count (visible body text)
- Headings (H1, H2, H3 counts)
- JSON-LD structured data (types like Article, FAQ, Product)
- Publication and modification dates from meta tags
- Entity density (proper nouns, numbers, statistics, quoted terms)
- Phase 3 — Blueprint Generation: Aggregates page profiles into a "citation blueprint" — averages, ranges, and common patterns across all profiled pages.
- Phase 4 — Domain Analysis: If
--domain provided, compares that domain's pages against the blueprint, showing where they exceed or fall short.
Tips
- Use the blueprint as a content spec — match the word count, heading structure, and entity density of pages in the recurring retrieval set
- If your domain isn't in the top results, the blueprint tells you what to aim for to enter the candidate set
- Pages with JSON-LD schema (especially Article, FAQ) get cited more often — use
aeo-schema to add it
- Run for your most important prompts and compare blueprints — different query types may need different content profiles
- Pair with
aeo-content-free to create content that matches the blueprint
- Pair with
aeo-ai-overview-simulator for deeper citation rate tracking over time
- Pair with
aeo-multi-prompt-strategy to find pages that enter the recurring retrieval set across multiple prompts
References
Notes
- Gemini API key stored in macOS Keychain under
google-api-key
- Pages that fail to fetch (timeouts, 403s) are noted but don't crash the analysis
- HTML parsing uses stdlib
html.parser — no external dependencies
- Retries API calls up to 5 times with exponential backoff
- Page fetching uses a 10-second timeout to avoid slow pages blocking the analysis
