hashgraph-online /digital-marketing-pro:backlink-gap
Purpose
Identify the highest-leverage backlink prospects — domains that link to multiple competitors but not to you — and rank them by an opinionated priority score that combines authority, link-overlap signal, downstream traffic, and topical relevance. Produces a numbered output bundle ready for outreach handoff.
Context efficiency
Heavy skill. Grep before Read any referenced file, then Read only matched ranges with offset + limit. List ${CLAUDE_PLUGIN_DATA}/<brand>/ before opening files. On re-invocation mid-session, skip files already in context.
When to Use
- Quarterly backlink audit — "where did our competitors grow links this quarter and we didn't?"
- Pre-launch link-building plan for a new product or content hub
- Digital PR qualification — separating "would-link-to-anyone" prospects from "high-confidence-will-link-to-our-space"
- Competitive recovery — a competitor displaced you and you want to know which links moved
- Onboarding a new client and need a "first 50 link targets" backlog
Don't use when you just need backlink quantity numbers (use the brand's connected backlink MCP directly) or when you need anchor-text analysis of your own profile (that's a separate audit — covered in seo-audit).
Brand context (auto-applied)
- Read
~/.claude-marketing/brands/_active-brand.jsonfor the active slug, then load~/.claude-marketing/brands/{slug}/profile.json - If no brand exists: ask "Set up a brand first (/digital-marketing-pro:brand-setup)?" — or proceed with defaults
- Apply
skills/context-engine/industry-profiles.mdfor industry-specific link-quality thresholds (YMYL industries should set higher--min-dr) - Apply
skills/context-engine/compliance-rules.mdto filter out blocked publishers (e.g., PBN-style or paid-link networks the brand has explicitly banned)
Inputs
| Input | Source | Required? |
|---|---|---|
| Our backlinks CSV | Export from connected backlink MCP (Ahrefs / Semrush / SE Ranking / Moz) for the brand's primary domain | yes |
| Competitor backlinks CSVs (2+) | Same exporter, one per competitor (2 minimum for the link-overlap signal; 3-5 is the sweet spot) | yes |
| Min DR / DA filter | CLI flag, brand-profile default, or industry standard | optional |
| Top-N count | How many prospects to surface | optional |
One competitor is allowed (the script warns rather than errors) but the resulting "shared signal" is noise — single-competitor gap analysis is really just "who links to them" rather than "who consistently links in our space."
Process (10 steps, numbered-file output)
All outputs go to ${CLAUDE_PLUGIN_DATA}/{brand}/seo/backlink-gap/{YYYY-MM-DD}/.
00-input.md— capture our domain, competitor list (with rationale: why these N?), filter parameters, run timestamp01-data-pull.md— pull backlinks for{brand}.tldand each competitor via brand's connected backlink MCP. Budget guard: if the MCP exposes credit cost, sum estimated cost and ask "Continue? (y/N — default N)" before fetching when total > 200 credits.02-ours.csv— our backlink export (raw)03-comp-{competitor}.csv— one CSV per competitor (raw)04-gap-run.json— run the script:python "${CLAUDE_PLUGIN_ROOT}/scripts/backlink_gap.py" \ --ours "${CLAUDE_PLUGIN_DATA}/{brand}/seo/backlink-gap/{date}/02-ours.csv" \ --competitors \ "${CLAUDE_PLUGIN_DATA}/{brand}/seo/backlink-gap/{date}/03-comp-competitor1.csv" \ "${CLAUDE_PLUGIN_DATA}/{brand}/seo/backlink-gap/{date}/03-comp-competitor2.csv" \ --min-dr {brand.profile.min_link_dr or 20} \ --top 100 \ --out "${CLAUDE_PLUGIN_DATA}/{brand}/seo/backlink-gap/{date}/04-gap-run.json"--competitorstakes an explicit space-separated list of CSV paths (nargs="+") — enumerate each03-comp-*.csvfile; the script does not expand a*glob, so a quoted03-comp-*.csvwould fail with FileNotFoundError. List one path per competitor.05-quality-scorecard.md— readquality_scorecardfrom04-gap-run.json. Ifstatus: needs_review, diagnose:data_freshness: fail→ input CSV(s) older than 90 days. Re-pull data; backlink graphs decay fast.sample_size: fail→ any input < 50 unique referring domains. Either the domain is too new or the export was truncated. Re-export with no row limit.competitor_coverage: warn→ only 1 competitor. Add at least 1 more for genuine overlap signal.link_overlap_signal: fail→ fewer than 5 referring domains link to ≥2 competitors. Either competitors are poorly chosen (they don't share a content space with each other) or the data is incomplete. Re-choose competitors.
06-prospect-shortlist.md— top 30 prospects, formatted for outreach handoff: domain, DR, link count across competitors, suggested outreach angle (guest post, broken-link, resource-page mention)07-broken-link-candidates.md— subset where one or more competitor links return 4xx (run a quick HTTP HEAD pass on competitor backlink URLs — use the brand's connected web-fetch MCP). These are "easy wins" — pitch your URL as the replacement.08-outreach-templates.md— three template variants: (a) cold-pitch resource-page, (b) broken-link replacement, (c) competitor mention. Each pre-filled with brand voice from the brand profile's voice fields +skills/context-engine/guidelines-framework.md.PLAN.md— single-page summary: stats + scorecard + top 10 prospects with outreach angle + recommended cadence (3-5 pitches/week for sustainable outreach quality).
Output format
${CLAUDE_PLUGIN_DATA}/{brand}/seo/backlink-gap/2026-06-04/
├── 00-input.md
├── 01-data-pull.md
├── 02-ours.csv
├── 03-comp-{competitor1}.csv
├── 03-comp-{competitor2}.csv
├── ...
├── 04-gap-run.json
├── 05-quality-scorecard.md
├── 06-prospect-shortlist.md
├── 07-broken-link-candidates.md
├── 08-outreach-templates.md
└── PLAN.md
Quality scorecard (the four gates)
| Gate | What it checks | Why it matters |
|---|---|---|
| data_freshness | All input CSVs have mtime within 90 days | Backlink graphs decay fast — stale data sends you chasing dead links |
| sample_size | Each input has ≥ 50 unique referring domains | Below this, the gap math has too little signal to rank |
| competitor_coverage | ≥ 2 competitor CSVs supplied | The "shared signal" is what separates real prospects from noise |
| link_overlap_signal | ≥ 5 referring domains link to ≥ 2 of the competitors | If no domains shared, your competitors aren't actually competing in the same content space |
status: ready requires all four gates pass (competitor_coverage: warn does not block — it's a soft signal).
Priority score (0–1, displayed in 04-gap-run.json)
priority = 0.40 × DR_normalised
+ 0.25 × link_count_normalised (how many competitors this domain links to)
+ 0.20 × traffic_normalised
+ 0.15 × topical_relevance
Why link_count is weighted higher than traffic: a domain that links to 3/3 competitors is unambiguously in your space and willing to link. A high-traffic domain that only links to 1 might just be a tier-1 publisher who happens to have covered one of you in passing.
Chain handoffs
This skill is a producer in a longer chain:
/digital-marketing-pro:competitor-analysis— picks the right competitors/digital-marketing-pro:backlink-gap— this skill/digital-marketing-pro:digital-pr— consumes06-prospect-shortlist.md+08-outreach-templates.md/digital-marketing-pro:pr-pitch— drafts individual pitches per prospect/digital-marketing-pro:performance-report— quarterly re-runs of this skill feed the "links gained" KPI
Tips & caveats
- More competitors ≠ better. Three to five focused competitors beats ten random ones. The "shared signal" gate works best when all competitors are in the same content space.
- DR/DA from different exporters aren't comparable. Don't mix an Ahrefs export with a Moz export — the script doesn't know to normalise across exporters. Pick one provider per audit.
- Topical relevance is the weakest signal in most exports because few exporters provide it well. The script defaults to 0.5 if absent, which is the right neutral. Override only if you have a curated topical-relevance score.
- Don't outreach 100 prospects in one week. The output is a backlog, not a queue. Sustainable cadence: 3-5 highly personalised pitches per week per outreach lead.
- Broken-link candidates tend to have the highest hit rate (broken-link replacement pitches typically out-reply cold pitches by a wide margin — the "30-60% vs 5-15%" figures are an illustrative rule of thumb, not measured; validate against your own outreach data) — always work the
07-broken-link-candidates.mdlist first. - Re-run quarterly, not monthly. Backlink data moves slowly enough that monthly runs mostly produce noise.
- YMYL industries (health, finance, legal) should set
--min-dr 40to filter out low-authority publishers that could damage E-E-A-T.
Agents used
seo-specialist(primary) — interpretation of prospect qualitycompetitive-intel— competitor-set selection rationale (Step 1)pr-outreach— outreach template drafting (Step 8)brand-guardian— banned-publisher filter at Step 6
See also
/digital-marketing-pro:competitor-analysis— pick the competitors for this audit/digital-marketing-pro:digital-pr— runs the actual outreach/digital-marketing-pro:seo-drift— re-run quarterly to track delta/digital-marketing-pro:seo-audit— broader site-level audit including own-profile healthscripts/backlink_gap.py— the underlying gap engine
Source: hashgraph-online/awesome-codex-plugins → plugins/indranilbanerjee/digital-marketing-pro/skills/backlink-gap/SKILL.md