agentleFS
mkreindelmkreindel/seo-toolkit-template/.claude/skills/broken-backlinks/SKILL.md

broken-backlinks

Skill1 starsChanged 6 months agoApache-2.0View on GitHub

Monthly cron — finds pages on the open web that link to defunct competitor URLs where the site has a live replacement page, queues outreach to pitch the site's URL as the broken-link replacement. Pulls broken-backlink data from SEMrush (or Ahrefs/Moz as fallback) for each top-5 competitor, cross-references with the site's published content, surfaces high-probability "replacement-ready" opportunities. Highest-conversion outreach type — link reclamation pitches convert ~10× higher than cold-pitches because the publisher already has a broken link to fix. Use when the user types `/broken-backlinks` or when the monthly cron fires.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read site-info.md → "Competitors" block.

    line 41

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

/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:

SignalWeight
Source DA (DA 80+ = 30, DA 50–79 = 20, DA 30–49 = 10)30
Match strength of replacement (cosine ≥ 0.9 = 20, 0.8–0.89 = 15, 0.75–0.79 = 10)20
Source page topical relevance (does the source's topic actually fit the replacement?)15
Source page traffic estimate (SEMrush organic traffic; > 1000/mo = 15, 100–999 = 10, < 100 = 5)15
Number of competitors using the same source domain as a link source (cross-domain authority signal)10
Outreach history check (source domain in backlinks.md "Outreach response tracking" with non-failed status)10

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).

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.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

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.