⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

linkbuilding

jamesoliverseo@jamesoliverseo⭐ 10 stars· last commit 19d ago· 0 open issues

Use when building backlinks to a site with an outreach tactic - broken link building, link gap (sites linking to competitors but not you), unlinked brand mentions, resource pages, guest posts, link reclamation, competitor dead pages, Moving Man (moved or closed resources), "best X" listicle inclusion, or skyscraper content - including finding prospects, checking dead links, counting referring domains, finding contacts and drafting outreach emails. Also use for plain requests like "get more backlinks", "build links to my site", "who links to my competitors", "find link opportunities", "why did I lose links" or "what can the linkbuilding skill do".

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 10 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Link building skill for AI agents

Give your AI agent your site. It finds the link opportunities, checks every link, finds a real contact and drafts the emails. You hit send.

The ten link building tactics in the skill

MIT licence Works with Claude Code Works with Codex and Cursor

Ten link building tactics, each a playbook with a clear pass or fail at every step, plus a working toolkit: dead link checks, expired domains, Wayback history, contact scanning and one tracker CSV.

Built by James Oliver. The full write-up and a real run: I turned my link building into a free Claude Code skill.

Get more skills and updates

This repo is free and always will be. I'm adding new skills regularly.

Join the email list to get every new skill, template and update in your inbox. No spam, unsubscribe anytime.

Want a hosted version instead?

Don't want to run anything yourself? Everything here is also on Answer Socrates, with no setup and many more features, including keyword research, trends, rising topics, YouTube keywords and clustering.

Try it on Answer Socrates

Quickstart

1. Install (pick one):

# Any agent that supports skills (Claude Code, Codex, Cursor and others)
npx skills add JamesOliverSEO/linkbuilding-skill

# Or clone it straight into Claude Code's skills folder
git clone https://github.com/JamesOliverSEO/linkbuilding-skill ~/.claude/skills/linkbuilding

[!TIP] npx skills add needs Node 22.20 or newer. On older Node it fails with does not provide an export named 'glob': update Node, or use the git clone line instead.

If you run npx skills add from inside an agent session, pass the agent explicitly, for example npx skills add JamesOliverSEO/linkbuilding-skill -a claude-code.

2. Ask in plain English:

Build links to mysite.com. It's a [niche] site. What should I do first?

That's it. It asks for anything it needs, picks a tactic, and walks you through it one step at a time. More starter prompts are in prompts.md.

3. Optional: connect DataForSEO for the backlink lookups (see below).

The ten tactics

#TacticStart here when
1Link reclamationyour site is older, moved URLs, or lost links
2"Best X" listiclesyou sell a product
3Unlinked mentionspeople already talk about your brand
4Broken link buildingyour niche has old resource lists and guides
5Competitor dead pagescompetitors have pruned or moved old content
6Link gapyou have clear competitors with more links
7Resource pagesyou have a genuinely useful guide or tool
8Guest postsyou can write expert articles
9Moving Mana tool or brand in your niche rebranded or shut down
10Skyscrapera competitor piece earns lots of links and you can beat it

What works free, and what needs DataForSEO

The toolkit is one Python file with no installs. Most of it is free. The backlink lookups use the DataForSEO Backlinks API, which is pay as you go. The skill always shows an estimate and waits for a yes before spending anything.

TacticWithout DataForSEORough cost with it
Unlinked mentionsWorks fully$0
Resource pagesWorks fully$0
"Best X" listiclesWorks, finds lists by search~$0.04 per competitor
Broken link buildingWorks, but cannot rank dead links by value~$0.03 to $0.05 a batch
Guest postsWorks, skips the site strength check~$0.03 for the whole list
Link reclamationNeeds it~$0.10 per site
Competitor dead pagesNeeds it~$0.03 per competitor, plus ~$0.03 per page
Link gapNeeds it~$0.15 for three competitors
Moving ManNeeds it to find the linking sites~$0.03 per closed brand
SkyscraperNeeds it~$0.06 per competitor

Costs measured in October 2026: about 2.4 US cents per call plus a tiny amount per row. Running all ten for one site costs well under a dollar.

To connect it, create a DataForSEO account, then set your API login:

export DATAFORSEO_LOGIN="your-login"
export DATAFORSEO_PASSWORD="your-api-password"

Or put those two lines (without export) in a .env file and point to it with DATAFORSEO_ENV_FILE=/path/to/.env. Never commit that file.

What is inside

linkbuilding-skill/
  SKILL.md               the brain: picks the tactic, sets the rules
  prompts.md             starter prompts for every tactic
  footprints.md          search strings that find prospects
  tracker-template.csv   the one spreadsheet you keep
  tactics/               one playbook per tactic
  scripts/blb.py         the toolkit: 13 commands, Python 3, no installs

House rules

  • It never sends email. It drafts, you send from your own inbox.
  • No guessed email addresses and no paid email finders.
  • It never pays for links. A site asking for a fee gets flagged for you.
  • One follow-up per prospect, then it stops.
  • One conversation per site at a time, tracked in one CSV.

Disclaimer

This skill is provided as is, with no warranty (see LICENSE). Use it at your own risk.

  • You send the emails, so you are responsible for them. The skill only drafts. Follow the outreach and privacy laws where you and your contacts are (for example CAN-SPAM, GDPR and PECR), and honour opt-outs.
  • Third-party costs are yours. DataForSEO calls are billed to your own account. The estimates shown are approximate.
  • No guaranteed results. This is not legal or professional SEO advice. Rankings and links are never guaranteed.
  • Be a good citizen. The toolkit makes light, polite requests. Respect each site's terms and don't hammer servers.
  • Not affiliated with Anthropic, OpenAI, Cursor or DataForSEO. Product names belong to their owners.
  • Affiliate link: the DataForSEO link in this README is an affiliate link. I may earn a commission at no cost to you.

Questions and ideas

Found a bug, or a tactic that should work differently? Open an issue.

Licence

MIT. See LICENSE.


⭐ Star the repo if it helped · Join the list · Hosted version

// HOW IT'S BUILT

// FILES

19 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md10.0 KB838cf0ab4b3aupstream ↗
    ---
    name: linkbuilding
    description: Use when building backlinks to a site with an outreach tactic - broken link building, link gap (sites linking to competitors but not you), unlinked brand mentions, resource pages, guest posts, link reclamation, competitor dead pages, Moving Man (moved or closed resources), "best X" listicle inclusion, or skyscraper content - including finding prospects, checking dead links, counting referring domains, finding contacts and drafting outreach emails. Also use for plain requests like "get more backlinks", "build links to my site", "who links to my competitors", "find link opportunities", "why did I lose links" or "what can the linkbuilding skill do".
    ---
    
    # Link building
    
    ## Overview
    
    A playbook per tactic, each with a decidable rule at every step, plus one shared toolkit. Output is always a prospect table and drafted emails. **The skill never sends email.** The user sends.
    
    ## Tactics
    
    | Tactic | File | Start here when |
    |---|---|---|
    | Broken link building | [broken-link-building.md](tactics/broken-link-building.md) | the niche has old resource lists and guides |
    | Link gap | [link-gap.md](tactics/link-gap.md) | the user has clear competitors with more links |
    | Unlinked brand mentions | [unlinked-mentions.md](tactics/unlinked-mentions.md) | the brand already gets talked about |
    | Resource pages | [resource-pages.md](tactics/resource-pages.md) | the user has genuinely useful guides or tools |
    | Guest posts | [guest-posts.md](tactics/guest-posts.md) | the user can write expert articles |
    | Link reclamation | [link-reclamation.md](tactics/link-reclamation.md) | the site is older, has moved URLs, or lost links (do this first: quickest wins) |
    | Competitor dead pages | [competitor-dead-pages.md](tactics/competitor-dead-pages.md) | competitors have pruned or moved old content |
    | Moving Man | [moving-man.md](tactics/moving-man.md) | a tool or brand in the niche rebranded or shut down |
    | "Best X" listicle inclusion | [listicle-inclusion.md](tactics/listicle-inclusion.md) | the user sells a product (start here for any SaaS) |
    | Skyscraper | [skyscraper.md](tactics/skyscraper.md) | a competitor piece earns many links and the user can beat it |
    
    When the user just says "build links", ask for the inputs below, then suggest an order: reclamation, then listicles (for a product) or unlinked mentions, then broken link building and competitor dead pages.
    
    When the user asks what the skill can do, give a two-line summary and show the starter prompts in [prompts.md](prompts.md).
    
    ## Talking to the user
    
    The user may not know SEO terms or tactic names. Run the session as a conversation, not a batch job.
    
    **Starting:**
    - Ask one question at a time. Start with the site, then what they want from it (more traffic to a page, links for a new product, recovering lost links).
    - Recommend one tactic with a one-line reason, for example "Your site moved URLs last year, so reclamation is the quickest win." Offer the others only if they ask.
    - Before the first step, say in two or three lines what the tactic does and what they will get at the end.
    
    **Before each step:** say what is about to happen, roughly how long it takes, and whether it costs anything. Paid steps follow the paid-call rule below.
    
    **After each step:**
    - Give a short plain summary with numbers, for example "Checked 40 pages, found 12 dead links, 3 worth pitching."
    - Show the top 5 to 10 rows as a small table with only the columns that matter for the decision. Save the full CSV and give its path. Never paste a whole CSV into chat.
    - Say what looks promising and what was dropped, and why, in a line or two.
    - End with a clear next choice: continue to the next step, adjust (a different niche keyword, a lower threshold), or stop here.
    
    **Words:** explain a term the first time it comes up, in one short clause. Examples:
    - referring domains: how many different sites link to that page;
    - dead / recheck / review: broken for sure / might be a temporary error, check again later / redirects somewhere else, needs a human look;
    - dofollow: a link that passes ranking value;
    - prospect: a page we might ask for a link.
    
    **Finishing a run (the handoff):**
    1. Where the tracker CSV and any other files were saved.
    2. How many emails are drafted, and the drafts themselves, ready to copy.
    3. What the user does next: send the emails from their own inbox, set `status = sent` and `first_sent` in the tracker, and come back in about 7 days for the follow-ups.
    4. One suggested next tactic, with its one-line reason.
    
    Keep messages short. When a step finds nothing, say so plainly and suggest what to change, rather than padding the result.
    
    ## Inputs every run needs
    
    Ask for anything missing before starting:
    
    1. Target site URL.
    2. Its niche, in a few words.
    3. Candidate pages to promote (a list of URLs, or run `blb.py sitemap SITE` and pick from it).
    4. Per tactic extras: competitors (link gap, competitor dead pages, listicles, skyscraper), brand names (unlinked mentions, listicles), the product's differentiator (listicles).
    
    ## Shared toolkit
    
    Script: `scripts/blb.py` in this skill's folder (Python 3 standard library, no install). Run it with the full path to wherever the skill is installed, for example `python3 ~/.claude/skills/linkbuilding/scripts/blb.py`. Every subcommand takes targets as arguments or `--file` (one per line, or a CSV with a `url`, `dead_url` or `domain` column) and writes CSV to stdout or `--out`.
    
    **Free:**
    
    | Need | Command |
    |---|---|
    | Dead outbound links on prospect pages | `blb.py outbound PAGE [...]` |
    | Check a list of URLs (and where redirects end) | `blb.py check URL [...]` (`--all` keeps live ones) |
    | Domain registered / expired / unregistered | `blb.py rdap DOMAIN [...]` |
    | First and last good Wayback copy | `blb.py wayback URL [...]` (slow, rate limited) |
    | Every URL a site has had | `blb.py history DOMAIN/PATH` (narrow big sites with a path) |
    | A site's sitemap URLs | `blb.py sitemap SITE` |
    | Does a page link to a domain, mention a brand | `blb.py haslink PAGE [...] --domain D --brand "B"` |
    | Qualify a prospect, find contact routes | `blb.py scan PAGE [...]` (published emails, contact/about/write-for-us pages, sponsored markers, CMS, socials, modified date) |
    | Finding prospect pages | The agent's own web search |
    
    **Paid (DataForSEO):**
    
    | Need | Command | Rough cost |
    |---|---|---|
    | Referring domains per URL or domain | `blb.py refdomains URL [...]` | one call per 1,000 URLs |
    | Linking pages, one per domain | `blb.py backlinks TARGET [--lost] [--broken] [--title "a\|b"]` | one call per target |
    | Competitor's dead pages with links | `blb.py deadpages DOMAIN [--min-rd 3]` | one call per domain |
    | Competitor's most-linked live pages | `blb.py toppages DOMAIN [--min-rd 20]` | one call per domain |
    | Domains linking to all competitors, not the user | `blb.py gap USER COMP1 COMP2 [...]` | one call |
    
    Measured October 2026: about **2.4 US cents per call plus 0.003 cents per row or URL**, so a 1,000-row call is about 5 cents. (Prices are written in cents because some agents rewrite a dollar sign followed by a digit when loading this file.) Calls are cheap; the thing to watch is running one call per target over long lists.
    
    DataForSEO's crawl can be weeks old: re-check anything it calls dead or lost with `check` or `haslink` before pitching.
    
    ### Paid-call rule
    
    Run every paid command without `--yes` first. It prints the call count and an upper-bound cost. Show the user that estimate and wait for a yes. Then re-run with `--yes`; it prints the actual cost. Use `--limit` to cap rows. Credentials come from `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` in the environment (or a `.env` file named by `DATAFORSEO_ENV_FILE`). If they are missing, say so, point the user to the README, and carry on with the free commands.
    
    ### Verdicts from `check` and `outbound`
    
    | Verdict | Reasons | Meaning |
    |---|---|---|
    | dead | `http_404`, `http_410`, `dns_fail`, `connection_refused`, `parked`, `redirect_home`, `soft_404`, `owner_archived` | A real prospect |
    | recheck | `blocked` (401/403/429), `server_error` (5xx), `timeout`, `ssl_error`, `dns_flaky` | Not dead yet. Re-run later; never pitch on a recheck, and never spend a paid call on one |
    | review | `redirect_offsite`, `closed_notice` | Redirects to another site, or loads but says the business closed. Look by hand: acquired, moved (Moving Man), or dead? |
    | live | `ok` | Dropped unless `--all` |
    
    `dns_fail` is only given after DNS keeps failing on repeated lookups; a lookup that fails once and then works gives `dns_flaky`. Big publishers often block the script (`blocked`): check those in a browser before calling a link lost.
    
    `owner_archived` means the site already swapped the link for a Wayback copy. The original is dead and the owner maintains links, which makes it a warm prospect.
    
    ## Prospect tracker
    
    Every tactic writes to one CSV the user keeps, from [tracker-template.csv](tracker-template.csv). Keep it in the site's own project folder as `linkbuilding/tracker.csv`, with each run's raw CSVs in `linkbuilding/runs/YYYY-MM-DD-<name>/`. Ask where the project folder is if it is not obvious, never leave the tracker in a temp folder. The `status` column moves through: `found`, `drafted`, `sent`, `followed_up`, `linked`, `declined`, `no_reply`. Add rows; never delete them, so the same site is not pitched twice. Before drafting, check the tracker for the prospect's domain: one live conversation per site at a time, whatever the tactic.
    
    ## House rules for all copy
    
    - No em dashes or en dashes anywhere, templates included. Check the rendered email, not just the source.
    - Outreach leads with what helps the recipient, then offers the user's page as one option.
    - No guessed email addresses and no paid email finders. Contacts come from bylines, author pages and contact/about pages (`scan` lists published ones).
    - No paying for links. A site that asks for a fee is flagged for the user, never accepted by the skill.
    - One follow-up per prospect, then stop.
    - Thresholds in these files are starting values to tune, not proven rules. When a run teaches something, update the tactic file and its change log line.
    
  • README.md7.5 KB74abc324d88dupstream ↗
    # Link building skill for AI agents
    
    **Give your AI agent your site. It finds the link opportunities, checks every link, finds a real contact and drafts the emails. You hit send.**
    
    ![The ten link building tactics in the skill](assets/tactics.gif)
    
    [![MIT licence](https://img.shields.io/badge/licence-MIT-green.svg)](LICENSE)
    [![Works with Claude Code](https://img.shields.io/badge/Claude_Code-ready-orange.svg)](#quickstart)
    [![Works with Codex and Cursor](https://img.shields.io/badge/Codex_%7C_Cursor-ready-blue.svg)](#quickstart)
    
    Ten link building tactics, each a playbook with a clear pass or fail at every step, plus a working toolkit: dead link checks, expired domains, Wayback history, contact scanning and one tracker CSV.
    
    Built by [James Oliver](https://oliver.com/?utm_source=github&utm_medium=readme&utm_campaign=linkbuilding-skill&utm_content=author). The full write-up and a real run: [I turned my link building into a free Claude Code skill](https://oliver.com/blog/free-link-building-skill?utm_source=github&utm_medium=readme&utm_campaign=linkbuilding-skill&utm_content=post).
    
    ## Get more skills and updates
    
    This repo is free and always will be. I'm adding new skills regularly.
    
    **[Join the email list](https://olivercom.substack.com/subscribe?utm_source=github&utm_medium=readme&utm_campaign=linkbuilding-skill&utm_content=email-section)** to get every new skill, template and update in your inbox. No spam, unsubscribe anytime.
    
    ## Want a hosted version instead?
    
    Don't want to run anything yourself? Everything here is also on **[Answer Socrates](https://answersocrates.com/?utm_source=github&utm_medium=readme&utm_campaign=linkbuilding-skill&utm_content=hosted-section)**, with no setup and many more features, including keyword research, trends, rising topics, YouTube keywords and clustering.
    
    **[Try it on Answer Socrates](https://answersocrates.com/?utm_source=github&utm_medium=readme&utm_campaign=linkbuilding-skill&utm_content=hosted-button)**
    
    ## Quickstart
    
    **1. Install** (pick one):
    
    ```bash
    # Any agent that supports skills (Claude Code, Codex, Cursor and others)
    npx skills add JamesOliverSEO/linkbuilding-skill
    
    # Or clone it straight into Claude Code's skills folder
    git clone https://github.com/JamesOliverSEO/linkbuilding-skill ~/.claude/skills/linkbuilding
    ```
    
    > [!TIP]
    > `npx skills add` needs Node 22.20 or newer. On older Node it fails with `does not provide an export named 'glob'`: update Node, or use the `git clone` line instead.
    >
    > If you run `npx skills add` from inside an agent session, pass the agent explicitly, for example `npx skills add JamesOliverSEO/linkbuilding-skill -a claude-code`.
    
    **2. Ask in plain English:**
    
    > Build links to mysite.com. It's a [niche] site. What should I do first?
    
    That's it. It asks for anything it needs, picks a tactic, and walks you through it one step at a time. More starter prompts are in [prompts.md](prompts.md).
    
    **3. Optional: connect DataForSEO** for the backlink lookups (see below).
    
    ## The ten tactics
    
    | # | Tactic | Start here when |
    |---|---|---|
    | 1 | [Link reclamation](tactics/link-reclamation.md) | your site is older, moved URLs, or lost links |
    | 2 | ["Best X" listicles](tactics/listicle-inclusion.md) | you sell a product |
    | 3 | [Unlinked mentions](tactics/unlinked-mentions.md) | people already talk about your brand |
    | 4 | [Broken link building](tactics/broken-link-building.md) | your niche has old resource lists and guides |
    | 5 | [Competitor dead pages](tactics/competitor-dead-pages.md) | competitors have pruned or moved old content |
    | 6 | [Link gap](tactics/link-gap.md) | you have clear competitors with more links |
    | 7 | [Resource pages](tactics/resource-pages.md) | you have a genuinely useful guide or tool |
    | 8 | [Guest posts](tactics/guest-posts.md) | you can write expert articles |
    | 9 | [Moving Man](tactics/moving-man.md) | a tool or brand in your niche rebranded or shut down |
    | 10 | [Skyscraper](tactics/skyscraper.md) | a competitor piece earns lots of links and you can beat it |
    
    ## What works free, and what needs DataForSEO
    
    The toolkit is one Python file with no installs. Most of it is free. The backlink lookups use the [DataForSEO](https://try.dataforseo.com/wpna3h013ems) Backlinks API, which is pay as you go. The skill always shows an estimate and waits for a yes before spending anything.
    
    | Tactic | Without DataForSEO | Rough cost with it |
    |---|---|---|
    | Unlinked mentions | Works fully | $0 |
    | Resource pages | Works fully | $0 |
    | "Best X" listicles | Works, finds lists by search | ~$0.04 per competitor |
    | Broken link building | Works, but cannot rank dead links by value | ~$0.03 to $0.05 a batch |
    | Guest posts | Works, skips the site strength check | ~$0.03 for the whole list |
    | Link reclamation | Needs it | ~$0.10 per site |
    | Competitor dead pages | Needs it | ~$0.03 per competitor, plus ~$0.03 per page |
    | Link gap | Needs it | ~$0.15 for three competitors |
    | Moving Man | Needs it to find the linking sites | ~$0.03 per closed brand |
    | Skyscraper | Needs it | ~$0.06 per competitor |
    
    Costs measured in October 2026: about 2.4 US cents per call plus a tiny amount per row. Running all ten for one site costs well under a dollar.
    
    To connect it, [create a DataForSEO account](https://try.dataforseo.com/wpna3h013ems), then set your API login:
    
    ```bash
    export DATAFORSEO_LOGIN="your-login"
    export DATAFORSEO_PASSWORD="your-api-password"
    ```
    
    Or put those two lines (without `export`) in a `.env` file and point to it with `DATAFORSEO_ENV_FILE=/path/to/.env`. Never commit that file.
    
    ## What is inside
    
    ```
    linkbuilding-skill/
      SKILL.md               the brain: picks the tactic, sets the rules
      prompts.md             starter prompts for every tactic
      footprints.md          search strings that find prospects
      tracker-template.csv   the one spreadsheet you keep
      tactics/               one playbook per tactic
      scripts/blb.py         the toolkit: 13 commands, Python 3, no installs
    ```
    
    ## House rules
    
    - It never sends email. It drafts, you send from your own inbox.
    - No guessed email addresses and no paid email finders.
    - It never pays for links. A site asking for a fee gets flagged for you.
    - One follow-up per prospect, then it stops.
    - One conversation per site at a time, tracked in one CSV.
    
    ### Disclaimer
    
    This skill is provided as is, with no warranty (see [LICENSE](LICENSE)). Use it at your own risk.
    
    - **You send the emails, so you are responsible for them.** The skill only drafts. Follow the outreach and privacy laws where you and your contacts are (for example CAN-SPAM, GDPR and PECR), and honour opt-outs.
    - **Third-party costs are yours.** DataForSEO calls are billed to your own account. The estimates shown are approximate.
    - **No guaranteed results.** This is not legal or professional SEO advice. Rankings and links are never guaranteed.
    - **Be a good citizen.** The toolkit makes light, polite requests. Respect each site's terms and don't hammer servers.
    - **Not affiliated** with Anthropic, OpenAI, Cursor or DataForSEO. Product names belong to their owners.
    - **Affiliate link:** the DataForSEO link in this README is an affiliate link. I may earn a commission at no cost to you.
    
    ## Questions and ideas
    
    Found a bug, or a tactic that should work differently? [Open an issue](https://github.com/JamesOliverSEO/linkbuilding-skill/issues).
    
    ## Licence
    
    MIT. See [LICENSE](LICENSE).
    
    ---
    
    ⭐ Star the repo if it helped · [Join the list](https://olivercom.substack.com/subscribe?utm_source=github&utm_medium=readme_footer&utm_campaign=linkbuilding-skill) · [Hosted version](https://answersocrates.com/?utm_source=github&utm_medium=readme_footer&utm_campaign=linkbuilding-skill)
    
  • scripts/blb.py30 KB880a3f4238c4upstream ↗
    #!/usr/bin/env python3
    """Link building helpers. Standard library only.
    
    Subcommands (free):
      outbound URL [URL ...]        external links on prospect pages, checked for dead ones
      check URL [URL ...]           check a list of URLs directly (dead / live / recheck / review)
      rdap DOMAIN [DOMAIN ...]      registration status and expiry from RDAP
      wayback URL [URL ...]         first and last good Wayback capture (rate limited)
      history DOMAIN                every URL Wayback has seen on a domain (find old pages)
      sitemap URL_OR_DOMAIN         URLs listed in a site's XML sitemaps
      haslink PAGE [...] --domain D does each page link to D (anchor, rel), and mention --brand
      scan PAGE [...]               qualify a prospect: contact routes, published emails,
                                    write-for-us page, sponsored markers, CMS, socials
    
    Subcommands (PAID, DataForSEO, print an estimate and need --yes):
      refdomains URL [URL ...]      referring domains per URL or domain
      backlinks TARGET [...]        linking pages, one per domain (--lost, --broken, --title)
      deadpages DOMAIN [...]        a domain's 4xx/5xx pages that still have referring domains
      toppages DOMAIN [...]         a domain's most-linked live pages
      gap YOU COMP [COMP ...]       domains linking to every competitor but not to YOU
    
    Every subcommand also reads targets from --file (one per line, or a CSV with a
    url / dead_url column) and writes CSV to stdout or --out.
    """
    
    import argparse
    import csv
    import io
    import json
    import os
    import re
    import socket
    import ssl
    import sys
    import time
    import urllib.error
    import urllib.parse
    import urllib.request
    from base64 import b64encode
    from concurrent.futures import ThreadPoolExecutor
    from html.parser import HTMLParser
    
    UA = ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
          "(KHTML, like Gecko) Chrome/126.0 Safari/537.36")
    TIMEOUT = 15
    READ_BYTES = 200_000
    
    # Hosts that are never broken-link targets (share buttons, profiles).
    SKIP_HOSTS = {"facebook.com", "twitter.com", "x.com", "linkedin.com", "pinterest.com",
                  "instagram.com", "youtube.com", "youtu.be", "t.co", "wa.me", "tiktok.com",
                  "reddit.com", "whatsapp.com", "google.com", "apple.com"}
    SECOND_LEVEL = {"co.uk", "org.uk", "ac.uk", "gov.uk", "me.uk", "com.au", "net.au", "org.au",
                    "co.nz", "co.za", "com.br", "co.jp", "co.in", "com.mx", "com.sg", "com.tr"}
    
    PARKED_MARKERS = ["domain is for sale", "buy this domain", "this domain may be for sale",
                      "domain for sale", "parked free", "parkingcrew", "sedoparking", "sedo.com",
                      "dan.com", "afternic", "hugedomains", "bodis.com", "above.com",
                      "this domain has expired", "domain has expired", "renew this domain",
                      "abovedomains", "forsale.min.js"]
    # A brand that shut down but still serves a 200 page. Verdict review: read it by hand.
    CLOSED_MARKERS = ["ceased trading", "no longer trading", "wrap up operations",
                      "bid farewell", "has closed its doors", "we have closed", "closing down sale",
                      "permanently closed", "we are closing"]
    SOFT404_TITLE = re.compile(r"\b(404|not found|page not found|page cannot be found|"
                               r"no longer available|doesn.t exist)\b", re.I)
    
    # Optional .env file holding DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD, used only when they
    # are not already set in the environment.
    DFS_ENV_DEFAULT = os.environ.get("DATAFORSEO_ENV_FILE", ".env")
    # Observed in October 2026: refdomains 2 URLs $0.024072; backlinks, domain_pages and
    # domain_intersection $0.0242 at 5 rows and $0.0244 at 10 rows. So about
    # $0.024 per call + $0.00003 per URL or row. Estimates round up slightly.
    DFS_CALL_COST = 0.025
    DFS_URL_COST = 0.00005
    DFS_BATCH = 1000
    DFS_ROW_COST = 0.00005
    
    SPONSORED_MARKERS = ["sponsored post", "sponsored content", "paid post", "advertorial",
                         "partner content", "in partnership with", "this post is sponsored"]
    SOCIAL_HOSTS = ["twitter.com", "x.com", "linkedin.com", "facebook.com", "instagram.com",
                    "youtube.com", "tiktok.com", "threads.net", "bsky.app", "mastodon.social"]
    EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
    EMAIL_SKIP = ("example.", "sentry", "wixpress", "@2x", ".png", ".jpg", ".webp", "domain.com")
    
    
    def reg_domain(host):
        host = (host or "").lower().split(":")[0].strip(".")
        if host.startswith("www."):
            host = host[4:]
        parts = host.split(".")
        if len(parts) >= 3 and ".".join(parts[-2:]) in SECOND_LEVEL:
            return ".".join(parts[-3:])
        return ".".join(parts[-2:])
    
    
    def http_get(url, read=READ_BYTES):
        req = urllib.request.Request(url, headers={"User-Agent": UA, "Accept": "text/html,*/*"})
        ctx = ssl.create_default_context()
        with urllib.request.urlopen(req, timeout=TIMEOUT, context=ctx) as r:
            body = r.read(read)
            charset = r.headers.get_content_charset() or "utf-8"
            return r.status, r.geturl(), body.decode(charset, "replace")
    
    
    WAYBACK_LINK = re.compile(r"^https?://web\.archive\.org/web/\d+[a-z_]*/(.+)$", re.I)
    
    
    def resolves(host, tries=3):
        """True when DNS answers for host. Retries because lookups fail spuriously under load."""
        for i in range(tries):
            try:
                socket.getaddrinfo(host, 443)
                return True
            except socket.gaierror:
                time.sleep(2 * (i + 1))
        return False
    
    
    def classify(url, _retried=False):
        """Return dict(url, verdict, reason, http_status, final_url).
    
        verdict: dead | live | recheck | review
        """
        out = {"url": url, "verdict": "", "reason": "", "http_status": "", "final_url": ""}
        m = WAYBACK_LINK.match(url)
        if m:
            # The site owner already swapped a dead link for an archive copy: the original is
            # dead and they maintain their links. Not fetched (archive.org rate limits hard).
            out.update(verdict="dead", reason="owner_archived", final_url=m.group(1))
            return out
        try:
            status, final, body = http_get(url)
        except urllib.error.HTTPError as e:
            out["http_status"] = e.code
            if e.code in (404, 410):
                out.update(verdict="dead", reason=f"http_{e.code}")
            elif e.code in (401, 403, 429, 503) or e.code >= 500:
                out.update(verdict="recheck", reason="blocked" if e.code < 500 else "server_error")
            else:
                out.update(verdict="recheck", reason=f"http_{e.code}")
            return out
        except urllib.error.URLError as e:
            r = e.reason
            if isinstance(r, socket.gaierror):
                # One failed lookup is not proof: parallel checks produced false dns_fail on
                # live sites. Only dead when DNS keeps failing on its own.
                host = urllib.parse.urlparse(url).hostname or ""
                if not _retried and resolves(host):
                    return classify(url, _retried=True)
                if _retried:
                    out.update(verdict="recheck", reason="dns_flaky")
                else:
                    out.update(verdict="dead", reason="dns_fail")
            elif isinstance(r, (socket.timeout, TimeoutError)):
                out.update(verdict="recheck", reason="timeout")
            elif isinstance(r, ssl.SSLError):
                out.update(verdict="recheck", reason="ssl_error")
            elif isinstance(r, ConnectionRefusedError):
                out.update(verdict="dead", reason="connection_refused")
            else:
                out.update(verdict="recheck", reason=f"error:{type(r).__name__}")
            return out
        except (socket.timeout, TimeoutError):
            out.update(verdict="recheck", reason="timeout")
            return out
        except Exception as e:  # noqa: BLE001 - any other failure is a recheck, never a dead link
            out.update(verdict="recheck", reason=f"error:{type(e).__name__}")
            return out
    
        out["http_status"] = status
        out["final_url"] = final
        src, dst = urllib.parse.urlparse(url), urllib.parse.urlparse(final)
        low = body.lower()
        title = re.search(r"<title[^>]*>(.*?)</title>", body, re.I | re.S)
        title = title.group(1).strip() if title else ""
    
        if any(m in low for m in PARKED_MARKERS):
            out.update(verdict="dead", reason="parked")
        elif src.path.strip("/") and not dst.path.strip("/") and not dst.query:
            out.update(verdict="dead", reason="redirect_home")
        elif SOFT404_TITLE.search(title):
            out.update(verdict="dead", reason="soft_404")
        elif reg_domain(src.hostname) != reg_domain(dst.hostname):
            out.update(verdict="review", reason="redirect_offsite")
        elif any(m in low for m in CLOSED_MARKERS):
            out.update(verdict="review", reason="closed_notice")
        else:
            out.update(verdict="live", reason="ok")
        return out
    
    
    def check_many(urls, workers):
        """Classify URLs in parallel across hosts, one at a time per host with a 1s gap."""
        by_host = {}
        for u in urls:
            by_host.setdefault(urllib.parse.urlparse(u).hostname or "", []).append(u)
        results = {}
    
        def run_host(host_urls):
            for i, u in enumerate(host_urls):
                if i:
                    time.sleep(1)
                results[u] = classify(u)
    
        with ThreadPoolExecutor(workers) as ex:
            list(ex.map(run_host, by_host.values()))
        return [results[u] for u in urls]
    
    
    class LinkParser(HTMLParser):
        def __init__(self):
            super().__init__()
            self.links, self._cur = [], None
    
        def handle_starttag(self, tag, attrs):
            if tag == "a":
                a = dict(attrs)
                if a.get("href"):
                    self._cur = {"href": a["href"], "rel": a.get("rel") or "", "text": ""}
    
        def handle_data(self, data):
            if self._cur is not None:
                self._cur["text"] += data
    
        def handle_endtag(self, tag):
            if tag == "a" and self._cur is not None:
                self._cur["text"] = " ".join(self._cur["text"].split())[:120]
                self.links.append(self._cur)
                self._cur = None
    
    
    def outbound_links(page_url):
        _, final, body = http_get(page_url, read=3_000_000)
        p = LinkParser()
        p.feed(body)
        home = reg_domain(urllib.parse.urlparse(final).hostname)
        seen, out = set(), []
        for l in p.links:
            u = urllib.parse.urljoin(final, l["href"]).split("#")[0]
            pu = urllib.parse.urlparse(u)
            if (pu.hostname or "").endswith("safelinks.protection.outlook.com"):
                # Outlook-wrapped link: check the real target, not the wrapper.
                u = urllib.parse.parse_qs(pu.query).get("url", [u])[0].split("#")[0]
                pu = urllib.parse.urlparse(u)
            if pu.scheme not in ("http", "https"):
                continue
            d = reg_domain(pu.hostname)
            if d == home or d in SKIP_HOSTS or u in seen:
                continue
            seen.add(u)
            out.append({"url": u, "anchor": l["text"], "rel": l["rel"]})
        return out
    
    
    def rdap(domain):
        domain = reg_domain(domain if "/" not in domain else urllib.parse.urlparse(domain).hostname)
        row = {"domain": domain, "domain_status": "", "registered": "", "expires": ""}
        try:
            req = urllib.request.Request(f"https://rdap.org/domain/{domain}", headers={"User-Agent": UA})
            with urllib.request.urlopen(req, timeout=TIMEOUT) as r:
                d = json.load(r)
        except urllib.error.HTTPError as e:
            row["domain_status"] = "unregistered" if e.code == 404 else f"rdap_http_{e.code}"
            return row
        except Exception as e:  # noqa: BLE001
            row["domain_status"] = f"rdap_error:{type(e).__name__}"
            return row
        ev = {e.get("eventAction"): e.get("eventDate", "")[:10] for e in d.get("events", [])}
        row["registered"], row["expires"] = ev.get("registration", ""), ev.get("expiration", "")
        st = " ".join(d.get("status", [])).lower()
        if "redemption" in st or "pending delete" in st:
            row["domain_status"] = "expiring"
        elif row["expires"] and row["expires"] < time.strftime("%Y-%m-%d"):
            row["domain_status"] = "expired"
        else:
            row["domain_status"] = "registered"
        return row
    
    
    def _wb_get(url, tries=4, timeout=30):
        wait = 5
        for i in range(tries):
            try:
                req = urllib.request.Request(url, headers={"User-Agent": UA})
                with urllib.request.urlopen(req, timeout=timeout) as r:
                    return r.read().decode("utf-8", "replace")
            except urllib.error.HTTPError as e:
                if e.code in (429, 503) and i < tries - 1:
                    time.sleep(wait)
                    wait *= 3
                    continue
                raise
            except (TimeoutError, socket.timeout):
                if i < tries - 1:
                    time.sleep(wait)
                    wait *= 3
                    continue
                raise
        return ""
    
    
    def wayback(url):
        row = {"url": url, "captures_ok": "", "first_ok": "", "last_ok": "", "last_ok_snapshot": ""}
        base = ("https://web.archive.org/cdx/search/cdx?output=json&filter=statuscode:200"
                "&fl=timestamp,original&url=" + urllib.parse.quote(url, safe=""))
        try:
            first = json.loads(_wb_get(base + "&limit=1") or "[]")
            time.sleep(1.5)
            last = json.loads(_wb_get(base + "&limit=-1") or "[]")
        except Exception as e:  # noqa: BLE001
            row["captures_ok"] = f"error:{type(e).__name__}"
            return row
        if len(first) < 2:
            row["captures_ok"] = "0"
            return row
        row["captures_ok"] = "yes"
        row["first_ok"] = first[1][0][:8]
        if len(last) >= 2:
            ts, orig = last[1]
            row["last_ok"] = ts[:8]
            row["last_ok_snapshot"] = f"https://web.archive.org/web/{ts}/{orig}"
        return row
    
    
    def dfs_creds(env_path):
        login, pw = os.environ.get("DATAFORSEO_LOGIN"), os.environ.get("DATAFORSEO_PASSWORD")
        if not (login and pw) and os.path.exists(env_path):
            for line in open(env_path):
                k, _, v = line.strip().partition("=")
                if k == "DATAFORSEO_LOGIN":
                    login = v.strip().strip('"')
                elif k == "DATAFORSEO_PASSWORD":
                    pw = v.strip().strip('"')
        if not (login and pw):
            sys.exit("DataForSEO credentials not found. Set DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD "
                     f"in your environment or in {env_path} (see the README).")
        return login, pw
    
    
    def refdomains(urls, env_path):
        login, pw = dfs_creds(env_path)
        auth = "Basic " + b64encode(f"{login}:{pw}".encode()).decode()
        rows, total = [], 0.0
        for i in range(0, len(urls), DFS_BATCH):
            batch = urls[i:i + DFS_BATCH]
            req = urllib.request.Request(
                "https://api.dataforseo.com/v3/backlinks/bulk_referring_domains/live",
                data=json.dumps([{"targets": batch}]).encode(),
                headers={"Authorization": auth, "Content-Type": "application/json"}, method="POST")
            with urllib.request.urlopen(req, timeout=120) as r:
                task = json.load(r)["tasks"][0]
            if task["status_code"] != 20000:
                sys.exit(f"DataForSEO error {task['status_code']}: {task['status_message']}")
            total += task.get("cost") or 0
            for res in task.get("result") or []:
                for it in res.get("items") or []:
                    rows.append({"url": it["target"],
                                 "ref_domains": it.get("referring_main_domains", 0),
                                 "ref_domains_dofollow": (it.get("referring_main_domains", 0)
                                                          - it.get("referring_main_domains_nofollow", 0))})
        print(f"DataForSEO actual cost: ${total:.4f}", file=sys.stderr)
        return rows
    
    
    def dfs_post(endpoint, payload, env_path):
        login, pw = dfs_creds(env_path)
        auth = "Basic " + b64encode(f"{login}:{pw}".encode()).decode()
        req = urllib.request.Request(
            f"https://api.dataforseo.com/v3/backlinks/{endpoint}/live",
            data=json.dumps([payload]).encode(),
            headers={"Authorization": auth, "Content-Type": "application/json"}, method="POST")
        with urllib.request.urlopen(req, timeout=120) as r:
            task = json.load(r)["tasks"][0]
        if task["status_code"] != 20000:
            sys.exit(f"DataForSEO error {task['status_code']}: {task['status_message']}")
        res = (task.get("result") or [{}])[0] or {}
        return res.get("items") or [], task.get("cost") or 0
    
    
    def backlinks(target, limit, env_path, lost=False, broken=False, title=None):
        payload = {"target": target, "mode": "one_per_domain", "limit": limit,
                   "order_by": ["domain_from_rank,desc"]}
        if lost:
            payload["backlinks_status_type"] = "lost"
        filters = []
        if title:
            # Filter on DataForSEO's side so --limit counts matching rows. "a|b" becomes OR'd likes.
            terms = [t.strip() for t in title.split("|") if t.strip()][:6]
            likes = []
            for t in terms:
                likes += [["page_from_title", "like", f"%{t}%"], "or"]
            filters.append(likes[:-1] if len(terms) > 1 else likes[0])
        if broken:
            filters.append(["is_broken", "=", True])
        if filters:
            payload["filters"] = filters[0] if len(filters) == 1 else [filters[0], "and", filters[1]]
        items, cost = dfs_post("backlinks", payload, env_path)
        rows = []
        for it in items:
            rows.append({"target": target, "url_from": it.get("url_from"),
                         "domain_from": it.get("domain_from"), "page_from_title": it.get("page_from_title"),
                         "anchor": it.get("anchor"), "dofollow": it.get("dofollow"),
                         "domain_from_rank": it.get("domain_from_rank"), "url_to": it.get("url_to"),
                         "url_to_status_code": it.get("url_to_status_code"), "is_lost": it.get("is_lost"),
                         "is_broken": it.get("is_broken"), "first_seen": (it.get("first_seen") or "")[:10],
                         "last_seen": (it.get("last_seen") or "")[:10]})
        return rows, cost
    
    
    def domain_pages(domain, limit, env_path, dead, min_rd):
        if dead:
            filters = [["status_code", ">=", 400], "and",
                       ["page_summary.referring_main_domains", ">=", min_rd]]
        else:
            filters = [["status_code", "=", 200], "and",
                       ["page_summary.referring_main_domains", ">=", min_rd]]
        items, cost = dfs_post("domain_pages", {
            "target": domain, "limit": limit, "filters": filters,
            "order_by": ["page_summary.referring_main_domains,desc"]}, env_path)
        rows = [{"domain": domain, "page": it.get("page"), "status_code": it.get("status_code"),
                 "title": (it.get("meta") or {}).get("title"),
                 "ref_domains": (it.get("page_summary") or {}).get("referring_main_domains"),
                 "dfs_crawled": (it.get("fetch_time") or "")[:10]} for it in items]
        return rows, cost
    
    
    def gap(you, comps, limit, env_path):
        items, cost = dfs_post("domain_intersection", {
            "targets": {str(i + 1): c for i, c in enumerate(comps)},
            "exclude_targets": [you], "limit": limit,
            "order_by": ["1.rank,desc"]}, env_path)
        rows = []
        for it in items:
            di = it.get("domain_intersection") or {}
            first = di.get("1") or {}
            row = {"referring_domain": first.get("target"), "rank": first.get("rank")}
            for k, v in sorted(di.items()):
                row[f"backlinks_to_{comps[int(k) - 1]}"] = (v or {}).get("backlinks")
            rows.append(row)
        return rows, cost
    
    
    def history(prefix, limit=2000):
        """Distinct URLs Wayback captured with a 200 under a domain or path prefix
        (example.com or example.com/blog). Big sites are slow: narrow with a path."""
        prefix = re.sub(r"^https?://", "", prefix).rstrip("/*")
        q = ("https://web.archive.org/cdx/search/cdx?output=json&collapse=urlkey"
             "&filter=statuscode:200&filter=mimetype:text/html&fl=original,timestamp"
             f"&limit={limit}&url={urllib.parse.quote(prefix)}/*")
        try:
            data = json.loads(_wb_get(q, tries=3, timeout=120) or "[]")
        except Exception as e:  # noqa: BLE001
            print(f"Wayback index failed for {prefix} ({type(e).__name__}); narrow it with a path, "
                  f"e.g. {prefix}/blog", file=sys.stderr)
            return []
        return [{"url": u, "last_seen_ok": ts[:8]} for u, ts in data[1:]]
    
    
    def sitemap(target, cap=50000):
        if not target.startswith("http"):
            target = "https://" + target
        p = urllib.parse.urlparse(target)
        root = f"{p.scheme}://{p.netloc}"
        queue = [target] if p.path.endswith(".xml") else []
        if not queue:
            try:
                _, _, robots = http_get(root + "/robots.txt")
                queue = re.findall(r"(?im)^sitemap:\s*(\S+)", robots)
            except Exception:  # noqa: BLE001
                pass
            queue = queue or [root + "/sitemap.xml"]
        rows, seen = [], set()
        while queue and len(rows) < cap:
            sm = queue.pop(0)
            if sm in seen:
                continue
            seen.add(sm)
            try:
                _, _, xml = http_get(sm, read=20_000_000)
            except Exception as e:  # noqa: BLE001
                print(f"could not fetch {sm}: {e}", file=sys.stderr)
                continue
            if "<sitemapindex" in xml:
                queue += re.findall(r"<loc>\s*(.*?)\s*</loc>", xml)
                continue
            for block in re.findall(r"<url>(.*?)</url>", xml, re.S):
                loc = re.search(r"<loc>\s*(.*?)\s*</loc>", block)
                mod = re.search(r"<lastmod>\s*(.*?)\s*</lastmod>", block)
                if loc:
                    rows.append({"url": loc.group(1), "lastmod": mod.group(1)[:10] if mod else ""})
        return rows
    
    
    def haslink(page, domain, brand=None):
        row = {"page": page, "links_to_domain": "", "anchor": "", "rel": "", "mentions_brand": ""}
        try:
            _, final, body = http_get(page, read=3_000_000)
        except Exception as e:  # noqa: BLE001
            row["links_to_domain"] = f"fetch_error:{type(e).__name__}"
            return row
        p = LinkParser()
        p.feed(body)
        want = reg_domain(domain)
        hits = [l for l in p.links
                if reg_domain(urllib.parse.urlparse(urllib.parse.urljoin(final, l["href"])).hostname) == want]
        row["links_to_domain"] = "yes" if hits else "no"
        if hits:
            row["anchor"] = " | ".join(dict.fromkeys(h["text"] for h in hits))[:200]
            row["rel"] = " | ".join(dict.fromkeys(h["rel"] or "follow" for h in hits))
        if brand:
            text = re.sub(r"<[^>]+>", " ", re.sub(r"(?is)<(script|style).*?</\1>", " ", body))
            row["mentions_brand"] = "yes" if re.search(re.escape(brand), text, re.I) else "no"
        return row
    
    
    def scan(page):
        row = {"page": page, "emails": "", "contact_page": "", "about_page": "", "write_for_us": "",
               "sponsored_markers": "", "cms": "", "socials": "", "modified": ""}
        try:
            _, final, body = http_get(page, read=3_000_000)
        except Exception as e:  # noqa: BLE001
            row["emails"] = f"fetch_error:{type(e).__name__}"
            return row
        low = body.lower()
        p = LinkParser()
        p.feed(body)
        links = [(urllib.parse.urljoin(final, l["href"]), l["text"].lower()) for l in p.links]
        home = reg_domain(urllib.parse.urlparse(final).hostname)
    
        def first(pred):
            return next((u for u, t in links if pred(u.lower(), t)), "")
    
        row["contact_page"] = first(lambda u, t: "contact" in u or "contact" in t)
        row["about_page"] = first(lambda u, t: re.search(r"/about(-us)?/?$", u) or t in ("about", "about us"))
        row["write_for_us"] = first(lambda u, t: any(k in u or k in t for k in (
            "write-for-us", "write for us", "contribute", "guest-post", "guest post", "submit")))
        emails = {m.lower() for m in EMAIL_RE.findall(body) if not any(s in m.lower() for s in EMAIL_SKIP)}
        emails |= {u[7:].split("?")[0].lower() for u, _ in links if u.lower().startswith("mailto:")}
        row["emails"] = " | ".join(sorted(e for e in emails if "@" in e))
        row["sponsored_markers"] = " | ".join(m for m in SPONSORED_MARKERS if m in low)
        gen = re.search(r'<meta[^>]+name=["\']generator["\'][^>]+content=["\']([^"\']+)', body, re.I)
        row["cms"] = gen.group(1) if gen else ("WordPress" if "/wp-content/" in low else "")
        row["socials"] = " | ".join(sorted({u for u, _ in links if reg_domain(urllib.parse.urlparse(u).hostname)
                                            in SOCIAL_HOSTS and reg_domain(urllib.parse.urlparse(u).hostname) != home}))[:500]
        mod = re.search(r'(?:article:modified_time|dateModified)["\']?\s*(?:content=|:)\s*["\']([0-9-]{10})', body)
        row["modified"] = mod.group(1) if mod else ""
        return row
    
    
    def read_targets(args):
        items = list(args.targets)
        if args.file:
            text = open(args.file).read()
            first = text.splitlines()[0] if text.strip() else ""
            if "," in first:
                for r in csv.DictReader(io.StringIO(text)):
                    v = r.get("dead_url") or r.get("url") or r.get("domain")
                    if v:
                        items.append(v.strip())
            else:
                items += [l.strip() for l in text.splitlines() if l.strip() and not l.startswith("#")]
        return list(dict.fromkeys(items))
    
    
    def write_csv(rows, path):
        if not rows:
            print("no rows", file=sys.stderr)
            return
        keys = list(dict.fromkeys(k for r in rows for k in r))
        f = open(path, "w", newline="") if path else sys.stdout
        w = csv.DictWriter(f, fieldnames=keys)
        w.writeheader()
        w.writerows(rows)
        if path:
            f.close()
            print(f"wrote {len(rows)} rows to {path}", file=sys.stderr)
    
    
    def main():
        ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
        ap.add_argument("cmd", choices=["outbound", "check", "rdap", "wayback", "history", "sitemap",
                                        "haslink", "scan", "refdomains", "backlinks", "deadpages",
                                        "toppages", "gap"])
        ap.add_argument("targets", nargs="*")
        ap.add_argument("--file")
        ap.add_argument("--out")
        ap.add_argument("--all", action="store_true", help="outbound/check: include live links too")
        ap.add_argument("--workers", type=int, default=8)
        ap.add_argument("--yes", action="store_true", help="paid commands: confirm the call")
        ap.add_argument("--env", default=DFS_ENV_DEFAULT, help="paid commands: .env file with DataForSEO credentials")
        ap.add_argument("--limit", type=int, default=100, help="paid commands: max rows per target")
        ap.add_argument("--min-rd", type=int, default=3, help="deadpages/toppages: min referring domains")
        ap.add_argument("--lost", action="store_true", help="backlinks: lost links only")
        ap.add_argument("--broken", action="store_true", help="backlinks: links to broken pages only")
        ap.add_argument("--title", help="backlinks: keep linking pages whose title matches this regex")
        ap.add_argument("--domain", help="haslink: the domain to look for")
        ap.add_argument("--brand", help="haslink: brand name to look for in the page text")
        args = ap.parse_intermixed_args()
        targets = read_targets(args)
        if not targets:
            sys.exit("no targets")
    
        if args.cmd in ("backlinks", "deadpages", "toppages", "gap"):
            calls = 1 if args.cmd == "gap" else len(targets)
            if args.cmd == "gap" and len(targets) < 2:
                sys.exit("gap needs YOUR domain then at least one competitor")
            est = calls * (DFS_CALL_COST + args.limit * DFS_ROW_COST)
            print(f"{calls} call(s) at up to {args.limit} rows each, estimated cost up to ${est:.3f}",
                  file=sys.stderr)
            if not args.yes:
                sys.exit("not run: re-run with --yes once the cost is approved")
            rows, total = [], 0.0
            if args.cmd == "gap":
                rows, total = gap(targets[0], targets[1:], args.limit, args.env)
            for t in ([] if args.cmd == "gap" else targets):
                if args.cmd == "backlinks":
                    r, c = backlinks(t, args.limit, args.env, args.lost, args.broken, args.title)
                else:
                    r, c = domain_pages(t, args.limit, args.env, args.cmd == "deadpages", args.min_rd)
                rows += r
                total += c
            print(f"DataForSEO actual cost: ${total:.4f}", file=sys.stderr)
        elif args.cmd == "history":
            rows = [r for t in targets for r in history(t, args.limit if args.limit != 100 else 2000)]
        elif args.cmd == "sitemap":
            rows = [r for t in targets for r in sitemap(t)]
        elif args.cmd == "haslink":
            if not args.domain:
                sys.exit("haslink needs --domain")
            rows = [haslink(t, args.domain, args.brand) for t in targets]
        elif args.cmd == "scan":
            rows = [scan(t) for t in targets]
        elif args.cmd == "refdomains":
            calls = -(-len(targets) // DFS_BATCH)
            est = calls * DFS_CALL_COST + len(targets) * DFS_URL_COST
            print(f"{len(targets)} URLs in {calls} call(s), estimated cost ${est:.3f}", file=sys.stderr)
            if not args.yes:
                sys.exit("not run: re-run with --yes once the cost is approved")
            rows = refdomains(targets, args.env)
            rows.sort(key=lambda r: -r["ref_domains"])
        elif args.cmd == "rdap":
            rows = [rdap(t) for t in targets]
        elif args.cmd == "wayback":
            rows = []
            for t in targets:
                rows.append(wayback(t))
                time.sleep(1.5)
        elif args.cmd == "check":
            rows = check_many(targets, args.workers)
            if not args.all:
                rows = [r for r in rows if r["verdict"] != "live"]
        else:
            rows = []
            for page in targets:
                try:
                    links = outbound_links(page)
                except Exception as e:  # noqa: BLE001
                    print(f"could not fetch {page}: {e}", file=sys.stderr)
                    continue
                checked = check_many([l["url"] for l in links], args.workers)
                seen_dead = set()
                for l, c in zip(links, checked):
                    if c["verdict"] == "live" and not args.all:
                        continue
                    dead = c["final_url"] if c["reason"] == "owner_archived" else l["url"]
                    if dead in seen_dead:
                        continue
                    seen_dead.add(dead)
                    rows.append({"prospect_page": page, "dead_url": dead, "anchor": l["anchor"],
                                 "rel": l["rel"], "verdict": c["verdict"], "reason": c["reason"],
                                 "http_status": c["http_status"], "final_url": c["final_url"]})
                print(f"{page}: {len(links)} external links checked", file=sys.stderr)
            # Domain-level dead links get an RDAP lookup: an expired domain is the top prospect.
            for r in rows:
                if r["reason"] in ("dns_fail", "parked", "connection_refused"):
                    r["domain_status"] = rdap(r["dead_url"])["domain_status"]
        write_csv(rows, args.out)
    
    
    if __name__ == "__main__":
        main()
    
  • assets/tactics.gif812 KBc307be045374upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • .gitignore89 Ba425cd1c2e22upstream ↗
    .env
    .env.*
    __pycache__/
    *.pyc
    .DS_Store
    linkbuilding/
    runs/
    *.csv
    !tracker-template.csv
    
  • footprints.md2.2 KB75ceafd956c5upstream ↗
    # Footprints
    
    Search patterns for finding prospect pages. Replace `[niche]`, `[category]`, `[brand]` and `[competitor]` with real terms (try two or three variants of each).
    
    These are **starting points to test**, not proven patterns. Search operators (`intitle:`, `inurl:`, `site:`, quotes, `-`) are standard Google syntax; some search tools ignore them, so check that the results actually match and fall back to plain phrases when they do not.
    
    Mark a footprint `(works)` or `(dud)` after a run, with the date.
    
    ## Resource pages (broken link building, resource pages)
    
    - `[niche] intitle:resources`
    - `[niche] intitle:"useful links"`
    - `[niche] intitle:"helpful links"`
    - `[niche] inurl:resources`
    - `[niche] inurl:links`
    - `[niche] "useful resources"`
    - `[niche] "recommended sites"`
    - `[niche] "further reading"`
    - `[niche] intitle:"best" "websites"`
    
    ## Old guides likely to have rotted links (broken link building)
    
    - `[niche] "ultimate guide"` (prefer results with old publish dates)
    - `[niche] "complete guide"` (same)
    - `[niche] "list of"`
    - `[niche] site:.edu resources` (university and library guides)
    - `[niche] site:.gov resources`
    
    ## Guest posts
    
    - `[niche] "write for us"`
    - `[niche] "guest post guidelines"`
    - `[niche] "submit a guest post"`
    - `[niche] "become a contributor"`
    - `[niche] "contributor guidelines"`
    
    ## Unlinked mentions
    
    - `"[brand]" -site:[brand domain]`
    - `"[product name]" -site:[brand domain]`
    - `"[founder name]" "[brand]" -site:[brand domain]`
    - misspellings and spacing variants of the brand, each in quotes
    
    ## Listicles ("best X" inclusion)
    
    - `best [category] tools`
    - `best [category] software`
    - `top [category] tools [current year]`
    - `[competitor] alternatives`
    - `[competitor] vs`
    - `[competitor] competitors`
    - `intitle:"best" [category]`
    
    ## Moving Man
    
    - `[niche] "rebrands as"`
    - `[niche] "has been acquired"`
    - `[niche] "shutting down"`
    - `[niche] "sunsetting"`
    - `[niche] "discontinued"`
    - `[competitor or tool] "is now"`
    
    ## Results log
    
    Add lines here after runs: date, niche, footprint, outcome.
    - Product-review niche: health "useful links" / "resources" / `site:.edu` pages = dud (their dead links point at official bodies a review site cannot replace). `intitle:` and `inurl:` were ignored by the search tool; plain phrases did as well.
    
  • LICENSE1.0 KB1e780c107018upstream ↗
    MIT License
    
    Copyright (c) 2026 James Oliver
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • prompts.md1.8 KBc442e67f0d38upstream ↗
    # Starter prompts
    
    Copy one, swap in your own site and niche. Show these when the user asks what the skill can do.
    
    ## Not sure where to start
    
    - "Build links to mysite.com. It's a travel blog. What should I do first?"
    - "Look at mysite.com and tell me which link building tactic fits best."
    
    ## One per tactic
    
    | Tactic | Prompt |
    |---|---|
    | Link reclamation | "Find links mysite.com has lost or that point to pages that no longer work, and help me get them back." |
    | "Best X" listicles | "Find 'best [product type]' list articles that mention my competitors but not my product, mytool.com." |
    | Unlinked mentions | "Find pages that mention [brand name] but don't link to mysite.com." |
    | Broken link building | "Find broken link opportunities for mysite.com in the [niche] niche." |
    | Competitor dead pages | "Find dead pages on competitor.com that still have backlinks, that I could replace." |
    | Link gap | "Which sites link to competitor1.com and competitor2.com but not to mysite.com?" |
    | Resource pages | "Find resource pages in the [niche] niche that would list my guide at mysite.com/guide." |
    | Guest posts | "Find blogs in the [niche] niche that accept guest posts, and suggest topics I could pitch." |
    | Moving Man | "[Tool or site] shut down or rebranded. Find sites still linking to it so I can offer mysite.com instead." |
    | Skyscraper | "Find competitor.com's most linked articles and tell me which one I could beat." |
    
    ## Quick checks
    
    - "Check these URLs and tell me which are broken: [list]"
    - "Is olddomain.com expired or still registered?"
    - "Does this page link to mysite.com? [URL]"
    - "How many sites link to this page? [URL]" (a paid lookup, about $0.03; you'll be asked first)
    
    ## Picking up later
    
    - "Here's my tracker CSV. Which prospects are due a follow-up?"
    - "I sent these emails last week. Draft the follow-ups."
    
  • tactics/broken-link-building.md6.6 KBaf064b2dddf8upstream ↗
    # Broken link building
    
    Find dead links on relevant pages, then offer the site owner a working replacement from the user's site.
    
    Tools and verdicts are in [SKILL.md](../SKILL.md). Every threshold here is a starting value to tune.
    
    ## Step 1. Find prospect pages
    
    **Do:** search with the resource-page footprints in [footprints.md](../footprints.md), combined with the niche keywords. Start with about 10 queries; widen only if the first batch is thin. Collect the page URLs.
    
    **Pass when the page:**
    - links out to 10 or more external sites (resource lists, "best of" lists, guides);
    - is on topic for the user's niche;
    - is not the user's own site, a competitor, a forum thread, a directory that charges for listings, or a social profile.
    
    **Fail:** link farms (hundreds of unrelated links), pages with no visible owner or contact route, and pages where every outbound link is nofollow sponsored.
    
    **Record:** `prospect_page`, `prospect_domain`, `tactic = broken-link-building`, `status = found`.
    
    ## Step 2. Check outbound links
    
    **Do:** `blb.py outbound PAGE [PAGE ...] --out dead.csv`. It pulls every external link with its anchor text, checks it, and keeps everything that is not live. Domain-level failures (`dns_fail`, `parked`, `connection_refused`) get an RDAP lookup automatically.
    
    **Pass:** verdict `dead`.
    
    **Hold:** `recheck` rows. Re-run `blb.py check --file` on them a day later. A row still failing on a second run with `timeout` or `server_error` can be treated as dead; `blocked` stays recheck (it is usually bot protection, not a dead page).
    
    **Look by hand:** `review` rows (offsite redirects). Dead when the new site is unrelated; skip when the brand moved to a new domain.
    
    **Expired-domain branch:** when `domain_status` is `unregistered` or `expired`, mark the row priority. The whole site is gone, so every page linking to it is a prospect. Tell the user: a domain with strong referring domains may also be worth registering (that is their call, not part of this tactic).
    
    **Record:** `dead_url`, `dead_reason`, `anchor`, `domain_status`.
    
    ## Step 3. Judge the dead link's value
    
    **Do:** `blb.py refdomains --file dead.csv` first (prints the estimate). Show the estimate, wait for a yes, then re-run with `--yes --out refs.csv`.
    
    **Pass:** 3 or more referring domains (`ref_domains`) on the dead URL. A dead page that other sites linked to proves the content was wanted, and every one of those linking pages is an extra prospect for the same pitch.
    
    **Still allowed below the threshold:** a dead link on a strong, on-topic prospect page, when the user has an obvious replacement. Mark it `low_value` in notes.
    
    **Sort:** by `ref_domains`, highest first. Expired-domain rows go to the top.
    
    **Record:** `ref_domains`.
    
    ## Step 4. Match a replacement
    
    **Do:** `blb.py wayback DEAD_URL` for the last good snapshot, then open and read that snapshot. Note what the dead page covered: its topic, format and the key points the linking page relied on. Compare against the user's candidate pages.
    
    **Pass when a user page:**
    - covers the same topic and serves the same purpose for the reader (a guide replaces a guide, a tool replaces a tool);
    - is at least as complete as the dead page.
    
    **No match:** mark `needs_content` in notes and list the topic. When several high-value dead URLs share a topic, suggest the user writes one page that replaces them all. Never pitch a page that does not substitute for the dead one.
    
    **No Wayback copy:** judge from the anchor text and the linking page's context, and say so in notes.
    
    **Record:** `wayback_last_ok`, `wayback_snapshot`, `replacement_page`.
    
    ## Step 5. Find a contact
    
    **Do:** look on the prospect page for an author byline, then the site's contact, about and team pages.
    
    **Pass:** a named person's published email, or the site's contact form.
    
    **Fail:** no contact route found. Mark `no_contact` and stop for that row. Never guess an address pattern, never use a paid email finder.
    
    **Record:** `contact_name`, `contact_email_or_form`, `contact_source` (the page where it was found).
    
    ## Step 6. Draft the outreach
    
    **Do:** draft one email per prospect page (not per dead link; group a page's dead links in one email). Use the variant that fits. Fill every bracket from the row; never send a bracket.
    
    **Rules:**
    - under 120 words;
    - the broken link comes first, the user's page second;
    - name the exact page and the exact dead link so they can find it fast;
    - when the page has other dead links with no replacement from the user, list them too (it is a free favour and builds trust);
    - no em dashes or en dashes;
    - subject lines are plain, not clever.
    
    ### Variant A: the user has an existing page
    
    ```
    Subject: Broken link on your [topic] page
    
    Hi [first name],
    
    I was reading your [page title] page and noticed the link to [dead page name] ([dead URL]) no longer works. [It returns a 404. / The site has gone offline.]
    
    If you want a replacement, we have a [format] on [topic] that covers [the thing the dead page covered]: [replacement URL]
    
    [Also broken on the same page: [other dead URL].]
    
    Either way, thanks for keeping the list going.
    
    [Sender name]
    ```
    
    ### Variant B: the user wrote a new page to replace it
    
    ```
    Subject: [Dead page name] link on your [topic] page
    
    Hi [first name],
    
    Your [page title] page links to [dead page name] ([dead URL]), which has gone offline.
    
    It was a useful [format], so we put together an updated version covering [the main points]: [replacement URL]
    
    Happy for you to use it if it helps.
    
    [Sender name]
    ```
    
    ### Follow-up (once, about 7 days later, then stop)
    
    ```
    Subject: Re: [original subject]
    
    Hi [first name], just bumping this in case it got buried. The [dead page name] link on [page title] is still broken. No worries if you have already sorted it.
    
    [Sender name]
    ```
    
    **Record:** `status = drafted`. The user sends and then updates `status`, `first_sent` and `followed_up`. After the follow-up with no reply, set `no_reply`.
    
    ## Improving this tactic
    
    After each run, note what wasted time or produced replies (a footprint that only found link farms, a reason code that misfired, a subject line that got answers) and update this file or [footprints.md](../footprints.md). Keep the change small and say why in a one-line note at the bottom.
    
    ## Change log
    
    - First version.
    - DataForSEO cost corrected from real calls: about 2.4 cents per call plus 0.003 cents per URL.
    - For a product-review site, health and academic "useful links" pages mostly had dead links to official bodies a review site cannot replace. Consumer pages worked better (moving checklists, home and renovation resources, travel, student accommodation, nursery setup).
    - `outbound` gave false `dns_fail` under parallel load; fixed with a DNS retry (`dns_flaky`). Outlook safelinks are now unwrapped.
    
  • tactics/competitor-dead-pages.md2.6 KB1ec3f0046585upstream ↗
    # Competitor dead pages
    
    Find pages on competitor sites that are dead but still have backlinks, then pitch the user's page to every site linking to them. A broken link building variant that starts from the competitor, not the linking page.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md). Thresholds are starting values to tune.
    
    ## Step 1. Find the competitor's dead pages
    
    Two routes. Prefer the free one for a first look.
    
    **Free route (Wayback):**
    1. `blb.py history COMPETITOR.com/section --limit 2000 --out hist.csv`. Narrow big sites with a path (`/blog`, `/learn`, `/guides`); a whole big domain times out.
    2. `blb.py check --file hist.csv --out dead.csv` keeps the URLs that are not live today.
    3. `blb.py refdomains --file dead.csv` (paid but cheap: one call covers up to 1,000 URLs, about $0.03 to $0.05) to see which still have links.
    
    **Paid route (DataForSEO crawl):** `blb.py deadpages COMPETITOR.com --min-rd 3 --limit 100` (about $0.03 per competitor). Faster and ranked, but the crawl can be weeks old, so **always re-check the results** with `blb.py check` before going further.
    
    **Pass:** confirmed dead today and 3 or more referring domains.
    
    ## Step 2. Match a replacement
    
    As [broken-link-building.md](broken-link-building.md) step 4 (Wayback snapshot, same topic and purpose). A dead page with many referring domains and no match on the user's site is a content opportunity: mark `needs_content` and report it.
    
    ## Step 3. Get the linking pages
    
    **Do:** `blb.py backlinks DEAD_URL --limit 200` (paid, one call per dead page; only run it on matched pages). Keep `dofollow = True` rows from on-topic sites.
    
    **Then:** `blb.py haslink URL_FROM [...] --domain COMPETITOR.com` to confirm each page still links to the competitor today.
    
    ## Step 4. Contact and draft
    
    As [broken-link-building.md](broken-link-building.md) steps 5 and 6. Variant A or B fits as written: the linking page has a broken link to the competitor's dead page. Do not name or criticise the competitor beyond saying the page is gone.
    
    **Record:** `tactic = competitor-dead-pages`, `dead_url` = the competitor page.
    
    ## Change log
    
    - First real run: the free route checked about 130 old URLs (about 9 minutes; `check` paces one request per host every few seconds) and found a quarter dead, but exact-URL `refdomains` showed no links on almost all of them. The paid `deadpages` route (about 2.5 cents) found the linked dead pages the free route missed, because it catches http/www/slash variants and pages Wayback never saved. Start with the paid route for one competitor; use the free route only for path-level digging. Most linkers to dead pages were spam scrapers and forums: expect to keep about 1 in 8.
    
  • tactics/guest-posts.md2.1 KB21579cdc0796upstream ↗
    # Guest posts
    
    Write an article for another site in the niche, with a link back in the author bio or where it genuinely helps the reader.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md). Thresholds are starting values to tune.
    
    ## Step 1. Find sites
    
    **Do:** guest-post footprints in [footprints.md](../footprints.md) plus niche keywords. Link gap rows routed here are already qualified sites.
    
    ## Step 2. Qualify
    
    **Do:** `blb.py scan SITE_PAGE` (finds the write-for-us page, sponsored markers, CMS). Then `blb.py refdomains SITE_DOMAIN` for site strength (paid, cheap in bulk: batch every candidate domain in one call).
    
    **Pass when the site:**
    - publishes guidelines or a contribution page;
    - published posts by outside authors in the last 6 months;
    - is on topic for the user's audience;
    - has 50 or more referring domains;
    - does **not** tag guest posts as sponsored or charge for them. Paid links break Google's guidelines; flag any fee and leave the decision to the user.
    
    **Fail:** "write for us" pages on sites that publish anything (casino, CBD and loans next to the user's topic), sites where every post is a guest post.
    
    ## Step 3. Pitch ideas
    
    **Do:** read the guidelines and 5 recent posts. Propose 3 topics that the site has not covered, that their audience wants, and where the user has real expertise. Check each idea with a site search (`site:theirdomain.com topic`) to make sure it is not a duplicate.
    
    ## Step 4. Draft
    
    Follow their stated process exactly (form fields, word counts, subject line rules). When they ask for email:
    
    ```
    Subject: Guest post idea: [best title]
    
    Hi [first name],
    
    I read your guidelines and your recent post on [recent post topic]. Here are three ideas I think your readers would get a lot from:
    
    1. [Title]: [one line on the angle]
    2. [Title]: [one line on the angle]
    3. [Title]: [one line on the angle]
    
    A bit about me: [one line of real credentials]. Examples of my writing: [1 or 2 URLs].
    
    Happy to adjust any of these to fit your plans.
    
    [Sender name]
    ```
    
    **Record:** status moves to `pitched_topic`, then `accepted`, `written`, `published` in notes. Writing the post itself is a separate job (use your usual writing process).
    
  • tactics/link-gap.md2.5 KBe3be2f6e6a18upstream ↗
    # Link gap
    
    Find sites that link to several competitors but not to the user, work out why they link, and route each one to the tactic whose pitch fits.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md). Thresholds are starting values to tune.
    
    ## Step 1. Pick competitors
    
    **Do:** ask the user for 2 or 3 real competitors (same product category or same content topic). Never guess them.
    
    **Pass:** each competitor competes for the same audience. A giant generalist site (Wikipedia, Forbes) is not a competitor.
    
    ## Step 2. Pull the gap
    
    **Do:** `blb.py gap USER_DOMAIN COMP1 COMP2 [COMP3] --limit 200` (paid: show the estimate, wait for a yes, re-run with `--yes --out gap.csv`). It returns domains linking to **every** competitor listed and not to the user, highest rank first.
    
    **Tip:** with 3 competitors the list is short and strong. If it comes back under 20 rows, drop to the 2 strongest competitors.
    
    ## Step 3. Filter
    
    **Fail:** directories, spam (scraper or "stats" sites), forums, social sites, the competitors' own properties, and domains in a different language from the user's audience.
    
    **Pass:** real editorial sites on topic.
    
    ## Step 4. Find the linking page and route it
    
    **Do:** `blb.py backlinks COMP1 --limit 1000 --yes --out comp1-links.csv` (paid, one call per competitor) and join on `domain_from` to see which page on each gap domain links to the competitor. Read the page title and URL, open it when unsure.
    
    **Route by page type:**
    
    | The linking page is | Hand off to |
    |---|---|
    | a resource or links page | [resource-pages.md](resource-pages.md) step 3 |
    | a "best X" or "alternatives" list | [listicle-inclusion.md](listicle-inclusion.md) step 3 |
    | a guest post by the competitor | [guest-posts.md](guest-posts.md) step 2 |
    | an article citing a competitor's guide or data | [skyscraper.md](skyscraper.md) step 5 (only when the user has a better piece) |
    | a page where the competitor link is dead | [broken-link-building.md](broken-link-building.md) step 4 |
    | news, partner or paid placement | skip, note why |
    
    **Record:** one tracker row per gap page, `tactic = link-gap > [routed tactic]`.
    
    ## Change log
    
    - A gap against one niche competitor plus two big generalist publishers returned about 90 domains, almost all directories, scrapers and spam, and none usable. Generalists are ruled out in step 1 for this reason. Use niche-only competitors, and when the niche has fewer than two, use page-level backlinks to the competitor's matching page instead of a domain gap.
    
  • tactics/link-reclamation.md2.3 KB9c88c5d2ba6cupstream ↗
    # Link reclamation
    
    Recover links the user already earned: links pointing at pages that now 404, and links that were removed.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md).
    
    ## Step 1. Links to the user's broken pages (no outreach needed)
    
    **Do:** `blb.py backlinks USER_DOMAIN --broken --limit 1000` (paid). Then `blb.py check` on every distinct `url_to` to confirm it is still broken today (DataForSEO's crawl can be weeks old).
    
    **Fix on the user's site:** 301-redirect each confirmed dead target to the closest live page (same topic, not the homepage). List them for the user as `old URL -> new URL` pairs, sorted by how many domains link to the old URL. This needs no outreach and is the quickest win in the whole skill.
    
    ## Step 2. Lost links
    
    **Do:** `blb.py backlinks USER_DOMAIN --lost --limit 500` (paid), then `blb.py haslink URL_FROM [...] --domain USER_DOMAIN` to confirm the link is really gone today.
    
    **Pass for outreach when:**
    - the linking page is still live (`haslink` did not return a fetch error);
    - the page still covers the same topic (the link was edited out, not the page rewritten into something else);
    - the user's target page still exists and is still the best fit.
    
    **Skip:** pages that were deleted (nothing to restore), and links lost because the user's own page was removed (step 1 covers those).
    
    ## Step 3. Draft
    
    Under 80 words, no blame.
    
    ```
    Subject: Link on your [topic] page
    
    Hi [first name],
    
    Your [page title] page used to link to our [page name] ([URL]), and I noticed the link is no longer there. If it was removed by accident, would you consider adding it back? [If our page moved: it now lives at [new URL].]
    
    No worries if it was a deliberate change.
    
    [Sender name]
    ```
    
    One follow-up after about 7 days, then stop.
    
    ## Step 4. Wrong URL variants
    
    When `url_to` is an old slug or http version that redirects in a chain of 3 or more hops, or ends at the homepage, fix the redirect on the user's site first. Ask the linker to update the URL only when the redirect cannot be fixed.
    
    ## Change log
    
    - About a third of the "lost" editorial links in one run were still live, or pointed at an old domain that still 301s. Run `haslink` against the current domain and every old domain before calling a link lost. A linker's typo in the URL is a 301 on the user's side, not an email.
    
  • tactics/listicle-inclusion.md2.7 KB8150d3b00ebeupstream ↗
    # "Best X" listicle inclusion
    
    Get the user's product added to "best [category] tools" and "[competitor] alternatives" articles. For a product, these pages send buyers as well as links, so they come first for any SaaS.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md). Thresholds are starting values to tune.
    
    ## Step 1. Inputs
    
    Ask for: the product, 2 or 3 category phrases buyers use ("rank tracker", "brand mention tool"), 3 to 5 competitors, and the one concrete thing the product does better or differently. No differentiator, no pitch.
    
    ## Step 2. Find the lists
    
    **Do both:**
    - **Search:** listicle footprints in [footprints.md](../footprints.md) for each category phrase and each competitor ("best [category]", "[competitor] alternatives", "[competitor] vs").
    - **Competitor backlinks:** `blb.py backlinks COMPETITOR --limit 500 --title "best|top|alternative|vs|review" --out lists.csv` (paid). Lists that mention competitors almost always link to them.
    
    ## Step 3. Qualify
    
    **Do:** `blb.py haslink LIST_PAGE [...] --domain USER_DOMAIN --brand "PRODUCT"`, then read each page.
    
    **Pass when the list:**
    - names 2 or more of the user's competitors and does not include the user (`links_to_domain = no`, `mentions_brand = no`);
    - was published or updated in the last 2 years (lists get refreshed; a stale list still gets updated if the author is active);
    - is editorial: written by a person who reviews tools.
    
    **Flag, do not pitch:** lists run by a competitor (they will not add a rival), and lists that charge for inclusion or label entries as sponsored. Paid placement must be `rel="sponsored"` under Google's guidelines; that is the user's call.
    
    **Already listed** (`mentions_brand = yes` and `links_to_domain = no`): hand off to [unlinked-mentions.md](unlinked-mentions.md) step 5.
    
    ## Step 4. Find the author
    
    As [broken-link-building.md](broken-link-building.md) step 5. The byline author is the right contact here, not a general inbox.
    
    ## Step 5. Draft
    
    Under 120 words. Make it easy to say yes: offer access and a ready blurb.
    
    ```
    Subject: [Product] for your [list title]
    
    Hi [first name],
    
    I read your [list title] and liked how you [one specific thing about their review method]. I'd like to suggest [product] for the next update.
    
    What it does differently: [the one concrete differentiator].
    
    Happy to set you up with a free account so you can test it yourself: [link or "just reply"]. Here is a short description in case it helps:
    
    "[2 sentence blurb, plain and factual]"
    
    Thanks for considering it.
    
    [Sender name]
    ```
    
    **Rules:** never criticise the competitors on their list, never offer payment, no inflated claims. The blurb uses the brand's exact spelling. One follow-up after about 10 days (list updates are slower), then stop.
    
  • tactics/moving-man.md2.3 KB944c9c984065upstream ↗
    # Moving Man
    
    Find brands, tools and resources in the niche that rebranded, moved, or shut down, then reach the sites still linking to the old version.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md).
    
    ## Step 1. Find moved or closed resources
    
    **Do:**
    - news searches with the Moving Man footprints in [footprints.md](../footprints.md) ("rebrands as", "shutting down", "sunsetting", "has been acquired", "discontinued") plus niche keywords;
    - earlier `blb.py outbound` runs: `review` rows (`redirect_offsite`) and `redirect_home` rows are often moved or acquired resources.
    
    **Then:** `blb.py check --all OLD_URL [...]` shows where each old URL ends up today (`final_url`).
    
    **Classify:**
    
    | Outcome | Meaning | Pitch |
    |---|---|---|
    | dead (any dead reason) | closed | user's page as the replacement |
    | redirects to the new brand, same content | moved | "it moved to X"; offer the user's page only as an alternative |
    | redirects to an unrelated page or homepage | effectively gone | user's page as the replacement |
    
    ## Step 2. Get the sites still linking to the old version
    
    **Do:** `blb.py backlinks OLD_DOMAIN_OR_URL --limit 200` (paid). Then `blb.py haslink URL_FROM [...] --domain OLD_DOMAIN` to confirm the old link is still on the page.
    
    **Pass:** on-topic site, link still present, user has a page that fits.
    
    ## Step 3. Contact
    
    As [broken-link-building.md](broken-link-building.md) step 5.
    
    ## Step 4. Draft
    
    ```
    Subject: [Old name] link on your [topic] page
    
    Hi [first name],
    
    Your [page title] page links to [old name] ([old URL]). [It shut down in [month year]. / It now redirects to [where it goes].]
    
    If you are updating the page, we have a [format] that covers the same ground: [URL].
    
    Thanks for keeping the page useful.
    
    [Sender name]
    ```
    
    When the brand simply moved with the same content, say so honestly and offer the user's page as one option, not as the fix. One follow-up after about 7 days, then stop.
    
    ## Change log
    
    - Best source of dead brands was the user's own discontinued-product pages. About 95% of backlinks to dead brand domains were link-selling spam and domain-report scrapers, so pass `--title` or filter titles before reading. `check` now flags parked for-sale pages as `parked` and 200 OK shutdown pages as `closed_notice`. Confirm the replacement page is still live (a review can itself have been redirected).
    
  • tactics/resource-pages.md1.5 KB2732b84dd176upstream ↗
    # Resource pages
    
    Get the user's page added to curated resource and links pages in the niche.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md). Thresholds are starting values to tune.
    
    ## Step 1. Find resource pages
    
    **Do:** resource-page footprints in [footprints.md](../footprints.md) plus niche keywords.
    
    ## Step 2. Qualify
    
    **Do:** `blb.py scan PAGE [PAGE ...]` for contact routes, sponsored markers and the modified date. Read the page.
    
    **Pass when the page:**
    - actively lists external resources for readers (not a page of ads);
    - shows signs of upkeep: a modified date in the last 3 years, or its links mostly work;
    - has a section where one of the user's pages genuinely belongs;
    - has no "submit your link for a fee" or sponsored markers.
    
    ## Step 3. Check for dead links first
    
    **Do:** `blb.py outbound PAGE`. If it has dead links, switch to [broken-link-building.md](broken-link-building.md) step 3. A broken link pitch gets more replies than a plain inclusion request.
    
    ## Step 4. Contact
    
    As [broken-link-building.md](broken-link-building.md) step 5.
    
    ## Step 5. Draft
    
    Under 100 words. Name the exact section.
    
    ```
    Subject: Suggestion for your [topic] resources page
    
    Hi [first name],
    
    I came across your [page title] page while looking for [topic] resources. The [section name] section is a great list.
    
    We have a [format] on [topic] that might fit there: [URL]. It covers [one concrete thing their readers get].
    
    Thanks for putting the list together.
    
    [Sender name]
    ```
    
    One follow-up after about 7 days, then stop.
    
  • tactics/skyscraper.md2.5 KB59706af3e28fupstream ↗
    # Skyscraper
    
    Find a competitor's most-linked piece on a topic, make something clearly better, and pitch the sites that link to the original.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md). Thresholds are starting values to tune.
    
    ## Step 1. Find linkable pieces
    
    **Do:**
    - `blb.py toppages COMPETITOR --min-rd 20 --limit 50` (paid) for each competitor: their most-linked live pages;
    - or search the topic, take the top 10 results and run `blb.py refdomains URL [...]` on them in one batch (paid, cheap).
    
    **Pass:** 20 or more referring domains, on a topic the user's site can credibly own, and not a homepage, tool login or brand page (people link to those for the brand, not the content).
    
    ## Step 2. Work out why it gets links
    
    **Do:** read the piece. Name what the linking sites cite it for: original data or statistics, a definition, a tool or calculator, a template, a list of examples, a guide. Sample 10 linking pages from step 4 to confirm what they quote.
    
    ## Step 3. Decide whether the user can beat it
    
    **Pass only when the user can make it clearly better on what gets cited:**
    - **More current:** the original's data or examples are 2 or more years old;
    - **More complete:** it misses sections the linkers need;
    - **Original data:** the user can add data nobody else has;
    - **Easier to use:** a tool, template or visual where the original is text.
    
    **Fail:** "a bit longer" or "better designed" alone. If the user cannot beat it on the cited thing, stop and say why.
    
    **Output:** a brief for the new piece (angle, sections, the specific improvements, the stats to replace). Writing it is a separate job (use your usual writing process).
    
    ## Step 4. Get the linkers
    
    **Do (once the user's piece is live):** `blb.py backlinks ORIGINAL_URL --limit 300` (paid).
    
    **Pass:** `dofollow = True`, on-topic site, the link sits in the body of an article (not a sitewide list), and `haslink` confirms it is still there. Linkers quoting an outdated stat that the new piece updates go to the top.
    
    ## Step 5. Draft
    
    Under 120 words. Lead with what is new for **their** page, never ask them to remove the original.
    
    ```
    Subject: Updated [topic] [data/guide] for your [page title]
    
    Hi [first name],
    
    Your [page title] cites [original page name] for [what they cite]. That [data/guide] is from [year], so I thought you'd want to know we just published [new piece name] with [the specific improvement, e.g. 2026 figures from X sources]: [URL]
    
    If it is useful, it could make a good addition next time you update the page.
    
    [Sender name]
    ```
    
    One follow-up after about 7 days, then stop.
    
  • tactics/unlinked-mentions.md2.2 KB2fab6c9f848dupstream ↗
    # Unlinked brand mentions
    
    Find pages that already name the user's brand or product without linking, and ask for the link. The warmest tactic: the writer already chose to mention the brand.
    
    Tools, verdicts and house rules are in [SKILL.md](../SKILL.md).
    
    ## Step 1. Search for mentions
    
    **Do:** search each variant with the unlinked-mentions footprints in [footprints.md](../footprints.md): brand name, product names, founder name, and common misspellings and spacing variants (for example "Acme Tools" and "AcmeTools"). Exclude the user's own domain and social profiles.
    
    ## Step 2. Confirm unlinked
    
    **Do:** `blb.py haslink PAGE [PAGE ...] --domain USER_DOMAIN --brand "BRAND"`.
    
    **Pass:** `mentions_brand = yes` and `links_to_domain = no`.
    
    **Also worth a note:** `links_to_domain = yes` with `rel` containing nofollow is a link already. Leave it alone.
    
    ## Step 3. Filter
    
    **Fail:** negative reviews or complaints, scraped or spun copies, forum posts, pages older than about 3 years with no sign of updates (low reply rate), and the user's own guest posts.
    
    **Pass:** neutral or positive mentions on real sites.
    
    ## Step 4. Contact
    
    As [broken-link-building.md](broken-link-building.md) step 5. Prefer the author of the page; `blb.py scan PAGE` lists published emails, contact page and socials.
    
    ## Step 5. Draft
    
    Under 90 words, thank first, one ask.
    
    ```
    Subject: Thanks for mentioning [brand]
    
    Hi [first name],
    
    Thanks for including [brand] in [page title]. [One specific line about what they said.]
    
    Would you be open to linking the mention to [best page URL] so readers can find it? It is the page that covers [what the mention is about].
    
    Thanks again either way.
    
    [Sender name]
    ```
    
    Pick the page that matches the mention (a feature mention links to that feature's page, not the homepage). One follow-up after about 7 days, then stop.
    
    ## Change log
    
    - A brand made of common words found nothing in 9 searches: it was swamped by namesakes (organisations with similar names), and the search tool did not reliably honour exact quotes or `-site:`. Report such a result as inconclusive, not "none"; it needs a stronger search tool or a paid mentions source. Also search founder and author names and the brand plus product terms.
    
  • tracker-template.csv227 B1d1238f201c2upstream ↗
    tactic,prospect_page,prospect_domain,dead_url,dead_reason,anchor,domain_status,ref_domains,wayback_last_ok,wayback_snapshot,replacement_page,contact_name,contact_email_or_form,contact_source,status,first_sent,followed_up,notes
    

Plain-text copy, no login: /skill-bundles/jamesoliverseo-linkbuilding-skill.md

// REPO STATS

10 stars
0 open issues
Last commit: 19d ago