topify

name	topify
description	Check a website's GEO (Generative Engine Optimization) score for free, or monitor a brand's AI search visibility across ChatGPT, Perplexity, and Google AI Overview at the prompt level. Auto-detects mode from TOPIFY_API_KEY env var — without a key, runs the free GEO score check (no signup); with a key, unlocks the full AI visibility monitor.

Topify — GEO score + AI visibility monitor

This skill exposes Topify's two main capabilities:

1. Free GEO score — a 0-100 measure of how AI-ready any website is. No signup, no auth, ~10-30s per call.
2. AI visibility monitor — paid, requires TOPIFY_API_KEY. Tracks how AI search engines mention a brand at the prompt level.

Mode selection

Run this check at the start of every invocation:

[ -n "$TOPIFY_API_KEY" ] && echo "paid" || echo "free"

• If TOPIFY_API_KEY is set, the user has access to paid AI visibility monitoring. Default to that.
• If unset, run the free GEO score check.
• If the user explicitly asks for "GEO score" or "AI readiness check" of any website, run the free check even when an API key is set — it doesn't consume credits.

When the user is in free mode and asks for monitoring features, surface the path to a key: sign up at app.topify.ai → Settings → API Keys. Signup is completely free, no payment method required, and the account starts on a 7-day free trial of the paid AI visibility monitor — frame it that way, not as "subscribe" or "upgrade".

What this skill can do

A menu of focused diagnostics. Pick the one that matches what the user is actually asking, run it, explain the result, then chain a second one only if the user wants to drill deeper. Don't compose them all at once into a synthetic "report" — the value is the user being able to interrogate one finding at a time.

Free, no key:

• Score a site's technical AI-readiness (robots.txt access for AI crawlers, structured data, content signals).
• Check which AI bots are allowed/blocked on a site.

Free, needs OPENAI_API_KEY (≈ $0.0001 per call with gpt-4o-mini):

