Update to 8gnc — Brand Growth Diagnostic

{
  "description": "Use when the user wants to know who the AI engines cite — brand mentions and citations inside Google AI Overviews and ChatGPT answers, AI search volume for a query set, or a competitor comparison of AI-answer presence. Triggers on \"who does ChatGPT cite,\" \"AI mentions,\" \"LLM citations,\" \"AI visibility,\" \"are we showing up in AI Overviews,\" \"AI share of voice,\" \"track our brand in AI answers,\" or any AEO/GEO measurement task. Wraps the DataForSEO LLM Mentions API through the shared dataforseo client.",
  "included_files": [],
  "name": "ai-visibility-tracking",
  "skill_md_contents": "---\nname: ai-visibility-tracking\ndescription: >-\n  Use when the user wants to know who the AI engines cite — brand mentions and\n  citations inside Google AI Overviews and ChatGPT answers, AI search volume for\n  a query set, or a competitor comparison of AI-answer presence. Triggers on\n  \"who does ChatGPT cite,\" \"AI mentions,\" \"LLM citations,\" \"AI visibility,\"\n  \"are we showing up in AI Overviews,\" \"AI share of voice,\" \"track our brand in\n  AI answers,\" or any AEO/GEO measurement task. Wraps the DataForSEO LLM\n  Mentions API through the shared dataforseo client.\n---\n\n# AI Visibility Tracking — LLM Mentions Operational Guide\n\nThe question every operator is starting to ask: *when an AI answers my customer's\nquestion, am I in the answer?* This skill measures it. It pulls citation data from\nGoogle AI Overviews and ChatGPT responses — which domains get cited, for which\nquestions, at what AI search volume — and turns it into a baseline, a competitor\ncomparison, and a monthly tracking cadence.\n\n## File locations (read this first)\n\nUse the same execution boundary as the `dataforseo` skill; the client is shared:\n\n| Context | Client | Working dir | User-facing output |\n|---|---|---|---|\n| Codex with local shell access | Resolve the installed `dataforseo/scripts/dataforseo_client.py` | current workspace | `./ai-visibility-results/YYYYMMDD/` or another user-approved path |\n| ChatGPT or a surface without local shell access | No direct API execution in this skills-only release | conversation or supported file workspace | Analyze user-supplied exports or return the exact data request; never fabricate live measurements |\n\nCredentials load exactly as documented in the `dataforseo` skill. No separate setup.\n\n## When NOT to Use\n\n- No DataForSEO account. Same rule as the dataforseo skill — every call bills.\n- The brand has near-zero web presence. If classic SERPs don't know you, AI engines\n  won't either — run the dataforseo skill's keyword/backlink work and the\n  ai-agent-readiness audit first; come back to measure once there's something to cite.\n- You want to *manipulate* AI answers. This skill measures; the defense/offense\n  content moves live in your strategy work, not in the measurement.\n\n## Cost discipline — read this before the first call\n\n`llm_mentions/*` endpoints are plain pay-per-call like the rest of the\ntoolkit — DataForSEO removed its former $100/month minimum top-up on these\nendpoints in July 2026. Just fund the account (credits never expire, spend on\nany of their APIs).\n\nPricing snapshot (2026-07). Verify the current official DataForSEO pricing before any paid call; do not rely on this table as a live quote:\n\n| Endpoint | Cost | Use for |\n|---|---|---|\n| `ai_keyword_data/keywords_search_volume/live` | $0.01/task | AI search volume per keyword — the cheap step-0 wide pass (no subscription) |\n| `llm_responses/live` | $0.0006/task | Ask a model the actual question, see the answer — spot checks (no subscription) |\n| `llm_mentions/aggregated_metrics/live` | $0.10/task + $0.001/row | Citation counts + AI volume per domain |\n| `llm_mentions/cross_aggregated_metrics/live` | $0.10/task + $0.001/row | You vs. competitors, side by side, one call |\n| `llm_mentions/search/live` | $0.10/task + $0.001/row | Full AI response text + per-citation sources |\n| `llm_mentions/top_domains/live` | $0.10/task + $0.001/row | Who dominates AI citations in your space |\n| `llm_mentions/top_pages/live` | $0.10/task + $0.001/row | The exact PAGES earning citations — teardown targets |\n\nA full baseline (you + 4 competitors, cross-aggregated, both platforms) runs\n$1–3 depending on rows. Coverage: `platform: \"google\"` = AI Overviews;\n`platform: \"chat_gpt\"` = ChatGPT, **United States location only** per DataForSEO.\n\n## Client methods\n\n```python\nclient.ai_llm_mentions_aggregated(\n    targets=[{\"domain\": \"yourbrand.com\", \"search_scope\": [\"sources\"]}],\n    platform=\"google\",            # or \"chat_gpt\"\n    location_name=\"United States\",\n)\n# → mentions count, sources_domain frequencies, ai_search_volume\n\nclient.ai_llm_mentions_search(\n    targets=[{\"keyword\": \"best b2b branding agency dallas\"}],\n    platform=\"google\",\n)\n# → individual citations: full AI response text, sources[] (url, position,\n#   title), triggering question, per-citation ai_search_volume\n```\n\nAdditional methods on the shared client:\n\n```python\nclient.ai_llm_mentions_cross_aggregated(\n    target_groups=[\n        {\"aggregation_key\": \"us\",   \"target\": [{\"domain\": \"yourbrand.com\"}]},\n        {\"aggregation_key\": \"them\", \"target\": [{\"domain\": \"competitor.com\"}]},\n    ],\n    platform=\"google\",\n)   # → per-group mentions / ai_search_volume / impressions, plus combined totals\n\nclient.ai_llm_mentions_top_domains(targets=[{\"keyword\": \"b2b branding agency\"}])\nclient.ai_llm_mentions_top_pages(targets=[{\"keyword\": \"b2b branding agency\"}])\nclient.ai_keywords_search_volume(keywords=[\"best branding agency dallas\", \"...\"])\nclient.ai_llm_models()                       # model list for llm_responses\nclient.ai_llm_response({...})                # payload per current DataForSEO docs\n```\n\n`search_scope: [\"sources\"]` is the citation filter — DataForSEO distinguishes\n`search_results` (everything retrieved) from `sources` (actually cited in the\nanswer). Citations are the metric that matters; always scope to sources unless\nyou're explicitly studying retrieval.\n\n## The methodology\n\n### 0. Volume pass (cheap, no subscription)\n\n`ai_keywords_search_volume` on the full commercial query set ($0.01). Rank the\nqueries by AI search volume — this decides where the expensive calls go.\n\n### 1. Baseline (run once)\n\nOne `cross_aggregated_metrics` call: your domain + every named competitor as\nseparate `aggregation_key` groups → the share-of-voice table in a single\nrequest. Save it dated — it's the \"before.\"\n\n### 2. Question-level read (deep pass, selective)\n\nFor the 5–10 commercial queries that drive the business: `search/live` with the\nkeyword as target. Read the actual AI responses. Record per query: who's cited,\nat what position, and whether the answer's framing matches how the cited brand\nwants to be described. A citation that misdescribes you is a content brief, not\na win.\n\n### 3. Gap analysis\n\nThree lists fall out of #1 + #2:\n- **Cited, high volume, not you** → run `top_pages` on those queries: the exact\n  competitor URLs earning the citations are your teardown targets.\n- **Your pages cited** → protect those pages; they're load-bearing now.\n- **Questions with thin/no citations** → open ground; first credible answer wins.\n\n### 4. Monthly cadence\n\nRe-run the baseline monthly (same targets, same platforms — comparability beats\ncleverness). Track: mentions delta per domain, new questions entering the set,\nposition shifts on the deep-pass queries. One page of output: what moved, why it\nlikely moved (ship log vs. delta), what to publish next month.\n\n## Output shape\n\nWrite results to the output dir as both `ai-visibility-YYYYMMDD.json` (raw) and a\nshort markdown report: share-of-voice table, the three gap lists, and a \"next\nmoves\" section with at most three actions. Numbers without a next move are\ntrivia; keep the actions attached to the data.\n"
}