Ahrefs Content Gap Analysis

Discovers keywords competitors rank for that the target domain does not, revealing content opportunities. Uses runtime schema discovery to choose the best available Ahrefs tool.

References

@skills/seo/references/mcp-degradation.md @skills/seo/references/ahrefs-api-reference.md

Inputs

• domain: The bare target domain to analyze (e.g., example.com). Strip https://, http://, and trailing slashes.
• competitors (optional): Up to 3 competitor domains, space-separated (e.g., competitor1.com competitor2.com). If not provided, auto-detect using Ahrefs organic competitors tool.

MCP Check

Before proceeding, verify Ahrefs MCP is available:

1. Use ToolSearch with query +ahrefs
2. If tools are returned → Ahrefs MCP is available, proceed to Execution
3. If no tools returned → display the Ahrefs MCP error template from references/mcp-degradation.md and stop

Execution

Step 1 — Identify Competitors

If competitors parameter provided: use those domains directly.

If no competitors specified:

• Call mcp__claude_ai_ahrefs__site-explorer-organic-competitors with target: the bare domain
• Select top 3 competitors by common keyword overlap from the response

Step 2 — Runtime Schema Discovery for Content Gap Tool

IMPORTANT: The filter parameter for keywords-explorer-matching-terms that enables competitor-domain filtering is UNVERIFIED. Discover the schema at runtime:

1. Use ToolSearch to load mcp__claude_ai_ahrefs__keywords-explorer-matching-terms
2. Inspect the tool's parameter schema carefully
3. Decision:
   • If the tool has a competitor/domain filter parameter → proceed with Approach A (direct filter)
   • If the tool has no such filter → fall back to Approach B (cross-reference)

Document which approach was used in the output.

Step 3A — Direct Filter Approach (if schema supports it)

For each competitor domain identified:

• Call mcp__claude_ai_ahrefs__keywords-explorer-matching-terms with:
  • target: the competitor domain keyword or filter parameter (per discovered schema)
  • Apply any discovered competitor/domain filter to find keywords competitor ranks for
• Cross-reference against target domain's keywords to identify gaps

Step 3B — Cross-Reference Approach (fallback)

1. Call mcp__claude_ai_ahrefs__site-explorer-organic-keywords with target: the target domain → collect target's keyword set

2. For each of the 3 competitor domains:

   • Call mcp__claude_ai_ahrefs__site-explorer-organic-keywords with target: the competitor domain
   • Collect their keyword set

3. Find keywords in competitor sets NOT in target's keyword set → these are gaps

Step 4 — CRITICAL: Monetary Conversion

cpc is returned in CENTS. Divide by 100 before display. Format as USD per click: $X.XX.

Example: API returns cpc = 350 → display as $3.50/click

Step 5 — Prioritize Gaps

Sort content gap keywords by:

1. Volume descending (highest search demand first)
2. Filter out keywords with position >50 for the target domain (focus on true gaps)

Output Format

## Ahrefs Content Gap Analysis: example.com

**Method used:** [Approach A — direct filter] or [Approach B — cross-reference]
**Competitors analyzed:** competitor1.com, competitor2.com, competitor3.com

### Content Gap Opportunities

| Keyword | Volume | Difficulty | CPC | Competitor Ranking | Your Position |
|---------|--------|-----------|-----|-------------------|---------------|
| seo checklist | 8,100 | 42 | $3.20/click | competitor1.com #3 | Not ranking |
| on-page seo guide | 5,400 | 38 | $2.80/click | competitor2.com #5 | Not ranking |
| technical seo audit | 3,600 | 55 | $5.10/click | competitor1.com #2 | Not ranking |

### Summary
- **Total gap keywords found:** 340
- **High-opportunity gaps** (volume >1,000, difficulty <50): 45 keywords
- **Top content opportunity:** Create comprehensive "seo checklist" guide targeting
  the cluster around "seo checklist", "seo audit checklist", "on-page seo checklist"

Error — Ahrefs MCP Not Available

If MCP check fails, display the Ahrefs error template from references/mcp-degradation.md:

## Ahrefs MCP Not Available

The `/seo ahrefs content-gap` command requires the Ahrefs MCP, which is not
currently connected.

**What you can do:**
- Use `/seo audit <url>` for a full static SEO analysis without live Ahrefs data
- Use `/seo technical <url>` for technical SEO issues without backlink/keyword data

**To connect Ahrefs MCP:**
- Ensure the Ahrefs MCP is registered at user scope in ~/.claude/mcp.json
- Verify with: cat ~/.claude/mcp.json | grep -i ahrefs
- Ahrefs MCP must be registered at user scope (not project scope) to work in subagents