/ai-citations-tracker

name: ai-citations-tracker
description: 'Use when you need to **measure** (not just describe) brand citation frequency across AI search surfaces over time. Runs a configurable brand-mention prompt set weekly against ChatGPT (OpenAI API), Perplexity (Sonar API), and optionally Google AI Mode / AI Overviews / Bing Copilot / Claude.ai (manual workflow). Stores NDJSON history for trend analysis. Triggers from "track AI citations", "AI Overview citation tracker", "ChatGPT brand mention monitoring", "Perplexity citation tracking", "AI-Sichtbarkeit messen", "wie oft erwähnt ChatGPT meine Marke". Complements [[ai-search-rescue]]: that skill is the framework, this skill is the measurement loop.'
user-invocable: true
argument-hint: '[setup | run | analyze]'
allowed-tools: [Read, Write, Bash(node:*), Bash(curl:*), Bash(launchctl:*), Bash(crontab:*)]
license: MIT
metadata:
  author: Max Schottke
  version: '0.5.4'
  category: marketing

AI Citations Tracker

Overview

Most "AI search visibility" advice is descriptive ("you should rank in AI Overviews"). This skill is the measurement loop: a weekly cron job that asks the same brand-mention prompts to AI surfaces, parses the answers for your brand vs competitors, and logs results to NDJSON for trend analysis.

This is the **possible-early-signal** companion to [[post-core-update-recovery]]:

• Classical Sistrix VI / GSC clicks lag Google by 3-5 days
• Hypothesis (N=1, currently unproven): AI citation counts MAY start moving **2-6 weeks before** classical SERP recovery shows up. In the pilot case this pattern suffered a setback — the AI-citation rise could not be separated from a pre-update plateau (the update hit first cited as having erased it was itself withdrawn after a full post-window re-measurement; the hypothesis stays unproven either way) (see `post-core-update-recovery/LESSONS.md`, 2026-06-03 correction). Log the signal; do not report recovery based on it alone.
• If your AI citations are climbing while VI is flat, that is worth logging — not confirmation that recovery is on track. If both are flat, the authority signals from [[ai-search-rescue]] Tactic 4 (Author + Person-Schema) need more time or aren't reaching the model retrieval layer.

When to use

• A site running active Core-Update recovery — track AI citations as the leading recovery indicator
• A brand wanting to know whether ChatGPT / Perplexity / AI Overviews actually mention them (most brands don't measure this — they guess)
• An agency reporting to clients on "AI search visibility" — needs hard numbers, not vibes
• A YMYL / B2B vendor whose buyers research via ChatGPT before contact sales — citation frequency is a direct lead-gen signal

**Don't use for:**

• One-off citation snapshots (use the manual workflow in [[ai-search-rescue]] instead — no cron needed)
• Pure SERP ranking tracking (use [[seo-outreach-report]] + [[competitor-deep-audit]])
• Optimizing the content itself (that's [[ai-search-rescue]] — this skill measures, that skill optimizes)

Architecture

ai-citations-config.json   (your prompts + competitors + API keys via env)
  ↓
ai-citations-fetch.example.js   (run weekly via cron)
  ↓
ai-citations-history.ndjson    (append-only, per-week records)
  ↓
your trend chart / Sistrix-style overlay

The script is **opt-in per AI surface**: skip surfaces where you don't have API access. Default: ChatGPT (OpenAI API) + Perplexity (Sonar API). Manual workflow appended for Google AI Mode / AI Overviews / Bing Copilot / Claude.ai (no stable public APIs for those as of 2026-05).

Config template

`ai-citations-config.json` (gitignored — see `SECURITY.md` at the repo root, in the repository, not shipped in the plugin package):

{
  "brand": "Your Brand",
  "brand_variants": ["Your Brand", "your-brand.com", "yourbrand"],
  "competitors": ["competitor-a.com", "competitor-b.de", "competitor-c.io"],
  "prompts": [
    "Was ist die beste Matratze für Rückenschläfer in Deutschland?",
    "Wo kaufe ich orthopädische Matratzen?",
    "Vergleich von Matratzenmarken in Deutschland",
    "Welche Matratzenmarke produziert in Deutschland?"
  ],
  "surfaces": ["chatgpt", "perplexity"],
  "output_dir": "./ai-citations-history"
}

| Field | Required | Notes | |-------|----------|-------| | `brand` | yes | Canonical brand name as it appears in the wild | | `brand_variants` | yes | Other strings the model might use (domain, abbreviations, common typos) — used for fuzzy match | | `competitors` | yes | 3-15 domains for competitive context | | `prompts` | yes | 10-30 prompts covering category, problem-aware, comparison, brand-aware queries | | `surfaces` | yes | Subset of `["chatgpt", "perplexity"]` for now. Google AI Mode / AI Overviews / Bing Copilot are manual (see below) | | `output_dir` | no | Default `./ai-citations-history` — must be relative, no `..` |

API keys (env-only, never in config — same pattern as [[psi-weekly-cron-baseline]]):

export OPENAI_API_KEY=sk-...
export PERPLEXITY_API_KEY=pplx-...

Quick start

1. Copy `ai-citations-config.example.json` to `ai-citations-config.json` and customize. Put the file in a private location outside the plugin repo. 2. Get API keys:

• **OpenAI:** [platform.openai.com](https://platform.openai.com/) → API keys → create. Typical cost: ~$0.0001 per prompt with `gpt-4o-mini`, so 20 prompts × 50 weeks ≈ $0.10/year.
• **Perplexity:** [docs.perplexity.ai](https://docs.perplexity.ai/) → API keys → create. Free tier allows ~50 queries/day with the `sonar` model. Pro tier (~$5/mo) gives higher rate limits.

3. Run once manually: `node ai-citations-fetch.example.js` 4. Inspect the resulting `./ai-citations-history/history.ndjson` — one record per `(prompt, surface)` pair. 5. Schedule weekly via launchd / cron / GHA — see [[psi-weekly-cron-baseline]] for the cron-setup pattern.

What gets logged

Per `(prompt, surface)` pair, the NDJSON record contains:

| Field | Type | Description | |-------|------|-