Broken Backlinks

/broken-backlinks — Broken-backlink replacement opportunity finder

Captures the highest-conversion backlink-acquisition opportunity on the web: publishers with a known-broken outbound link who need a replacement. Conversion rates on broken-link outreach run 8–15% (vs. 0.5–2% for cold-pitch outreach) because you're solving the publisher's problem, not asking for a favor.

This skill does NOT auto-send outreach. It queues opportunities for user review + approval. Pitches are drafted by /outreach (see templates/outreach/ once built).

Inputs

Required (asked at start if not given):

• Site — must match a folder under sites/[name]/.

Optional (per-run overrides):

• Keyword tool — overrides the site's default. Source for broken-backlink reports. SEMrush is the default (preferred for sites with active SEMrush subscriptions); Ahrefs and Moz are supported via API plug-ins.
• --min-da=N — minimum DA of source page to include (default 30; below 30 = low-leverage links).
• --max-opportunities=N — cap opportunities per run (default 25; below cap, may surface < 25 if competitors haven't lost many links this month).
• --competitor=domain.com — restrict to one competitor's backlink graph this run.

Workflow

Step 0 — Cron-mode detection (if invoked with --cron)

Cron mode is the DEFAULT for this skill — monthly cadence is the right frequency (broken-backlink opportunities don't materialize overnight). Required behavior per the standard contract (see .claude/skills/blog/SKILL.md Step 0). Idempotency key: (site, year-month).

Step 1 — Read context (Rule 1)

Load in order:

1. CLAUDE.md
2. sites/{site}/site-info.md — especially "Competitors" block (the top 5 ranking competitors)
3. sites/{site}/backlinks.md — for "Banned outreach targets" + outreach history
4. sites/{site}/used-keywords.md — for the published content inventory (to identify replacement candidates)
5. Site's sitemap (live URL) — fallback content inventory if used-keywords.md is incomplete
6. sites/{site}/notes.md

Step 2 — Identify top-5 competitors

Read site-info.md → "Competitors" block. If fewer than 5 listed, escalate (cron-mode) or ask user (interactive): "Site has only N documented competitors — /broken-backlinks is most effective with ≥ 5. Continue with N, or pause until more competitors are documented?"

Step 3 — Pull broken-backlinks report per competitor

For each competitor, query the configured keyword tool's broken-backlinks endpoint:

SEMrush (default):

• Endpoint: backlinks_broken (Backlink Analytics → Indexed pages → Broken backlinks filter)
• Filter: da_min={--min-da}, link_type=dofollow, last_seen ≥ 90 days ago
• Output: list of (source_url, source_domain, da, broken_target, anchor_text, first_seen, last_seen) rows

Ahrefs / Moz (fallbacks):

• Same logical query against each tool's broken-backlinks API.

Cache results to sites/{site}/_research/broken-backlinks-{competitor}-{year-month}.json for traceability + idempotency.

Step 4 — Cross-reference broken targets against site content

For each broken-target URL pulled in Step 3:

1. Extract the broken page's URL path + last-known title (from SEMrush snippet or web.archive.org fallback).
2. Match against site's published content via:
   • Slug similarity — Levenshtein distance < 0.3 to any URL in site's sitemap
   • Topic similarity — semantic embedding match (≥ 0.75 cosine) of broken-page title against site page titles
   • Keyword overlap — broken page's last-known target keyword in used-keywords.md for the site
3. Top match per broken-target = the proposed replacement URL.

If no match scores above the threshold → drop the opportunity (you can't replace a link you don't have content for). Flag as "content gap" in the summary; the user can decide to write a replacement page (which would then unlock the opportunity in a future run).

Step 5 — Score each opportunity

For each surviving (broken-target → replacement) pair, score 0–100:

Step 6 — Apply banned + previously-failed filters

Remove opportunities where:

• Source domain in backlinks.md → "Banned outreach targets"
• Source domain has Last outcome: declined in backlinks.md "Outreach response tracking" AND Next eligible date is in the future
• Source domain has open outreach in the pipeline (status: sent / replied / scheduled)

Step 7 — Output

Write to sites/{site}/_inbox/broken-backlinks-opportunities-{year-month}.md:

# Broken-backlink opportunities — {site} — {year-month}

Pulled broken-backlinks from {N} competitors. Found {M} matched opportunities ({K} above the {threshold} score floor). Top {min(max-opportunities, K)} listed below.

## Top opportunities (review + approve)

### 1. example.com/best-ai-tools — DA 87 — Score 92

- **Source URL:** https://example.com/best-ai-tools-for-smbs
- **Source DA:** 87
- **Source organic traffic:** ~3,400/mo (SEMrush)
- **Broken target:** https://defunct-competitor.com/ai-tools (last seen 2026-02-14)
- **Broken anchor text:** "comprehensive AI tools guide"
- **Proposed replacement (your URL):** https://{site}/services/ai-consulting
- **Match strength:** 0.91 cosine (strong topical + keyword overlap)
- **Why it's strong:** source has 3.4K monthly organic traffic, the broken link is in a numbered listicle (publishers typically maintain those), and 3 of your top-5 competitors also link from this domain (proven willingness)

**Suggested next step:** `/outreach --type=broken-link --opportunity-id=BB-2026-05-001`

---

### 2. ...

## Opportunities below score floor (logged for transparency)

(no draft generated; surface in case you want to override)

- example2.com/... — score 68 — replacement match is weak (cosine 0.76)
- ...

## Content gaps (broken-targets you have no replacement for)

These are broken links where you'd need to write a new page first. Each is a potential `/blog` or `/service` target if the topic + volume justifies it.

| Broken topic | Source DA | Source traffic | Suggested skill |
|--------------|-----------|----------------|-----------------|
| "best CRM integrations for SaaS" | 78 | 2,100/mo | `/integrations` (if you build it) |
| ... |

Step 8 — Update backlinks.md

Append every surfaced opportunity (above + below score floor) to backlinks.md → "Broken-link reclamation queue" with status: not-pitched. The user's approval flips it to pitched (via /outreach skill).

Step 9 — Audit log

appendRun({ exit: 'shipped', metadata: { competitors_queried: N, broken_links_found: TotalRaw, opportunities_surfaced: M, content_gaps_flagged: ContentGaps } }).

Refusal conditions

This skill refuses to run if:

• Site has fewer than 3 documented competitors.
• The configured keyword tool's broken-backlinks endpoint is unauthenticated.
• Site has no backlinks.md (initialize via cp templates/backlinks.md sites/{site}/backlinks.md first).

Routine versioning + idempotency contract

Idempotency key: (site, year-month). Runs once per month per site. Re-runs in the same month skip with idempotent-skip.

Routine version: 1.0.0 (2026-05-17).