6# Backlink Audit Skill
7
8You 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.
9
10## Prerequisites
11
12This 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:
13
14```
15This skill requires a SemRush or Ahrefs API key. Set one via:
16 export SEMRUSH_API_KEY=your_key_here
17 export AHREFS_API_KEY=your_key_here
18Or add them to ~/.claude/.env.global
19```
20
21## SemRush Backlink API Endpoints
22
23Use curl via the Bash tool. Base URL: https://api.semrush.com/analytics/v1/
24
25### Core Endpoints
26
27**1. Backlinks Overview**
28```
29https://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
30```
31
32**2. Backlinks List (individual links)**
33```
34https://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
35```
36
37**3. Referring Domains**
38```
39https://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
40```
41
42**4. Anchor Text Distribution**
43```
44https://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
45```
46
47**5. Indexed Pages (pages receiving links)**
48```
49https://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
50```
51
52**6. Competitor Backlinks (for comparison)**
53```
54# Reuse endpoints above with competitor domain as target
55```
56
57**7. Referring Domain Authority Score**
58Domain Authority Score (domain_ascore) is returned with referring domains and ranges 0-100.
59
60## Alternative: Ahrefs API
61
62If AHREFS_API_KEY is available (and SemRush is not), use the Ahrefs API v3 endpoints below. All endpoints require the Bearer token header.
63
64### Ahrefs Core Endpoints
65
66**1. Backlinks Overview (Stats)**
67```bash
68# Ahrefs backlinks overview
69curl -s "https://api.ahrefs.com/v3/site-explorer/backlinks-stats?target={domain}&output=json" \
70 -H "Authorization: Bearer ${AHREFS_API_KEY}"
71```
72Returns: live_backlinks, all_time_backlinks, live_refdomains, all_time_refdomains, live_refpages, dofollow_backlinks, nofollow_backlinks.
73
74**2. Referring Domains**
75```bash
76# Ahrefs referring domains
77curl -s "https://api.ahrefs.com/v3/site-explorer/refdomains?target={domain}&output=json&limit=100" \
78 -H "Authorization: Bearer ${AHREFS_API_KEY}"
79```
80Returns: 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.
81
82**3. Backlinks List**
83```bash
84curl -s "https://api.ahrefs.com/v3/site-explorer/backlinks?target={domain}&output=json&limit=100&mode=subdomains" \
85 -H "Authorization: Bearer ${AHREFS_API_KEY}"
86```
87Returns: Individual backlinks with url_from, url_to, anchor, domain_rating, first_seen, last_seen, nofollow, redirect, edu, gov.
88
89**4. Anchors**
90```bash
91curl -s "https://api.ahrefs.com/v3/site-explorer/anchors?target={domain}&output=json&limit=50&mode=subdomains" \
92 -H "Authorization: Bearer ${AHREFS_API_KEY}"
93```
94Returns: Anchor text distribution with anchor, backlinks, refdomains.
95
96**5. Pages by Backlinks (Best by Links)**
97```bash
98curl -s "https://api.ahrefs.com/v3/site-explorer/best-by-links?target={domain}&output=json&limit=50" \
99 -H "Authorization: Bearer ${AHREFS_API_KEY}"
100```
101Returns: Top linked pages with url, backlinks, refdomains, dofollow.
102
103**6. Domain Rating**
104```bash
105curl -s "https://api.ahrefs.com/v3/site-explorer/domain-rating?target={domain}&output=json" \
106 -H "Authorization: Bearer ${AHREFS_API_KEY}"
107```
108Returns: domain_rating (0-100) and ahrefs_rank.
109
110### Ahrefs vs. SemRush Field Mapping
111
112When using Ahrefs instead of SemRush, map the fields as follows:
113| SemRush Field | Ahrefs Equivalent | Notes |
114|---------------|-------------------|-------|
115| domain_ascore | domain_rating | Both are 0-100 authority scores |
116| total (backlinks) | live_backlinks | Ahrefs separates live vs. all-time |
117| domains_num | live_refdomains | Referring domains count |
118| follows_num | dofollow_backlinks | Dofollow link count |
119| nofollows_num | nofollow_backlinks | Nofollow link count |
120| first_seen / last_seen | first_seen / last_seen | Same concept, both available |
121
122The audit process (Steps 1-7 below) works identically regardless of which API you use. Simply substitute the corresponding endpoints and field names.
123
124## Audit Process
125
126### Step 1: Pull Backlink Overview
127
128Fetch the backlink overview and summarize:
129
130```markdown
131## Backlink Profile Summary: {domain}
132
133| Metric | Value |
134|--------|-------|
135| Total Backlinks | {total} |
136| Referring Domains | {domains_num} |
137| Referring IPs | {ips_num} |
138| Referring Subnets (Class C) | {ipclassc_num} |
139| Follow Links | {follows_num} ({%}) |
140| Nofollow Links | {nofollows_num} ({%}) |
141| Text Links | {texts_num} ({%}) |
142| Image Links | {images_num} ({%}) |
143| Backlink-to-Domain Ratio | {total/domains_num} |
144```
145
146### Step 2: Analyze Referring Domains
147
148Pull the top referring domains sorted by authority score. Evaluate:
149
150**Domain Quality Tiers:**
151
152| Tier | Authority Score | Quality | Action |
153|------|----------------|---------|--------|
154| Tier 1 | 80-100 | Excellent | Protect and nurture |
155| Tier 2 | 60-79 | Good | Maintain relationship |
156| Tier 3 | 40-59 | Average | Monitor |
157| Tier 4 | 20-39 | Low quality | Review for relevance |
158| Tier 5 | 0-19 | Suspicious | Investigate for toxicity |
159
160**Domain Quality Distribution:**
161Calculate the percentage of referring domains in each tier. A healthy profile should have:
162- Tier 1-2: at least 10-15% of referring domains
163- Tier 3: 30-40%
164- Tier 4: 20-30%
165- Tier 5: < 20% (flag if higher)
166
167**Diversity Analysis:**
168- Unique IPs vs. referring domains (ratio close to 1:1 is healthy)
169- Unique Class C subnets (should be close to IP count)
170- Country distribution (should match target market)
171- TLD distribution (.com, .org, .edu, .gov diversity is positive)
172
173### Step 3: Analyze Anchor Text Distribution
174
175Pull anchor text data and classify each anchor:
176
177| Anchor Type | Healthy Range | Description | Example |
178|------------|---------------|-------------|---------|
179| Branded | 30-50% | Brand name or domain | "Acme Corp", "acme.com" |
180| Naked URL | 10-20% | Raw URL | "https://acme.com/product" |
181| Generic | 10-15% | Non-descriptive text | "click here", "read more", "this website" |
182| Topic/Keyword | 10-20% | Natural topic reference | "project management software" |
183| Exact Match | 1-5% | Exact target keyword | "best project management tool" |
184| Partial Match | 5-10% | Includes target keyword variation | "top tools for project management" |
185| Compound | 5-10% | Brand + keyword | "Acme project management" |
186| Image (no alt) | < 5% | Images without alt text | [image] |
187
188**Red flags in anchor text:**
189- Exact match > 10% = Over-optimized (Penguin risk)
190- Single anchor > 15% of total = Unnatural concentration
191- Money keyword anchors from low-quality sites = Likely spam
192- Irrelevant anchors (casino, pharma, adult) = Toxic links
193- Foreign language anchors unrelated to business = Likely spam
194
195### Step 4: Identify Toxic Links
196
197Score each backlink for toxicity based on these signals:
198
199**Toxicity Signals (each adds to a toxicity score 0-100):**
200
201| Signal | Weight | Detection Method |
202|--------|--------|-----------------|
203| Source domain AS < 10 | +15 | From referring domains data |
204| Source is known link farm/PBN pattern | +30 | Domain name patterns: keyword-keyword-keyword.com, random strings |
205| Anchor text is exact match keyword | +10 | From anchor text analysis |
206| Source page has 100+ external links | +20 | From external_num column |
207| Source is irrelevant niche | +15 | Compare source domain topic to target |
208| Source has no organic traffic | +15 | Check via domain_organic if budget allows |
209| Link from sitewide (footer/sidebar) | +10 | Same domain, many links to same target |
210| Link from non-indexed page | +20 | Page not in Google (manual check) |
211| Redirect chain to target | +10 | From redirect column |
212| Foreign language + irrelevant | +15 | From anchor text + domain TLD |
213
214**Toxicity Rating:**
215- 0-20: Clean - no action needed
216- 21-40: Monitor - watch for changes
217- 41-60: Suspicious - investigate further
218- 61-80: Likely toxic - consider disavow
219- 81-100: Toxic - add to disavow list
220
221### Step 5: Link Velocity Analysis
222
223Analyze the first_seen and last_seen dates to determine:
224
225- **Monthly new links** over the past 12 months
226- **Monthly lost links** (links where last_seen is in the past)
227- **Net link growth rate**
228- **Velocity spikes** (unnatural bursts of links)
229
230**Healthy velocity patterns:**
231- Steady, gradual growth = Natural
232- Correlated with content publishing = Natural
233- Sudden spike then flat = Likely campaign or mention (investigate)
234- Massive spike from low-quality domains = Negative SEO attack (flag immediately)
235- Declining trend = Losing links, need outreach
236
237### Step 6: Competitor Comparison
238
239Pull backlink overview for 2-3 competitors and compare:
240
241```markdown
242## Competitor Backlink Comparison
243
244| Metric | {Your Domain} | {Competitor 1} | {Competitor 2} | {Competitor 3} |
245|--------|--------------|----------------|----------------|----------------|
246| Total Backlinks | | | | |
247| Referring Domains | | | | |
248| Avg. Domain AS | | | | |
249| Follow % | | | | |
250| Link Growth (6mo) | | | | |
251```
252
253**Link Gap Analysis:**
254Find domains that link to competitors but not to the target:
2551. Pull top 100 referring domains for each competitor
2562. Filter out domains already linking to the target
2573. Sort by authority score
2584. These are outreach targets
259
260### Step 7: Generate Disavow File
261
262If toxic links are found, generate a Google Disavow file:
263
264```
265# Disavow file for {domain}
266# Generated: {date}
267# Total entries: {count}
268
269# Individual URLs (confirmed toxic)
270{url1}
271{url2}
272
273# Full domains (majority of links from domain are toxic)
274domain:{domain1}
275domain:{domain2}
276```
277
278**Disavow rules:**
279- Only disavow domains where 80%+ of their links are toxic
280- For mixed domains, disavow individual URLs
281- Never disavow high-authority domains (AS > 60) without manual verification
282- Always recommend the user review the list before submitting
283
284## Output Report Format
285
286```markdown
287# Backlink Audit Report: {domain}
288**Date:** {date}
289**Total Backlinks:** {total}
290**Referring Domains:** {count}
291**Health Score:** {score}/100
292
293## Executive Summary
294{2-3 sentences summarizing the health of the backlink profile}
295
296## Profile Overview
297{Overview table from Step 1}
298
299## Referring Domain Quality
300
301### Distribution by Authority
302| Tier | Range | Count | Percentage | Status |
303|------|-------|-------|-----------|--------|
304| Tier 1 | 80-100 | {} | {}% | {Good/Needs more} |
305| ... | ... | ... | ... | ... |
306
307### Top 20 Referring Domains
308| Domain | Authority | Backlinks | First Seen | Status |
309|--------|----------|-----------|-----------|--------|
310| {} | {} | {} | {} | {} |
311
312## Anchor Text Analysis
313
314### Distribution
315| Type | Percentage | Status |
316|------|-----------|--------|
317| Branded | {}% | {Healthy/Over/Under} |
318| ... | ... | ... |
319
320### Top 20 Anchors
321| Anchor | Domains | Backlinks | Type |
322|--------|---------|-----------|------|
323| {} | {} | {} | {} |
324
325## Toxic Link Analysis
326
327### Summary
328- **Total toxic links found:** {count}
329- **Toxic referring domains:** {count}
330- **Recommended for disavow:** {count}
331
332### Toxic Links Detail
333| Source URL | Anchor | Toxicity Score | Signals |
334|-----------|--------|---------------|---------|
335| {} | {} | {}/100 | {} |
336
337## Link Velocity
338{Monthly new/lost links chart description}
339{Assessment of velocity health}
340
341## Competitor Comparison
342{Comparison table}
343
344## Link Building Opportunities
345
346### Domains Linking to Competitors (Not You)
347| Domain | Authority | Links to Competitors | Outreach Strategy |
348|--------|----------|---------------------|-------------------|
349| {} | {} | {} | {} |
350
351### Recommended Link Building Tactics
3521. **{Tactic}** - {Description, estimated effort, expected results}
3532. ...
354
355## Action Items
356
357### Immediate (This Week)
3581. {Specific action}
359
360### Short Term (This Month)
3611. {Specific action}
362
363### Ongoing
3641. {Specific action}
365
366## Disavow File
367{If applicable, include the generated disavow file content}
368```
369
370## Notes
371
372- SemRush API has rate limits. Space out calls if making many requests.
373- Backlink data may be up to 30 days old. Note this in the report.
374- Never recommend disavowing links from legitimately authoritative domains.
375- For new sites (< 6 months), a small backlink profile is normal, not a problem.
376- Always recommend manual review of the disavow list before submission to Google Search Console.
377- If the user has Google Search Console access, recommend cross-referencing with GSC's link report for the most complete picture.
378