---
name: "SEO backlinks"
repo: https://github.com/agricidaniel/claude-seo
source: https://github.com/agricidaniel/claude-seo/blob/HEAD/skills/seo-backlinks/SKILL.md
license: "MIT"
install: "npx skills add agricidaniel/claude-seo --skill seo-backlinks"
page: https://100xlab.com/resources/agent-skills/agricidaniel-claude-seo--seo-backlinks--1rchuxq
---

# Backlink Profile Analysis

## Source Detection

Before analysis, detect available data sources:

1. **DataForSEO MCP** (premium): Check if `dataforseo_backlinks_summary` tool is available
2. **Moz API** (free signup): `python3 scripts/backlinks_auth.py --check moz --json`
3. **Bing Webmaster** (free signup): `python3 scripts/backlinks_auth.py --check bing --json`
4. **Common Crawl** (always available): Domain-level graph with PageRank
5. **Verification Crawler** (always available): Checks if known backlinks still exist

Run `python3 scripts/backlinks_auth.py --check --json` to detect all sources at once.

If no sources are configured beyond the always-available tier:
- Still produce a report using Common Crawl domain metrics
- Suggest: "Run `/seo backlinks setup` to add free Moz and Bing API keys for richer data"

## Quick Reference

| Command | Purpose |
|---------|---------|
| `/seo backlinks <url>` | Full backlink profile analysis (uses all available sources) |
| `/seo backlinks gap <url1> <url2>` | Competitor backlink gap analysis |
| `/seo backlinks toxic <url>` | Toxic link detection and disavow recommendations |
| `/seo backlinks new <url>` | New and lost backlinks (DataForSEO only) |
| `/seo backlinks verify <url> --links <file>` | Verify known backlinks still exist |
| `/seo backlinks setup` | Show setup instructions for free backlink APIs |

## Analysis Framework

Produce all 7 sections below. Each section lists data sources in preference order.

### 1. Profile Overview

**DataForSEO:** `dataforseo_backlinks_summary` → total backlinks, referring domains, domain rank, follow ratio, trend.

**Moz API:** `python3 scripts/moz_api.py metrics <url> --json` → Domain Authority, Page Authority, Spam Score, linking root domains, external links.

**Common Crawl:** `python3 scripts/commoncrawl_graph.py <domain> --json` → in-degree (referring domain count), PageRank, harmonic centrality.

**Scoring:**

| Metric | Good | Warning | Critical |
|--------|------|---------|----------|
| Referring domains | >100 | 20-100 | <20 |
| Follow ratio | >60% | 40-60% | <40% |
| Domain diversity | No single domain >5% | 1 domain >10% | 1 domain >25% |
| Trend | Growing or stable | Slow decline | Rapid decline (>20%/quarter) |

### 2. Anchor Text Distribution

**DataForSEO:** `dataforseo_backlinks_anchors`

**Moz API:** `python3 scripts/moz_api.py anchors <url> --json`

**Bing Webmaster:** `python3 scripts/bing_webmaster.py links <url> --json` (extract anchor text from link details)

**Healthy distribution benchmarks:**

| Anchor Type | Target Range | Over-Optimization Signal |
|-------------|-------------|-------------------------|
| Branded (company/domain name) | 30-50% | <15% |
| URL/naked link | 15-25% | N/A |
| Generic ("click here", "learn more") | 10-20% | N/A |
| Exact match keyword | 3-10% | >15% |
| Partial match keyword | 5-15% | >25% |
| Long-tail / natural | 5-15% | N/A |

Flag if exact-match anchors exceed 15% -- this is a Google Penguin risk signal.

### 3. Referring Domain Quality

**DataForSEO:** `dataforseo_backlinks_referring_domains`

**Moz API:** `python3 scripts/moz_api.py domains <url> --json` → domains with DA scores

**Common Crawl:** `python3 scripts/commoncrawl_graph.py <domain> --json` → top referring domains (domain-level, no authority scores)

Analyze:
- **TLD distribution**: .edu, .gov, .org = high authority. Excessive .xyz, .info = low quality
- **Country distribution**: Match target market. 80%+ from irrelevant countries = PBN signal
- **Domain rank distribution**: Healthy profiles have links from all authority tiers
- **Follow/nofollow per domain**: Sites that only nofollow = limited SEO value

### 4. Toxic Link Detection

**DataForSEO:** `dataforseo_backlinks_bulk_spam_score` + toxic patterns from reference

**Moz API:** Spam Score from `python3 scripts/moz_api.py metrics <url> --json` (1-17% scale, >11% = high risk)

**Verification Crawler:** `python3 scripts/verify_backlinks.py --target <url> --links <file> --json` (verify suspicious links still exist)

**High-risk indicators (flag immediately):**
- Links from known PBN (Private Blog Network) domains
- Unnatural anchor text patterns (100% exact match from a domain)
- Links from penalized or deindexed domains
- Mass directory submissions (50+ directory links)
- Link farms (sites with 10K+ outbound links per page)
- Paid link patterns (footer/sidebar links across all pages of a domain)

**Medium-risk indicators (review manually):**
- Links from unrelated niches
- Reciprocal link patterns
- Links from thin content pages (<100 words)
- Excessive links from a single domain (>50 backlinks from 1 domain)

Load `references/backlink-quality.md` for the full 30 toxic patterns and disavow criteria.

### 5. Top Pages by Backlinks

**DataForSEO:** `dataforseo_backlinks_backlinks` with target type "page"

**Moz API:** `python3 scripts/moz_api.py pages <domain> --json`

Find:
- Which pages attract the most backlinks
- Pages with high-authority links (link magnets)
- Pages with zero backlinks (internal linking opportunities)
- 404 pages with backlinks (redirect opportunities to reclaim link equity)

### 6. Competitor Gap Analysis

**DataForSEO:** `dataforseo_backlinks_referring_domains` for both domains, then compare

**Bing Webmaster (unique!):** `python3 scripts/bing_webmaster.py compare <url1> <url2> --json` — the only free tool with built-in competitor comparison

**Moz API:** Compare DA/PA between domains via `python3 scripts/moz_api.py metrics <url> --json` for each

Output:
- Domains linking to competitor but NOT to target = link building opportunities
- Domains linking to both = validate existing relationships
- Domains linking only to target = competitive advantage
- Top 20 link building opportunities with domain authority

### 7. New and Lost Backlinks

**DataForSEO only:** `dataforseo_backlinks_backlinks` with date filters for 30/60/90 day changes

**Verification Crawler:** For known links, verify current status with `python3 scripts/verify_backlinks.py`

**Note:** Free sources cannot track new/lost links over time. If this section is requested without DataForSEO, inform the user: "Link velocity tracking requires the DataForSEO extension. Free sources provide point-in-time snapshots only."

**Red flags:**
- Sudden spike in new links (possible negative SEO attack)
- Sudden loss of many links (site penalty or content removal)
- Declining velocity over 3+ months (content not attracting links)

## Backlink Health Score

Calculate a 0-100 score. When mixing sources, apply confidence weighting:

| Factor | Weight | Sources (preference order) | Confidence |
|--------|--------|---------------------------|------------|
| Referring domain count | 20% | DataForSEO > Moz > CC in-degree | 1.0 / 0.85 / 0.50 |
| Domain quality distribution | 20% | DataForSEO > Moz DA distribution | 1.0 / 0.85 |
| Anchor text naturalness | 15% | DataForSEO > Moz > Bing anchors | 1.0 / 0.85 / 0.70 |
| Toxic link ratio | 20% | DataForSEO > Moz spam score | 1.0 / 0.85 |
| Link velocity trend | 10% | DataForSEO only | 1.0 |
| Follow/nofollow ratio | 5% | DataForSEO > Bing details | 1.0 / 0.70 |
| Geographic relevance | 10% | DataForSEO > Bing country | 1.0 / 0.70 |

**Data sufficiency gate:** Count how many of the 7 factors have at least one data source available.
- **4+ factors with data:** Produce a numeric 0-100 score (redistribute missing weights proportionally)
- **Fewer than 4 factors:** Do NOT produce a numeric score. Instead display:
  ```
  Backlink Health Score: INSUFFICIENT DATA (X/7 factors scored)
  ```
  Show individual factor scores that ARE available with their source and confidence.
  Recommend: "Configure Moz API (free) for a scoreable profile. Run `/seo backlinks setup`"

When only CC is available, cap maximum score at 70/100.
A numeric score with fewer than 4 data sources is **misleading** — it implies poor health when
the reality is we simply lack data.

## Output Format

### Backlink Health Score: XX/100 (or INSUFFICIENT DATA)

| Section | Status | Score | Data Source |
|---------|--------|-------|-------------|
| Profile Overview | pass/warn/fail | XX/100 | Moz (0.85) |
| Anchor Distribution | pass/warn/fail | XX/100 | Moz (0.85) |
| Referring Domain Quality | pass/warn/fail | XX/100 | CC (0.50) |
| Toxic Links | pass/warn/fail | XX/100 | Moz Spam (0.85) |
| Top Pages | info | N/A | Moz (0.85) |
| Link Velocity | pass/warn/fail | XX/100 | DataForSEO only |

### Critical Issues (fix immediately)
### High Priority (fix within 1 month)
### Medium Priority (ongoing improvement)
### Link Building Opportunities (top 10)

## Error Handling

| Error | Cause | Resolution |
|-------|-------|-----------|
| No sources configured | No API keys, no DataForSEO | Run `/seo backlinks setup` |
| Moz rate limit | Free tier: 1 req/10s | Wait 10 seconds, retry. Built into script. |
| Bing site not verified | Site not verified in Bing | Verify at https://www.bing.com/webmasters |
| CC download timeout | Large graph file, slow connection | Use `--timeout 180` flag |
| DataForSEO unavailable | Extension not installed | Run `./extensions/dataforseo/install.sh` |
| No backlink data returned | Domain too new or very small | Note: small sites may have <10 backlinks |

**Fallback cascade:**
1. DataForSEO available? → Use as primary (confidence: 1.0)
2. Moz configured? → Use for DA/PA/spam/anchors (confidence: 0.85)
3. Bing configured? → Use for links/competitor comparison (confidence: 0.70)
4. Always: Common Crawl for domain-level metrics (confidence: 0.50)
5. Always: Verification crawler for known link checks (confidence: 0.95)
6. Nothing works? → "Run `/seo backlinks setup` to configure free APIs"

## Pre-Delivery Review (MANDATORY)

Before presenting any backlink analysis to the user, run this checklist internally.
Do NOT skip this step. Fix any issues found before showing the report.

### Fact-Check Every Claim
- [ ] **Schema claims**: Did parse_html return `@type` for each block? If any `@type` is missing,
      re-check — it may use `@graph` wrapper (valid JSON-LD, not malformed).
- [ ] **"link_removed" findings**: Is the page JS-rendered? If `unverifiable_js`, say so — never
      report a JS-rendered page as "link removed" (that's a false negative).
- [ ] **H1 findings**: Are any H1s in the `h1_suspicious` list? If so, note they are likely
      counters/stats, not semantic headings.
- [ ] **Reciprocal links**: If site A links to site B AND B links back to A, flag it as a
      reciprocal link pattern. Check outbound links against verified inbound sources.
- [ ] **Health score**: Are 4+ of 7 factors scored? If not, report INSUFFICIENT DATA — never
      show a misleading numeric score.

### Verify Data Source Labels
- [ ] Every metric in the report has a source label (e.g., "Parsed (0.95)", "CC (0.50)")
- [ ] Every "not found" result distinguishes between "not crawled" vs "below threshold" vs "error"
- [ ] Social media pages flagged as `unverifiable_js` (not `link_removed`)

### Cross-Check Consistency
- [ ] Platform detection matches actual signals (check for wp-content, shopify CDN, etc.)
- [ ] Referring domain count in summary matches the actual verified links list
- [ ] No claim is presented without a data source backing it

If ANY check fails, fix the finding before presenting. Never present inferred data as fact.

## Post-Analysis

After completing any backlink analysis command, always offer:
"Generate a professional PDF report? Use `/seo google report`"

## Reference Documentation

Load on demand (do NOT load at startup):
- `skills/seo/references/backlink-quality.md` -- Detailed toxic link patterns and scoring methodology (shared reference, load when analyzing toxic links or spam scores)
- `skills/seo/references/free-backlink-sources.md` -- Source comparison, confidence weighting, setup guides (shared reference, load when configuring free backlink APIs)

---

## Supporting file: LICENSE.txt

```text
MIT License - see repository root LICENSE file for complete terms.

Copyright (c) 2026 AgriciDaniel
https://github.com/AgriciDaniel/claude-seo
```

---

## Supporting file: skills/seo/references/backlink-quality.md

# Backlink Quality Scoring Methodology

## Toxic Link Indicators (30 Patterns)

### Definite Spam (auto-flag)
1. Link from domain with 10,000+ outbound links per page
2. Link from domain with no indexed pages in Google
3. Link from domain registered <30 days ago with 100+ outbound links
4. Exact-match anchor text from 5+ unrelated domains
5. Links from doorway pages (thin content, keyword-stuffed)
6. Links from hacked sites (pharma/casino injections)
7. Links from known link networks (check against known PBN lists)
8. Footer/sidebar site-wide links from unrelated domains
9. Links from auto-generated content (spun articles)
10. Links from domains with manual Google penalties

### Likely Spam (manual review)
11. Links from domains with >90% outbound link ratio
12. Foreign-language domains linking to English content (and vice versa)
13. Links from expired/auctioned domains repurposed for link building
14. Links from pages with >50 outbound links
15. Links from sites with no real traffic (parked domains)
16. Reciprocal link patterns across 10+ domains
17. Links from Web 2.0 properties with thin content
18. Links from article directories (EzineArticles, ArticleBase)
19. Links from low-quality guest post networks
20. Links from unrelated niches (e.g., pet site linking to SaaS)

### Potentially Problematic (monitor)
21. Links from social bookmarking sites at scale
22. Links from forum profiles (not discussions)
23. Links from press release syndication networks
24. Links from coupon/deal aggregators
25. Links from generic directories (not industry-specific)
26. Links with hidden/invisible anchor text
27. Links from pages with cloaked content
28. Links from sites with thin affiliate content
29. Links from comment sections without editorial context
30. Links from nofollow-only domains (limited SEO value)

## Anchor Text Ratio Benchmarks by Industry

| Industry | Branded | URL | Generic | Exact Match | Partial Match |
|----------|---------|-----|---------|-------------|---------------|
| SaaS | 40-55% | 15-20% | 10-15% | 3-8% | 10-15% |
| E-commerce | 35-45% | 15-25% | 10-15% | 5-10% | 10-20% |
| Local Service | 45-60% | 10-15% | 15-20% | 5-10% | 5-10% |
| Publisher/Blog | 30-40% | 20-30% | 10-15% | 3-8% | 10-20% |
| Agency | 40-50% | 15-20% | 10-15% | 5-10% | 10-15% |

## Link Velocity Red Flags

| Pattern | Signal | Action |
|---------|--------|--------|
| 10x normal new links in 1 week | Possible negative SEO | Investigate source, prepare disavow |
| 50%+ links lost in 1 month | Penalty or site issues | Check GSC for manual actions |
| Zero new links for 3+ months | Content not attracting links | Review content strategy |
| All new links from same TLD | Coordinated link building | Diversify sources |
| Spike from single country | Link network activity | Review geographic sources |

## Disavow Recommendations

**When to disavow:**
- Domain has received a manual penalty from Google
- Clear evidence of negative SEO attack
- Toxic link ratio exceeds 10% of total profile
- Specific domains identified as PBN or link farms

**When NOT to disavow:**
- Low-quality links that Google likely ignores anyway
- Nofollow links (already devalued by Google)
- Links from legitimate but low-authority sites
- Small number of spam links (<2% of profile)

**Disavow file format:**
```
# Toxic domains identified by Claude SEO backlink analysis
# Date: YYYY-MM-DD
# Total domains disavowed: X
domain:spamsite1.com
domain:linkfarm2.net
domain:pbn-network3.xyz
```

---

## Supporting file: skills/seo/references/free-backlink-sources.md

# Free Backlink Data Sources

Reference for the seo-backlinks skill. Loaded on demand when analyzing backlinks
with free sources.

## Source Comparison

| Source | Auth | Any Domain? | Data Quality | Coverage vs Commercial | Rate Limit |
|--------|------|-------------|-------------|----------------------|------------|
| **Moz API** | API key (free signup) | Yes | ★★★★☆ | ~70% for DA/PA | 1 req/10s, 2,500 rows/mo |
| **Bing Webmaster** | API key (free) | Verified sites only | ★★★☆☆ | ~15% (Bing index) | Generous |
| **Common Crawl** | None (public) | Yes | ★★★☆☆ | ~25-40% domains | N/A |
| **Verification Crawler** | None | Yes | ★★★★★ (binary) | N/A (checks known links) | 1 req/s per domain |
| **DataForSEO** (paid) | API key | Yes | ★★★★★ | ~90%+ | Per plan |

## Confidence Weighting

When merging data from multiple sources, apply confidence weights to each metric:

| Source | Weight | Rationale |
|--------|--------|-----------|
| DataForSEO | 1.00 | Commercial-grade, real-time, comprehensive |
| Verification Crawler | 0.95 | Direct observation (binary: link exists or not) |
| Moz API | 0.85 | Large index (45.5T links), established metrics, 3-day update lag |
| Bing Webmaster | 0.70 | Smaller index (~15% of web), but authoritative for Bing-indexed pages |
| Common Crawl | 0.50 | Domain-level only, quarterly updates, no anchor text |

**Composite formula:**
```
weighted_score = Σ(source_score × confidence × factor_weight) / Σ(confidence × factor_weight)
```

When only Common Crawl is available, cap the maximum health score at 70/100 and note
"limited to domain-level metrics" in the report.

## Source Details

### Moz API (Tier 1)
- **Endpoint:** `https://api.moz.com/jsonrpc` (JSON-RPC 2.0)
- **Free tier:** 2,500 rows/month, 1 request per 10 seconds (verify current limits at https://moz.com/products/api — free tier limits may change)
- **Signup:** https://moz.com/products/api (credit card required, not charged)
- **Data:** Domain Authority (0-100), Page Authority, Spam Score (1-17%), link counts,
  referring domains, anchor text distribution
- **Script:** `scripts/moz_api.py`
- **Commands:** `metrics`, `domains`, `anchors`, `pages`
- **Blind spots:** No link velocity, no toxic link patterns beyond Spam Score,
  3-day update lag, smaller index than Ahrefs/Semrush

### Bing Webmaster Tools (Tier 2)
- **Endpoint:** `https://ssl.bing.com/webmaster/api.svc/json/`
- **Free tier:** Unlimited for verified sites
- **Signup:** https://www.bing.com/webmasters (Microsoft account)
- **Unique feature:** Competitor backlink comparison (no other free tool offers this)
- **Data:** Inbound links with anchor text, source URL, discovery date
- **Script:** `scripts/bing_webmaster.py`
- **Commands:** `links`, `counts`, `compare`
- **Blind spots:** Only Bing-indexed pages (~15% of web), verified sites only,
  no authority metrics, no spam scoring

### Common Crawl Web Graph (Always Available)
- **Data source:** `s3://commoncrawl/projects/hyperlinkgraph/`
- **Releases:** Quarterly (e.g., cc-main-2025-18)
- **No auth needed:** Public data, free to download
- **Data:** Domain-level in-degree, PageRank, harmonic centrality, referring domains
- **Script:** `scripts/commoncrawl_graph.py`
- **Cache:** `~/.cache/claude-seo/commoncrawl/` (90-day TTL)
- **Blind spots:** No anchor text, no page-level data, monthly/quarterly freshness,
  domain-level only (e.g., "nytimes.com links to example.com" but not which page)

### Verification Crawler (Always Available)
- **No auth needed:** Uses existing fetch_page.py + parse_html.py
- **Data:** Binary verification (link exists/lost/moved), anchor text, rel attributes
- **Script:** `scripts/verify_backlinks.py`
- **Input:** JSON file with `[{"source_url": "..."}]` entries
- **Polite crawling:** 1-second delay between requests to same domain
- **Best for:** Checking if known backlinks still exist, monitoring link health

## When to Recommend DataForSEO Upgrade

Suggest the paid DataForSEO extension when:
- User needs **toxic link detection** beyond Moz's basic Spam Score
- User needs **competitor gap analysis** at scale (Bing only compares verified sites)
- User needs **link velocity trends** (new/lost links over time)
- User needs **real-time data** (free sources update monthly at best)
- User manages **multiple client sites** (free tier limits are per-account)
- User needs **disavow file generation** with confidence scoring

## Data Quality Reality Check

- Commercial tools index **35-45 trillion links** across 500M+ referring domains
- Free sources combined capture **20-40% of raw backlink data**
- But **60-70% of actionable intelligence** since highest-authority links appear in free samples
- For sites with <500 backlinks, free sources can capture **50%+ of the meaningful profile**
- **Referring domain count matters more than raw backlink count** for SEO
- Top 50-100 referring domains capture the majority of link authority

## Five Systematic Biases in Free Data

1. **Popularity bias:** Free tools crawl popular sites more, underrepresenting niche sites
2. **Truncation bias:** All free tools cap at 100-1,000 links, hiding the long tail
3. **Own-site restriction:** GSC and Ahrefs Webmaster Tools only work for verified properties
4. **Missing quality metrics:** Raw CC data lacks authority/toxicity scores
5. **Freshness lag:** Free sources update monthly at best vs. minutes for commercial