From easy-skills
Use when a user asks to audit, improve, or grow their likelihood of being cited by AI search engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews). Triggers on phrases like "audit our AI citation", "get cited by ChatGPT", "GEO audit", "generative engine optimization", "AI visibility", "raise our AI citation score", "citability check on <url>", "AI citation walkthrough", "monthly AI citation check". Use also when a user asks to score a single page for AI citability, run a brand-wide AI search visibility audit, walk through growth-hack moves to improve citation likelihood, or compare audits over time.
How this skill is triggered — by the user, by Claude, or both
Slash command
/easy-skills:ai-citationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A self-contained skill that audits a brand's likelihood of being cited by AI search engines, walks the team through prioritized growth-hack moves to fix gaps, and tracks improvements over monthly delta runs.
A self-contained skill that audits a brand's likelihood of being cited by AI search engines, walks the team through prioritized growth-hack moves to fix gaps, and tracks improvements over monthly delta runs.
The skill is grounded in research:
It produces a hybrid two-score model:
Composite AI Citation Score = 0.5 × Readiness Score + 0.5 × Action Score
Plus a Brand Surface Area Map (off-site presence on the platforms AI engines pull from) and per-engine projection gauges (ChatGPT / Perplexity / Gemini / AIO / Claude).
Use this skill when the user says:
Do NOT use when:
| Mode | Trigger | What it does |
|---|---|---|
| audit (default) | "audit our AI citation", "AI citation audit" | Brand-wide audit → HTML report + JSON snapshot + walkthrough offer + delta enrollment |
| single-page | "score this page", "citability check on " | Degenerate audit — skips site crawl and off-site probe; focused passage report |
| walkthrough | "AI citation walkthrough", "walk me through GEO fixes" | Interactive playbook — top 5-7 moves with branching done / show-me-how / skip |
| delta | "AI citation delta", "compare our AI citation" | Load most recent snapshot → re-audit → compute deltas → render delta report |
The default flow is opinionated: audit → report → offer walkthrough → offer delta enrollment. Each step is below.
Parse the trigger phrase and any URL/argument provided. Set mode = audit | single-page | walkthrough | delta. If mode is audit and no URL was provided, ask for the root URL (Q1 below).
Scan the conversation first; do not re-ask anything the user already provided. Then ask up to 4 focused questions, one at a time.
Q1 — Root URL. Required for audit mode. Skip if already in context.
Q2 — Brand identity + disambiguation.
First, try to extract the brand name from the homepage's <title>, og:site_name, or Organization JSON-LD.
I've identified the brand as "". That's a common word — to keep off-site searches clean, give me a few additional phrasings:
- Full company name (e.g., "Easy Labs Inc.")
- Category phrasing (e.g., "Easy payment processor", "Easy PSP")
- Alternative names / handles (e.g., "@useeasy", "easy.com") — optional
Also: what is the one-sentence category description? (e.g., "payment service provider for SaaS companies")
Q3 — Live AI citation probing opt-in (sticky per site).
If preferences.json for this site does not have a recorded answer for ai_probing, ask:
Want me to also probe live AI engines (ChatGPT/Perplexity/Gemini) to measure your actual citation rate?
A. Yes — I have API keys, or I'll paste the answers manually B. Skip for this run C. No, don't ask again
Q4 — Google Search Console integration (sticky per site).
If preferences.json does not have a recorded answer for gsc_integration, ask:
A more thorough report can use Google Search Console data to find queries you're already getting impressions for but not optimized for. Requires GSC API credentials.
A. Yes — I'll provide credentials now (or read from
~/.config/ai-citation/gsc-credentials.json) B. Skip for this run C. No, don't ask again
Preference semantics — these are not negotiable:
preferences.json; never ask again for this sitePersist preferences at <storage>/preferences.json with this structure:
{
"site_slug": "example-com",
"brand": {
"primary": "Easy",
"full_name": "Easy Labs Inc.",
"category_phrasings": ["Easy payment processor", "Easy PSP"],
"handles": ["@useeasy", "easy.com"],
"category_description": "payment service provider for SaaS companies"
},
"preferences": {
"ai_probing": { "answered": "C", "answered_at": "2026-05-13", "scope": "site" },
"gsc_integration": { "answered": "C", "answered_at": "2026-05-13", "scope": "site" },
"target_engine": "perplexity",
"cadence_days": 30
}
}
Per-site by default. Global override at ~/.ai-citation/preferences.json if user copies the file.
/sitemap.xml. If present, sample up to 25 pages weighted toward: homepage + product/feature pages + blog/glossary/docs (configurable via the --max-pages flag — see "Slash-command flags" below).robots.txt (once, cached) and llms.txt (if present — noted but low-weight).For each sampled page, fetch and extract:
rubric/block-rubric.md)Apply the Readiness Score rubric in rubric/readiness-factors.md (12 factors, weights sum to 100) and the page-level inputs to the Action Score rubric in rubric/action-factors.md (8 factors, weights sum to 100).
Build a query set from Q2 disambiguation data:
queries = [
'"<full company name>"',
'"<brand>" <category phrasing>',
'"<alternate phrasing>"',
'"<domain>"',
'@<handle>',
]
Run each over six off-site platforms via WebSearch:
site:reddit.com <query> — critical for Perplexity (46.7% citation share)site:youtube.com <query> — top social citation source in early 2026"best <category>" "<brand>"For non-SaaS brands, skip G2/Capterra. For local-services brands, skip Wikipedia.
Match-quality weighting:
False-positive guard (mandatory for ambiguous brand names): for every result, check whether category-description tokens appear in result title/snippet. Drop if not. Print this transparency note in the final report:
"Off-site probe used N query variants and dropped K results that didn't match the category context."
Score each platform 0/5/10 per the rubric in rubric/brand-surface-area.md. Produce the Brand Surface Area Map.
Only if preferences.ai_probing.answered == "A" for this run.
Before running: print an estimated cost based on the number of seed prompts × the number of available engines × estimated tokens per response. Get explicit user confirmation before incurring API costs:
"Live probing will run {{prompt_count}} seed prompts against {{engine_count}} engines. Estimated cost: ~${{cost_estimate}}. Continue? (y/n)"
If the user declines, fall back to printing the seed prompts for manual probing.
~/.config/ai-citation/openai-key), xAI key, Anthropic key, Perplexity key. Use whichever MCPs are installed.scores.per_platform_measured.<engine> in the snapshot.No engine APIs detected. I can give you the seed prompts to paste into ChatGPT/Perplexity/etc. manually, then you drop the answers back to me and I'll score them. Want to do that?
Apply the rubrics. Both rubric files have explicit aggregation formulas.
Composite = 0.5 × Readiness + 0.5 × Action
Compute the Per-Platform Snapshot projections per rubric/platform-preferences.md. If a measured rate exists for an engine, use it instead of the projection (flag with ✓).
Cluster findings into a flat list. Score each by (impact × ease) where impact is the rubric-derived score lift and ease is the inverse of effort (low/medium/high).
Sort descending. Tag each: on-page | off-site | technical | content. Split into time buckets:
The top 5-7 items become the candidate set for the walkthrough.
Use templates/audit-report.html.template as the HTML scaffold.
Write three artifacts to <storage>/:
<date>-report.html — the human-readable deliverable<date>-baseline.json — durable structured snapshot (see Step 8 schema)Storage location resolution:
<repo>/.ai-citation/snapshots/<site-slug>/ so the snapshots get checked in~/.ai-citation/snapshots/<site-slug>/Site slug: primary registered domain, dots → dashes (example.com → example-com).
Snapshot JSON schema:
{
"schema_version": "1.0",
"methodology_version": "1.0",
"run": {
"id": "2026-05-13T14:22:03Z",
"type": "baseline",
"previous_snapshot": null
},
"site": {
"slug": "example-com",
"root_url": "https://example.com",
"brand": { /* from preferences.json */ },
"pages_audited": 25,
"pages_list": ["/", "/pricing", ...]
},
"scores": {
"composite": 63,
"readiness": 58,
"action": 68,
"per_platform": {
"chatgpt": 71, "perplexity": 49, "gemini": 64, "ai_overviews": 60, "claude": 67
},
"per_platform_measured": {
"perplexity": { "rate": 0.20, "measured_at": "2026-05-13", "prompts_tested": 10 }
}
},
"factor_scores": {
"readiness": { "url_accessibility": 9, "search_rank_proxy": 6, ... },
"action": { "passage_citability": 72, "brand_surface_area": 45, ... }
},
"brand_surface_area": {
"wikipedia": 0, "reddit": 5, "youtube": 3, "g2": 7, "quora": 0, "listicles": 4
},
"per_page": [...],
"recommendations": [
{ "id": "rec_001", "move": "rewrite-top-3-pages-definition-first",
"impact": 4, "effort": "low", "status": "open" }
]
}
After the report renders, prompt:
"You scored {{composite}}/100. The top 5-7 moves would lift you to an estimated {{projection}}/100 in 30 days. Want me to walk you through them now?
A. Yes — start the walkthrough B. Save for later — I'll write the plan to a file C. No"
walkthrough-plan.md using templates/walkthrough-plan.md.template with statuses pending for each moveDetect available reminder channels in order:
mcp__claude_ai_Google_Calendar)mcp__claude_ai_Linear)schedule skill installed?.ics file + NEXT-REVIEW.mdShow only the available options:
"You scored {{composite}}/100. Recommended cadence: monthly. Pick a reminder channel:
A. Google Calendar — recurring event with the slash command in the description B. Linear — recurring issue assigned to you C. .ics file — calendar invite dropped in the snapshot folder D. Cron via the
scheduleskill — autonomous re-runs (most hands-off) E. None — just write NEXT-REVIEW.md and trust me to remember"
On choice, set up the reminder with this body:
"Run
/ai-citation delta <site>to compare against your baseline. Baseline composite: /100. Snapshot: ."
Always write NEXT-REVIEW.md using templates/next-review.md.template regardless of channel chosen — it is the always-emit fallback.
Markdown summary in chat: composite score, paths to all artifacts (report HTML, snapshot JSON, walkthrough plan if generated, NEXT-REVIEW.md), reminder channel used (or "none chosen"), exact slash command to run the next check.
Entered from Step 9 of the audit funnel or directly via trigger ("walk me through GEO fixes"). If invoked standalone with no recent snapshot, prompt to run audit first or load a baseline JSON.
For each of the top 5-7 moves (selected from the catalog in move-catalog/moves.md by audit findings):
Introduce the move with its name, what, why (with research citation), estimated impact (e.g., +4 composite points), effort (low/medium/high).
Prompt for branch:
"A. Already have this — mark done, log evidence, move on B. Show me how — go deep on this one C. Skip — note reason, move on"
If A (done): ask for optional evidence URL/screenshot; record as status: done with evidence field; move on.
If B (show me how): load the playbook block for that move from move-catalog/moves.md and walk through:
If C (skip): ask "skip permanently for this site, or just for this run?" Persist to preferences.json if permanent.
At the end:
walkthrough-plan.md via templates/walkthrough-plan.md.template with statuses per moveThe top 5-7 moves are selected from move-catalog/moves.md by:
brand_surface_area.g2 == 10, skip move 4)preferences.json)preferences.target_engine is set (e.g., Perplexity target → bump Reddit-related moves up)Triggered by: "AI citation delta", "compare our AI citation", "monthly AI citation check", /ai-citation delta <site>.
Load the most recent snapshot for the site slug from <storage>/. If none, refuse:
"No baseline found for this site. Run
/ai-citation audit <url>first to establish a baseline."
Run Steps 2-7 of the audit fresh. Use the same preferences.json (brand identity, GSC opt-in, AI probing opt-in stay sticky).
Compute deltas:
move-catalog/moves.md to each open recommendationWrite <date>-delta.json with the same schema plus a delta block. Set run.type = "delta" and run.previous_snapshot = <baseline filename>.
CRITICAL: if methodology_version differs between baseline and current, the report MUST refuse direct numeric comparison and instead surface a "methodology has changed — re-baseline recommended" banner. Comparisons are informational only.
Render <date>-delta-report.html using templates/delta-report.html.template.
If Action Score did NOT improve since baseline, re-offer the walkthrough:
"Your Action Score is flat ({{action_baseline}} → {{action_current}}). The walkthrough should help find what got stuck. Want to run it now?"
For each open recommendation, apply the detector defined for that move in move-catalog/moves.md. Status options:
closed — detector confirms the move is done (e.g., FAQ schema now present on all 10 named pages)partial — partial progress detected (e.g., 6 of 10 pages now have schema)open — no progress detectedregressed — the move was previously detected as done but is now undoneDefault fallback: for any move without an explicit auto-close detector, status defaults to open and is surfaced in the delta report under "Awaiting manual verification" with a prompt to mark done / partial / skipped during the next walkthrough. The skill MUST NOT mark such moves closed based on inference.
The walkthrough's playbooks include educational-only patterns for legitimate growth. The skill explicitly refuses these:
Astroturfing Reddit / Quora / forums — sock-puppet accounts, undisclosed-affiliation posts, paid commenters. If asked, respond:
"I won't generate inauthentic Reddit/Quora content. The legitimate playbook is in Move 3 of the catalog — disclosure-first, real account history, educational answers."
Fake reviews for G2 / Capterra / TrustRadius / Trustpilot / etc. If asked, refuse and point to the customer-solicitation template in Move 4.
Wikipedia article seeded by the brand itself with marketing language — gets flagged or deleted. Move 6 has the legitimate playbook (AfC submission, neutral tone, third-party-cited claims).
Blank-page-with-schema-only growth hacks (e.g., the well-known Hobo_Web 36-hour Perplexity citation experiment). Mention in passing as a documented short-term tactic, but flag explicitly: works short-term, ages poorly, AI engines are increasingly filtering thin-content pages. Teach the sanitized version: rich schema on real content.
Aggressive WAF rules that block AI bots while pretending they don't — recommend explicit allow-listing per Move 7.
LLMs.txt over-investment — Cyrus Shepard's analysis scored llms.txt 2.0/10. The skill MUST surface this in every audit's "Don't waste time on" callout.
The walkthrough's "Common pitfalls" section for each move must include the bad version alongside the good version, so the team learns the boundary.
| Step | What | Skip = |
|---|---|---|
| 0 | Detect mode (audit / single-page / walkthrough / delta) | Wrong procedure dispatched |
| 1 | Gather minimum context (URL, brand identity, sticky prefs) | Generic results, polluted off-site probe on ambiguous brands |
| 2 | Discover up to 25 priority pages via sitemap or BFS | Missed primary content surfaces |
| 3 | On-page audit per page (passage rubric + Readiness factors) | Cannot compute scores |
| 4 | Off-site probe across 6 platforms with disambiguation | BSAM is unscored; can't recommend off-site moves |
| 5 | Optional live AI citation probing if opted in | Projections only, no measured ground-truth |
| 6 | Compute composite + per-platform projections | No deliverable |
| 7 | Prioritize recommendations by impact × ease, bucket 30/60/90 | Unprioritized advice dump |
| 8 | Render HTML report + JSON snapshot | No artifact for handoff or future delta |
| 9 | Offer walkthrough on top 5-7 moves | Audit becomes "advice" — no execution loop |
| 10 | Offer delta enrollment with channel detection | No accountability — audit drift |
| 11 | Final printout with paths and slash commands | User loses track of artifacts |
| Thought | Reality |
|---|---|
| "The brand name is fine, no need to disambiguate" | Check token count and commonness. "Easy" with no disambiguation = polluted probe. |
| "I'll just give them generic GEO advice in chat" | That's not this skill. Produce the HTML report. |
| "Two out of three preferences answered is enough" | All three Q3/Q4 answers matter. Sticky semantics depend on them. |
| "I can infer the user wants Perplexity since they mentioned it once" | Ask explicitly which engine matters most — bias the walkthrough on it. |
| "I'll set up the calendar event without offering options" | Offer the menu (A/B/C/D/E). Some users prefer .ics, some Linear. |
| "Schema sprays everywhere will boost their score" | False. Validity matters more than presence. Targeted, valid schemas only. |
The skill accepts optional flags passed as key=value arguments after the trigger phrase:
| Flag | Default | Effect |
|---|---|---|
--max-pages | 25 | Cap on pages crawled in Step 2 |
--rebrand | (off) | Force re-prompt of brand disambiguation in Q2, ignoring preferences.json |
--priority-urls | (none) | Comma-separated list of URLs to treat as priority pages (weighted 2× in rollup) |
--category | (auto-detect) | Override SaaS/ecom/media/local-services category detection |
--cadence | 30 (days) | Override the default monthly review cadence |
--enroll-cron | (off) | Enroll site in autonomous cron-driven delta runs (requires schedule skill) |
--target-engine | (auto/asked) | Bias walkthrough prioritization toward one engine (chatgpt / perplexity / gemini / aio / claude) |
Example: /ai-citation audit https://example.com --max-pages=50 --target-engine=perplexity
rubric/readiness-factors.md — 12 Readiness factors with weights and per-factor scoring criteriarubric/action-factors.md — 8 Action factors with weights and scoring criteriarubric/block-rubric.md — 6-criterion block-level passage rubricrubric/brand-surface-area.md — 6-platform off-site presence rubricrubric/platform-preferences.md — Per-engine projection formulasmove-catalog/moves.md — 12-move catalog with playbook blocks and auto-close detectorstemplates/audit-report.html.template — Audit report HTML scaffoldtemplates/delta-report.html.template — Delta report HTML scaffoldtemplates/walkthrough-plan.md.template — Walkthrough output markdowntemplates/next-review.md.template — Always-emit reminder markdownProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub itseasyco/easy-skills --plugin easy-skills