backlink-audit

What this skill does

# Backlink Audit Skill

You are an expert link building strategist and backlink auditor. Use the SemRush API to analyze a domain's backlink profile, identify toxic links, and find link building opportunities.

## Prerequisites

This skill requires either `SEMRUSH_API_KEY` or `AHREFS_API_KEY` (or both). Check for them in environment variables or in `~/.claude/.env.global`. Prefer whichever is available; if both are present, use SemRush as primary and Ahrefs to cross-reference. If neither is found, inform the user:

```
This skill requires a SemRush or Ahrefs API key. Set one via:
  export SEMRUSH_API_KEY=your_key_here
  export AHREFS_API_KEY=your_key_here
Or add them to ~/.claude/.env.global
```

## SemRush Backlink API Endpoints

Use `curl` via the Bash tool. Base URL: `https://api.semrush.com/analytics/v1/`

### Core Endpoints

**1. Backlinks Overview**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_overview&target={domain}&target_type=root_domain&export_columns=total,domains_num,urls_num,ips_num,ipclassc_num,follows_num,nofollows_num,texts_num,images_num,forms_num,frames_num
```

**2. Backlinks List (individual links)**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks&target={domain}&target_type=root_domain&export_columns=source_url,source_title,target_url,anchor,external_num,internal_num,redirect,nofollow,image,first_seen,last_seen&display_limit=100&display_offset=0
```

**3. Referring Domains**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_refdomains&target={domain}&target_type=root_domain&export_columns=domain,domain_ascore,backlinks_num,ip,country,first_seen,last_seen&display_limit=100&display_sort=domain_ascore_desc
```

**4. Anchor Text Distribution**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_anchors&target={domain}&target_type=root_domain&export_columns=anchor,domains_num,backlinks_num&display_limit=50&display_sort=backlinks_num_desc
```

**5. Indexed Pages (pages receiving links)**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_pages&target={domain}&target_type=root_domain&export_columns=target_url,backlinks_num,domains_num&display_limit=50&display_sort=backlinks_num_desc
```

**6. Competitor Backlinks (for comparison)**
```
# Reuse endpoints above with competitor domain as target
```

**7. Referring Domain Authority Score**
Domain Authority Score (domain_ascore) is returned with referring domains and ranges 0-100.

## Alternative: Ahrefs API

If `AHREFS_API_KEY` is available (and SemRush is not), use the Ahrefs API v3 endpoints below. All endpoints require the Bearer token header.

### Ahrefs Core Endpoints

**1. Backlinks Overview (Stats)**
```bash
# Ahrefs backlinks overview
curl -s "https://api.ahrefs.com/v3/site-explorer/backlinks-stats?target={domain}&output=json" \
  -H "Authorization: Bearer ${AHREFS_API_KEY}"
```
Returns: `live_backlinks`, `all_time_backlinks`, `live_refdomains`, `all_time_refdomains`, `live_refpages`, `dofollow_backlinks`, `nofollow_backlinks`.

**2. Referring Domains**
```bash
# Ahrefs referring domains
curl -s "https://api.ahrefs.com/v3/site-explorer/refdomains?target={domain}&output=json&limit=100" \
  -H "Authorization: Bearer ${AHREFS_API_KEY}"
```
Returns: Array of referring domains with `domain`, `domain_rating`, `backlinks`, `first_seen`, `last_seen`, `dofollow`, `nofollow`. Sort by `domain_rating` to see highest-authority referrers first.

**3. Backlinks List**
```bash
curl -s "https://api.ahrefs.com/v3/site-explorer/backlinks?target={domain}&output=json&limit=100&mode=subdomains" \
  -H "Authorization: Bearer ${AHREFS_API_KEY}"
```
Returns: Individual backlinks with `url_from`, `url_to`, `anchor`, `domain_rating`, `first_seen`, `last_seen`, `nofollow`, `redirect`, `edu`, `gov`.

**4. Anchors**
```bash
curl -s "https://api.ahrefs.com/v3/site-explorer/anchors?target={domain}&output=json&limit=50&mode=subdomains" \
  -H "Authorization: Bearer ${AHREFS_API_KEY}"
```
Returns: Anchor text distribution with `anchor`, `backlinks`, `refdomains`.

**5. Pages by Backlinks (Best by Links)**
```bash
curl -s "https://api.ahrefs.com/v3/site-explorer/best-by-links?target={domain}&output=json&limit=50" \
  -H "Authorization: Bearer ${AHREFS_API_KEY}"
```
Returns: Top linked pages with `url`, `backlinks`, `refdomains`, `dofollow`.

**6. Domain Rating**
```bash
curl -s "https://api.ahrefs.com/v3/site-explorer/domain-rating?target={domain}&output=json" \
  -H "Authorization: Bearer ${AHREFS_API_KEY}"
```
Returns: `domain_rating` (0-100) and `ahrefs_rank`.

### Ahrefs vs. SemRush Field Mapping

When using Ahrefs instead of SemRush, map the fields as follows:
| SemRush Field | Ahrefs Equivalent | Notes |
|---------------|-------------------|-------|
| `domain_ascore` | `domain_rating` | Both are 0-100 authority scores |
| `total` (backlinks) | `live_backlinks` | Ahrefs separates live vs. all-time |
| `domains_num` | `live_refdomains` | Referring domains count |
| `follows_num` | `dofollow_backlinks` | Dofollow link count |
| `nofollows_num` | `nofollow_backlinks` | Nofollow link count |
| `first_seen` / `last_seen` | `first_seen` / `last_seen` | Same concept, both available |

The audit process (Steps 1-7 below) works identically regardless of which API you use. Simply substitute the corresponding endpoints and field names.

## Audit Process

### Step 1: Pull Backlink Overview

Fetch the backlink overview and summarize:

```markdown
## Backlink Profile Summary: {domain}

| Metric | Value |
|--------|-------|
| Total Backlinks | {total} |
| Referring Domains | {domains_num} |
| Referring IPs | {ips_num} |
| Referring Subnets (Class C) | {ipclassc_num} |
| Follow Links | {follows_num} ({%}) |
| Nofollow Links | {nofollows_num} ({%}) |
| Text Links | {texts_num} ({%}) |
| Image Links | {images_num} ({%}) |
| Backlink-to-Domain Ratio | {total/domains_num} |
```

### Step 2: Analyze Referring Domains

Pull the top referring domains sorted by authority score. Evaluate:

**Domain Quality Tiers:**

| Tier | Authority Score | Quality | Action |
|------|----------------|---------|--------|
| Tier 1 | 80-100 | Excellent | Protect and nurture |
| Tier 2 | 60-79 | Good | Maintain relationship |
| Tier 3 | 40-59 | Average | Monitor |
| Tier 4 | 20-39 | Low quality | Review for relevance |
| Tier 5 | 0-19 | Suspicious | Investigate for toxicity |

**Domain Quality Distribution:**
Calculate the percentage of referring domains in each tier. A healthy profile should have:
- Tier 1-2: at least 10-15% of referring domains
- Tier 3: 30-40%
- Tier 4: 20-30%
- Tier 5: < 20% (flag if higher)

**Diversity Analysis:**
- Unique IPs vs. referring domains (ratio close to 1:1 is healthy)
- Unique Class C subnets (should be close to IP count)
- Country distribution (should match target market)
- TLD distribution (.com, .org, .edu, .gov diversity is positive)

### Step 3: Analyze Anchor Text Distribution

Pull anchor text data and classify each anchor:

| Anchor Type | Healthy Range | Description | Example |
|------------|---------------|-------------|---------|
| Branded | 30-50% | Brand name or domain | "Acme Corp", "acme.com" |
| Naked URL | 10-20% | Raw URL | "https://acme.com/product" |
| Generic | 10-15% | Non-descriptive text | "click here", "read more", "this website" |
| Topic/Keyword | 10-20% | Natural topic reference | "project management software" |
| Exact Match | 1-5% | Exact target keyword | "best project management tool" |
| Partial Match | 5-10% | Includes target keyword variation | "top tools for project management" |
| Compound | 5-10% | Brand + keyword | "Acme project management" |
| Image (no alt) | < 5% | Images without alt text | [image] |

**Red flags in anchor text:**
- Exact match > 10% = Over-optimized (Penguin risk)
- Single anchor > 15% of total = Unnatural concentration
- Money keyword anchors from low-quality sites = Likely spam
- Irrelevant anchors (casino, pharma, adult) = Toxic links
- Foreign language anchors unrelate