asale-ai/seo-geo-skill / skills/geo-visibility
geo-visibility
VerifiedMeasure whether the answer engines actually mention a brand. Asks ChatGPT, Claude, Perplexity, Gemini, or a local Ollama model the questions real buyers type, then reports mention rate, share of voice against named competitors, which domains get cited instead, and how all of it moved since the last run. Use this whenever someone asks "does ChatGPT mention us", "are we losing AI visibility", "who gets cited instead of us", or wants AI-search visibility tracked over time.
Answer-Engine Visibility
What this measures, and what it does not
Every other GEO check in this toolkit inspects a page and predicts. This one asks the engines and records the answer. Keep the difference visible in every report you write, because it is the difference between advice and evidence.
Two kinds of provider, and they answer different questions:
| Provider | Env var | Answers from | Tells you |
|---|---|---|---|
perplexity | PERPLEXITY_API_KEY | live retrieval, reports its sources | whether your pages get retrieved and cited |
openai | OPENAI_API_KEY | model weights | whether your brand is known |
anthropic | ANTHROPIC_API_KEY | model weights | whether your brand is known |
gemini | GEMINI_API_KEY | model weights | whether your brand is known |
ollama | none — runs locally | local model weights | free smoke-testing, no API bill |
Only retrieval providers can tell you a page was cited. If the user has no retrieval key, say so in the report rather than presenting a mention rate as a citation rate.
Check what is available before promising anything:
seogeo visibility providers
The workflow
1. Build the prompt set — this is the measurement instrument
The prompt set decides the result. A set of branded questions will show a flattering mention rate and tell the user nothing; a set of category questions ("best CRM for a two-person agency") is where visibility is actually won or lost.
Get a scaffold, then rewrite it. You are a language model reading the user's site — you will write better prompts than the template.
seogeo visibility prompts example.com --topic "project management software" --count 20
Save the rewritten set as JSON or one prompt per line:
{"prompts": ["What is the best project management tool for a design studio?", "..."]}
Aim for 20–50 prompts, mostly unbranded, spread across the buying journey: category discovery, comparison, objection ("what are the downsides of…"), and use-case fit. Include 3–5 that name competitors but not the brand.
2. Cost the run before spending anything
Probes = prompts × providers. Fifty prompts against four engines is 200 API calls. Always dry-run first and show the user the number.
seogeo visibility run --brand "Acme" --prompts prompts.json --dry-run
3. Run it
seogeo visibility run --brand "Acme" --domain acme.com --prompts prompts.json \
--competitor "Globex" --competitor "Initech" --label "2026-Q3" --json
--domainis what makescited_own_domainwork — without it, self-citations cannot be detected.--competitoris what makes share of voice meaningful. Without competitors, SoV is always 100%.--aliascatches the other names people use for the brand ("Acme Corp", "AcmeHQ").--labelshows up in the history table; use a release tag or a quarter.--concurrencydefaults to 4. Raise it for large sets, lower it if a provider rate-limits.
4. Read the result
The fields that matter, in the order a client cares about them:
mention_rate— of the answers that came back, how many named the brand.share_of_voice— brand mentions ÷ (brand + competitor mentions). This is the number that moves when a competitor invests and you do not.avg_prominence— 1.0 means named first, 0.1 means named as an afterthought. Engines list the best-known option first, so a falling prominence is an early warning that precedes a falling mention rate.citation_rate— of retrieval answers, how many cited the brand's own domain.cited_domains— who is getting cited. This is the most actionable list in the whole report: it is the set of pages you need to appear on, be reviewed on, or out-rank.unanswered_prompts— the exact questions where the brand is invisible. Hand these to the content plan.
5. Track it
One run is a snapshot and worth little. The value is the trend.
seogeo visibility history --brand "Acme" --days 90
seogeo visibility diff --brand "Acme" --days 30
seogeo visibility citations --brand "Acme" --days 90
visibility diff exits 2 when mention rate or share of voice fell, so it
can gate a scheduled job without parsing the report.
One-off questions
For a single question, without recording a run:
seogeo ask "What is the best project management tool for a design studio?" --brand "Acme" --json
seogeo ask "Who are the leading CRM vendors?" --provider perplexity
Use this while iterating on the prompt set, and to reproduce a single surprising result from a run.
Validating the citability score
The toolkit's citability score claims to predict citations. On any site with a retrieval key, that claim can be checked rather than asserted:
seogeo citability-validate example.com --prompts prompts.json --max-pages 30 --json
It scores the site's pages, asks the retrieval engines the prompt set, and reports the rank correlation between a page's citability score and how often it was actually cited, plus the mean score of cited versus uncited pages.
Report the verdict.caveat verbatim. Small samples produce confident-looking
correlations that mean nothing, and the command flags that itself — do not
strip the flag when summarising.
Scheduling
seogeo watch --brand "Acme" --domain acme.com --prompts prompts.json \
--competitor "Globex" --url https://acme.com/pricing --html
Writes dated JSON artifacts plus report.html under seogeo-watch/, and exits
2 on a regression, 1 if a check could not run. Put it on cron or in a
scheduled CI job; nothing here needs a server.
A ready GitHub Actions workflow ships at templates/geo-watch.workflow.yml in
this repository — it runs weekly, caches the visibility history between runs so
the trend survives, uploads the report as an artifact, and opens an issue only
on exit 2. Copy it into the tracked site's repo rather than pointing it at this
one.
Weekly, not daily. Answer engines are noisy enough that a daily series is mostly variance.
Reporting
seogeo report-html --input visibility.json --output visibility.html --title "Acme"
One self-contained HTML file — no external CSS, fonts, or scripts — so it can be emailed, committed, or dropped on a static host.
Rules
- Never present a model-knowledge answer as a citation. If only
openaiandanthropicare configured, the report says the brand is known or unknown, not that pages were cited. - Always state the sample. "42% mention rate" without "over 24 prompts × 2 engines" is not a finding.
- Show the cost. Every run reports
cost_usd. Include it. - Never invent an answer. If a probe failed, the report says it failed. Failed probes are excluded from rates, and the count is in
summary.failed. - Rerun before concluding a drop is real. Engines are non-deterministic; a single run's mention rate moves several points on its own. Two runs agreeing is the minimum evidence for a trend claim.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |