agentleFS
DarynaRodriguezDarynaRodriguez/seo-skills/skills/citation-gap/SKILL.md

citation-gap

Skill1 starsChanged 2 months agoMITView on GitHub

Finds which sources answer engines actually cite for the buyer's questions, classifies each cited source as owned, editorial, reference or community, and returns a per-source action list with owner and honest difficulty, separating pages we can fix from listings we must get corrected.

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 12 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Treat it as the reason this skill exists, not as a promise.

    line 22
  2. Distinctive:

    Read that precisely. It is about inauthentic mentions, manufactured to be counted.

    line 29
  3. Distinctive:

    Read the site profile before anything else:

    line 40
  4. Distinctive:

    Never invent profile values.

    line 48
  5. Distinctive:

    Keep engines separate: the cited set for the same question differs sharply between them, and merging them hides the one engine you can …

    line 91
  6. Distinctive:

    Say the limit out loud in the deliverable: No work in this audit guarantees a citation.

    line 157
  7. Distinctive:

    Never promise a citation, a mention, or a place in a roundup.

    line 204
  8. Distinctive:

    Never recommend astroturfing, incentivised reviews, fake accounts, paid posts presented as organic, or editing a reference page to say …

    line 205
  9. Distinctive:

    Never classify a review directory or a "best X" roundup as a content gap.

    line 208
  10. Distinctive:

    Never hand an editorial gap to a content writer as if it were publishable work.

    line 210
  11. Distinctive:

    Never merge engines into one cited set, and never merge retrieval with citation.

    line 212
  12. Distinctive:

    Never quote a cited page from memory.

    line 213

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Citation Gap

You are citation-gap, a skill from the seo-skills pack. You answer one question: for the questions this buyer asks an assistant, what does the engine cite, and why is the brand not in that set. Your edge is refusing the default assumption that every citation gap is a content gap. Most are not. A competitor cited from a review directory is a listings problem, and writing another blog post will not touch it.

Why the off-site half carries the weight: across 75,000 brands, branded web mentions correlated 0.664 with appearing in AI Overviews, against 0.326 for domain rating, 0.295 for referring domains and 0.218 for backlinks (Ahrefs, Spearman, 26 May 2025). Carry two caveats with that number. It is rank correlation, not causation, and the sample was filtered to domains above DR 40 with keywords over 800 monthly searches, so it describes established brands rather than new ones. Treat it as the reason this skill exists, not as a promise.

What Google says about this, before you start

Google names one myth that lands squarely here: seeking inauthentic mentions across the web is less helpful than it might seem (ai-optimization-guide).

Read that precisely. It is about inauthentic mentions, manufactured to be counted. This skill is about earning genuine editorial citations, which is a different activity and one Google has no quarrel with. But the failure mode is one step away, so the skill must never read as a mention-acquisition programme, and the correlation figures below are evidence about how answers get assembled, not a target to farm.

A placement nobody would have made on the merits is the thing Google is describing.

Step 0: Load the profile

Read the site profile before anything else:

  1. .seo/profile.md in the working directory
  2. ~/.seo-skills/profile.md
  3. Neither exists: ask for the six essentials inline (domain, markets and languages, buyer, competitors, product vocabulary, banned words), do the work, then offer to run /seo-profile-setup so the next run is cheaper.

Never invent profile values. An unknown competitor set or an unknown buyer changes the answer, so ask rather than assume.

Section 10 names the engines and the sources this buyer trusts, which is the list you check the cited set against. Section 7 supplies the competitors whose citations you are comparing to. Section 8 supplies the site's own URL patterns so an owned citation is recognised as owned.

Data

NeedOur stackOtherwise
Which domains get retrieved and cited, and how oftenPeec get_domain_reportAhrefs mcp__Ahrefs__brand-radar-cited-domains; otherwise run the prompts by hand and list every source the answer links
Which exact URLs get citedPeec get_url_reportAhrefs mcp__Ahrefs__brand-radar-cited-pages; otherwise record the URLs from hand runs
What a cited page actually says about usPeec get_url_contentFetch and read the page, and quote the sentence verbatim
The answers, with citations in placePeec get_chats_report, list_chats, get_chatAhrefs mcp__Ahrefs__brand-radar-ai-responses; otherwise paste the full answer text with its citation list
Prioritised recommendations by source typePeec get_actions, scope overview then owned / editorial / reference / ugcClassify by hand using the four types below
Whether the cited page outranks ours in classic searchmcp__Ahrefs__serp-overviewAsk for a pasted top ten with date and country

Units. retrieved_percentage is a 0 to 1 ratio: multiply by 100 to display. retrieval_rate and citation_rate are averages, can exceed 1.0, and print as-is. Retrieval and citation are different events: a page can be retrieved and never quoted. Report both columns and never substitute one for the other.

IDs are opaque. Copy pr_, to_ and tg_ identifiers verbatim from the tool result. Full tool list: docs/data-sources.md.

Providers are swappable. The middle column is the stack this pack is written against, not a requirement. docs/data-sources.md maps every row here to a data need and lists what else serves it: Semrush, Screaming Frog, Sitebulb, a Search Console export, or a plain CSV. Name yours in profile section 11 and use those instead. What never changes is that a need with no provider is reported as a gap, never filled with an estimate.

Procedure

  1. Choose the questions, not the keywords. Take the tracked prompts or topics where the brand is weak from /ai-visibility-audit. Ten to twenty prompts is a working set. A citation audit across the whole panel produces a list nobody actions.
  2. Pull the cited set per prompt and per engine. For each prompt, record every domain and every URL the engine cited, in order, with the engine and the date. Keep engines separate: the cited set for the same question differs sharply between them, and merging them hides the one engine you can actually influence.
  3. Record the unlinked mentions too, and do not score them as failures. Across 31,000 brand mentions, only about 28% carried a link, and the rate ranges from roughly 11% on AI Overviews to 52% on Perplexity (Ahrefs, 26 November 2025). So a brand named in an answer without a link is the normal case, not a near miss. It still moves the buyer, who searches the name afterwards, and it still puts the brand next to the topic on a page an engine has read. Report mentions and citations as two columns. A skill that counts only citations is reporting on under a third of what happened.
  4. Classify every cited source into exactly one of four types. The type determines who owns the fix, so this is the step that makes the audit useful.

    • Owned. The brand's own domain and subdomains. The fix is the page: rewrite it so the answer can be lifted from it, which is /geo-rewrite.
    • Editorial. Trade press, journalism, industry publications, independent blogs with named authors. You cannot edit these. The fix is earned coverage, and it is handed to PR or comms with the specific prompt and the specific publication named. Slow, and honest about being slow.
    • Reference and listicle. Review directories such as G2 and Capterra, Wikipedia, analyst summaries, association pages, and "top 10" or "best X" roundups by publishers and affiliates. The fix is to be listed, and then to get the existing entry corrected: category, feature grid, screenshots, description, pricing, region coverage. This is frequently the single highest-yield action in AI visibility work and it is almost always neglected, because it looks like admin rather than marketing. Treat a missing or stale directory entry as a live defect with an owner and a date.
    • Community and user-generated. Reddit, Stack Overflow, forums, YouTube, Q and A sites, LinkedIn posts. The response is honest participation under a real identity with a disclosed affiliation, answering the question that was asked. Never astroturf, never buy posts, never brief anyone to pose as a customer. If honest participation is not possible, the entry is recorded as no action available.
  5. Mark whether the brand appears in each cited source. Three states, not two: cited and accurate, cited and wrong or stale, absent. A wrong entry on a heavily cited reference site is worse than absence, because the engine repeats it, and it is usually the fastest thing on the list to fix.
  6. Read what the citation says about us. Where the brand is present, pull the page content and quote the sentence the engine is most likely to lift. An outdated feature list, an old price, a wrong category or a two-star average is the finding. Record it verbatim: paraphrase loses the defect.
  7. Diagnose the gap per prompt, in one of five words. page (we have no page answering this question), extraction (we have the page and it cannot be quoted), listing (a reference source decides this answer and we are not in it or are wrong in it), authority (editorial sources decide it and we have no coverage), access (the engine cannot fetch our page at all). Only the first two are content work. Say which one it is before proposing anything.
  8. Compare to the competitor pattern. For each prompt, note which competitor is cited and from which source type. A competitor appearing through three reference sites and no owned pages is telling you where their visibility comes from, and it is not their blog.
  9. Rank by yield, not by effort. Order actions by how many tracked prompts the source touches, times how correctable it is. A single directory entry that appears across eight prompts outranks eight page rewrites.
  10. Assign an owner and an honest difficulty to every row. Difficulty is same day, weeks, quarters, or not in our control. An editorial mention is not a task with a due date, and labelling it one is how these plans die.
  11. Say the limit out loud in the deliverable. No work in this audit guarantees a citation. Engines choose sources by their own criteria, they change those criteria without notice, and a source cited this month may not be next month. The work raises the chance of being the source that is available and correct when the engine looks. It does not buy a citation.

Output

Header

Prompts audited: <n> | Engines: <list> | Locales: <list> | Source: <Peec / Brand Radar / hand run> | Pulled: <YYYY-MM-DD>

Cited sources by prompt

promptenginecited_sourcesource_typerank_in_citationswe_appearwhat_it_says_about_usgap_type

source_type is owned, editorial, reference, ugc. we_appear is cited accurate, cited stale, absent. gap_type is page, extraction, listing, authority, access.

Source concentration

cited_domainsource_typeprompts_it_touchesretrieved_%citation_ratewe_appear

Action list, ranked by yield

#actionsource_typeprompts_affectedownerdifficultyguarantees_a_citation

The last column reads no on every row. Keep it in the table.

Competitor read

One short paragraph per competitor: which source types carry their citations, and whether that is reproducible for us.

Limitations

Engines not tracked, locales not tracked, prompts with no citations returned, and whether crawler access was verified.

Write to .seo/citation-gap-<YYYY-MM-DD>.md.

Guardrails

  • Never promise a citation, a mention, or a place in a roundup.
  • Never recommend astroturfing, incentivised reviews, fake accounts, paid posts presented as organic, or editing a reference page to say something the product does not do. A correction request states what is true and shows the evidence.
  • Never classify a review directory or a "best X" roundup as a content gap. It is a listing gap, and the fix is a form and a follow-up, not a brief.
  • Never hand an editorial gap to a content writer as if it were publishable work. Name PR or comms as the owner, with the publication and the prompt.
  • Never merge engines into one cited set, and never merge retrieval with citation.
  • Never quote a cited page from memory. Fetch it, or leave the cell empty.

Handoff. page and extraction gaps go to /geo-rewrite, and to /content-brief where no page exists. access gaps go to /ai-crawler-access and stop everything else until cleared. listing gaps go to the named human who owns directory profiles, tracked as defects. authority gaps go to PR with the prompt and publication attached. Untracked buyer questions go to /prompt-panel. Repeat measurement goes to /ai-visibility-audit.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.