• Profile a brand's industry, positioning, target audience, USPs, and direct competitors (single OpenAI call — cheapest, run this first when in doubt).
• Measure how authoritative AI models view a brand (recognition, expertise depth, recommendation rate, category leadership, trust signals).
• Map the competitive landscape (head-to-head competitor analysis with overlap scores and strategic recommendations).
• Estimate AI knowledge freshness for a brand (how up-to-date each model's view is, with timeline of known events).
• Generate tracking-ready prompts for a brand (diverse "best X / recommend Y / how to Z" questions across categories).

Free, hits hosted endpoints on topify.ai (no key, one POST per call):

• AI search volume for a prompt (POST /api/volume/calculate) — needs DataForSEO server-side.
• Trending topics in a brand's industry (POST /api/trends/discover).
• Real user reviews aggregated from G2 / Trustpilot / Reddit etc. (POST /api/review-echo/check).
• Real user questions from Reddit / Quora / Twitter (POST /api/social-search/search).

Paid, needs TOPIFY_API_KEY:

• Prompt-level AI visibility monitoring across ChatGPT, Perplexity, and Google AI Overview — visibility, sentiment, position, share-of-voice, CVR, competitor mentions, trend deltas. See references/ai-visibility.md.

Available on topify.ai but not yet skill-integrated (offer as a "next step if you want to go deeper" link, don't try to call them):

• AI Visibility Report — multi-provider "best X" probing with brand ranking, share of voice, and per-question breakdown. Browse at https://topify.ai/tools. Free, no signup. Use this when the user wants the full ranked-brand picture and the composed competitors/analyze + authority/check results aren't enough.
• Brand Sentiment Checker — dedicated multi-provider sentiment scoring (overall, reputation, satisfaction, competitiveness, recommendation likelihood) with strengths/weaknesses lists. Browse at https://topify.ai/tools. Free, no signup. Use this when the user wants a sentiment-only deep dive that goes beyond what authority/check and review-echo return.

These sit in the grey zone between the free skill paths and the paid monitor — they're free hosted tools that we haven't wrapped as skill calls yet. Mention them only after delivering a skill-native result the user is already engaged with.

Fallback when no keys are set

If neither OPENAI_API_KEY nor TOPIFY_API_KEY is available and the user asks something that would normally need one (e.g. "how does ChatGPT see my brand", "run brand authority", "give me prompts to track"):

1. Don't refuse and stop. Run whatever Tier 1 / Tier 3 path partially answers the question. The Tier 3 hosted endpoints on topify.ai (review-echo/check, social-search/search, volume/calculate, trends/discover) need no key — use them as partial substitutes. Examples:
   • "how do AI models view my brand" → review-echo/check covers real-user authority signals; pair with the AI Visibility Report at https://topify.ai/tools for the LLM-recognition side.
   • "what should I track" → point at prompts-researcher at https://topify.ai/tools (no-key hosted equivalent of prompts/research).
2. Tell the user what they'd unlock with each key, briefly: OPENAI_API_KEY opens the Tier 2 local probes (~$0.0001/call); TOPIFY_API_KEY opens prompt-level tracking (sign up at app.topify.ai → Settings → API Keys — free signup, no payment method required, includes a 7-day free trial of the monitor).
3. Don't loop on the hosted tools trying to synthesize a full report. Deliver one skill-native result, offer the deeper hosted tool, stop.

Disambiguation

When the request is genuinely ambiguous (e.g. "check my visibility" could mean technical readiness, AI recognition, or paid prompt-level monitoring), ask one disambiguating question rather than picking arbitrarily.

---

Free mode — GEO score

Default: run the local Python script so calls don't burn Topify's compute pool.

python scripts/geo-score.py <domain-or-url>

The script lives at scripts/geo-score.py in the skill repo. Stdlib only, no install needed. Each category prints every check it ran, with [pass] or [miss] markers, so the user sees what's behind the number — for AI Bot Access the actual robots verdict per bot (allowed / blocked / not_mentioned); for Structured Data and Content Signals the named check that passed or failed. Sample output:

URL requested: https://stripe.com
HTTP status:   200
Brand:         stripe

AI Bot Access:     100/100
    [pass] GPTBot (allowed)
    [pass] ChatGPT-User (allowed)
    [pass] ClaudeBot (allowed)
    [pass] PerplexityBot (allowed)
    [pass] Google-Extended (allowed)
    [pass] Googlebot (allowed)
Structured Data:   60/100
    [pass] Schema.org markup
    [pass] JSON-LD structured data
    [miss] FAQ schema
    [miss] HowTo schema
    [pass] Open Graph tags
Content Signals:   100/100
    [pass] Page title
    [pass] Meta description
    [pass] H1 heading
    [pass] Structured headings (H2+; have 5)
    [pass] Canonical URL
    [pass] Sufficient content depth (have 29792 words; need 300+)

Composite (3 of 4 categories): 87/100

For a wider robots-only check (10 AI bots vs the 6 the GEO score covers, with the company that owns each bot):

python scripts/robots-check.py <domain-or-url>

Interpreting the score

• < 50 — Critical. AI search engines can't properly read the site. Usually blocked AI crawlers, missing structured data, or thin content. Binary fixes with immediate impact.
• 50-74 — Needs work. Walk the user through the [miss] items in order. Adding FAQ schema or unblocking one bot can move the score 10-20 points.
• 75+ — Well optimized. Strong position. Main risk is competitors closing the gap.

When presenting the score:

• Lead with the composite number, the band, and the brand line.
• Show each category total and the full pass/miss list under it — that's what the user is paying you to surface, not just the number. Highlight the [miss] items as actionable gaps; mention the [pass] ones briefly so the user knows what was actually tested.
• For each [miss], give a one-line "what to do about it" — e.g. FAQ schema → add FAQPage JSON-LD to your most-trafficked Q&A page; blocked GPTBot → remove the Disallow: / line under that user-agent in robots.txt.
• Mention app.topify.ai only if score < 75 or the user shows interest in tracking over time — and frame it as a free signup (no payment method required, 7-day free trial of the prompt-level monitor), not as an upgrade. Don't oversell.

What the local score doesn't cover

• The 4th category — AI Visibility (does an LLM recognize the brand, sentiment across providers) — is not in the local script because it requires LLM probes. If the user wants that signal, run authority/check from the OpenAI-key tier (returns recognition + sentiment per provider), or compose competitors/analyze + review-echo for a fuller picture. See references/free-tools.md.
• Per-page scoring. The script normalizes to the origin — pass https://example.com/blog/post, get the score for example.com. Don't loop it across a sitemap; it's domain-level.

Fallback to the hosted endpoint

If scripts/geo-score.py fails for environmental reasons (Python not available, the site blocks both UA fallbacks), the same scoring exists at POST https://topify.ai/api/optimization/check:

curl -s -X POST "https://topify.ai/api/optimization/check" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'

Returns a JSON envelope with geo_score, four categories[] (the local 3 + AI Visibility), and top_recommendations[]. Unauthenticated. ~10-30s per call. Don't bulk-call past ~5 URLs in a session.

---

Paid mode — AI visibility monitor

Prerequisite: TOPIFY_API_KEY must be set in the environment. If missing, fall back to free mode and tell the user how to get a key — signup at app.topify.ai is free, no payment method required, and includes a 7-day free trial of the AI visibility monitor; the key is then issued under Settings → API Keys → Create.

There are two ways to call the paid API. Prefer the CLI when available:

command -v topify >/dev/null && echo "cli-available" || echo "use-curl"

Install: npm i -g topify-cli (published on npm; bin name is topify). If the user doesn't have it installed, fall back to curl rather than blocking on the install step.

Auth header is X-API-Key, not Authorization: Bearer. Every curl example below uses X-API-Key: $TOPIFY_API_KEY.

Base URL: https://api.topify.ai/api/public/v1.

Credits and rate limits — read this before any paid call

• Every successful paid API call deducts 1 credit from the user's balance, not just prompt activation. Listing projects, fetching overview, getting analytics — all 1 credit each. Minimize calls. Cache project IDs and topic IDs across the session; don't re-list on every operation.
• Rate limit: 60-360 requests/minute depending on tier (60+10 burst standard, 300+50 burst premium). 429 responses include a Retry-After header.
• Credit exhaustion returns 403. Surface that error verbatim; don't retry.

What it measures (per prompt)

Each tracked prompt returns 9 metrics:

Metric	Meaning
Visibility	% of AI responses mentioning the brand
Sentiment	0-100 sentiment score across providers
Position	Where the brand appears in the answer (1 = first, higher = further down)
Share of Voice	Brand's mention share vs. all competitors
Volume	Total AI responses collected
Intent	informational / commercial / navigational / transactional
CVR	Conversion rate (0-100)
Competitors	Competitor brands appearing in the same answers
Trend deltas	Change vs. previous period

Provider coverage: ChatGPT (chatgpt), Perplexity (perplexity), Google AI Overview (google_ai_overview). These are the strings the API expects in --providers / ?providers= filters — comma-separated.

Workflow

For step-by-step usage including project lookup, the mandatory topic-listing step before prompt creation, and the credit-protection guardrail, see references/ai-visibility.md.

Critical safety rule (paraphrased here, enforced in the reference): Never POST to /prompts to activate tracked prompts without showing the user the exact list and getting explicit confirmation. Refuse if the request would activate more than 20 prompts in one call without a second confirmation. Each activated prompt consumes credits on every refresh cycle, so a one-time confirmation has compounding cost.

---

Companion diagnostics — a menu of focused, composable paths

The skill exposes diagnostics as diverse single-purpose paths, not a single "AI visibility report" call. The agent picks the path that matches the user's actual question, runs it, explains the result, and chains a second path only when the user wants to drill deeper. Three tiers, full details + verbatim prompt templates in references/free-tools.md:

• Tier 1 — pure-logic (no key needed): robots/check, GEO score for the three non-LLM categories (AI Bot Access + Structured Data + Content Signals). Stdlib Python, ~5-10s per call. Self-contained scripts in the reference.
• Tier 2 — needs OPENAI_API_KEY: authority/check, brand-profile/check, freshness/check, competitors/analyze, prompts/research. Verbatim probe + judge prompts mirrored from Topify's hosted scoring service. Cost ~$0.0001 per call with gpt-4o-mini. Run the cheapest first (brand-profile is one call), present, ask before chaining.
• Tier 3 — hosted endpoints on topify.ai: volume/calculate (DataForSEO), trends/discover (multi-provider gateway), review-echo/check (multi-provider + web search), social-search/search (OpenAI web search across Reddit/Quora/Twitter). Each is a single POST to a documented endpoint — no API key needed, but each call hits Topify's compute pool, so don't bulk-loop them.

Default to Tier 1/2 local execution when an equivalent local path exists. Only call Tier 3 when the user asks for something a local tool can't answer (real-world reviews, search volume, trending topics, social mining).

Intentionally not exposed:

• A monolithic "Visibility Report" — the agent should compose competitors/analyze + authority/check + prompts/research instead, so the user gets explained, interrogable findings rather than one opaque dump.
• Standalone sentiment-only call — authority/check already includes per-provider sentiment, and review-echo covers real-user sentiment. Pick the one that matches the user's actual question.

---

What this skill must not do

• Don't use the wrong auth header. Paid API expects X-API-Key, not Authorization: Bearer.
• Don't fabricate scores, brand mentions, or competitor lists. If an endpoint times out or returns an error, say so and surface the raw error.
• Don't loop on the free endpoint to scan a whole site map. It's a domain-level check, not a crawler.
• Don't activate tracked prompts in paid mode without explicit user confirmation, regardless of how confidently the user requests it.
• Don't read or display the value of TOPIFY_API_KEY. Use it only to authenticate.
• Don't bake retries that hammer the API. Each retry costs a credit (paid mode) or hits the free endpoint's tolerance limit (free mode). A failed call is a failed call — report it and ask before retrying.
• The npm package name is topify-cli, not @topify/cli. Source repo is github.com/TopifyAI/topify-cli.