---
name: research
description: Research a keyword using Ahrefs - find related keywords and analyze top-ranking content
argument-hint: "[keyword]"
---

# Research Skill

Gather keyword intelligence and analyze top-ranking content for a target keyword using Ahrefs MCP.

## Input

**Option A: User provides keyword directly**
If `$ARGUMENTS` contains a keyword, use that keyword and skip to the Workflow section.

**Option B: Select from keyword-ideas.csv**
If `$ARGUMENTS` is empty or user wants to pick from the pipeline:

1. **Read `keyword-ideas.csv`** and filter to show available keywords:
   - Exclude rows where `selected` column = "yes"
   - Sort by `business_potential` (desc), then `priority` (high > medium > low), then `traffic_potential` (desc)

2. **Present top 10 available keywords:**

   ```
   ## Available Keywords (from keyword-ideas.csv)

   | # | Keyword | Volume | TP | KD | Priority | BP | Product |
   |---|---------|--------|-----|-----|----------|-----|---------|
   | 1 | [keyword] | [vol] | [tp] | [kd] | [priority] | [bp] | [product] |
   ```

   **Column key:** TP = Traffic Potential, KD = Keyword Difficulty, BP = Business Potential (0-3)

3. **Wait for user selection.**

4. **When user selects a keyword from the list:**
   - Use that keyword for research
   - **Mark it as selected** by updating the `selected` column to "yes" in `keyword-ideas.csv`

---

## Workflow

### Step 1: Get Primary Keyword Metrics & Parent Topic

Call `mcp__ahrefs__keywords-explorer-overview` with:
- `keywords`: Target keyword
- `country`: "us"
- `select`: "keyword,volume,difficulty,traffic_potential,cpc,parent_topic"

**Extract:**
- Primary keyword volume and difficulty
- **Parent topic** - Critical for identifying which keywords can be targeted together

---

### Step 2: Find Long-Tail Variations (Same Parent Topic)

Call `mcp__ahrefs__keywords-explorer-matching-terms` with:
- `keywords`: Target keyword
- `country`: "us"
- `select`: "keyword,volume,difficulty,traffic_potential,parent_topic"
- `order_by`: "volume:desc"
- `limit`: 50
- `where`:
```json
{"and": [
  {"field": "volume", "is": ["gte", 50]},
  {"field": "word_count", "is": ["gte", 3]}
]}
```

**Filter results to keep only keywords where:**
- `parent_topic` matches the target keyword's parent topic, OR
- `parent_topic` equals the target keyword itself

**Organize into:**
- **Primary keyword** - The main target
- **Secondary keywords** - Long-tail variations with same parent topic
- **Separate article candidates** - Keywords with different parent topics

---

### Step 3: Pull Questions Report

Call `mcp__ahrefs__keywords-explorer-matching-terms` with:
- `keywords`: Target keyword
- `country`: "us"
- `select`: "keyword,volume,difficulty,parent_topic"
- `order_by`: "volume:desc"
- `limit`: 30
- `terms`: "questions"

**Organize questions into:**
1. **High-priority questions (volume 100+)** - Address directly in article
2. **Supporting questions (volume 50-99)** - Good for FAQ sections
3. **Question themes** - Group by "What is...", "How to...", "Why...", "Best..."

---

### Step 4: Get SERP Overview

Call `mcp__ahrefs__serp-overview` with:
- `keyword`: Target keyword
- `country`: "us"
- `select`: "position,url,title,domain_rating,traffic,refdomains,type"
- `top_positions`: 10

---

### Step 5: Analyze Search Intent & Content Format

Based on the top 10 SERP results, determine:

1. **Primary Intent** - Informational / Commercial Investigation / Transactional / Navigational
2. **Dominant Content Format** - Comprehensive Guide / Listicle / How-To / Tool / Comparison / Definition
3. **Content Depth Signals** - Average word count, tools ranking, Reddit/forum results

---

### Step 6: Analyze Top 3 Ranking Pages

For each URL, use WebFetch to extract H2 and H3 headers in order, approximate word count, and special elements.

**After analyzing all 3, identify patterns:**
- Headers/topics covered by all 3 (must include)
- Headers/topics covered by 2/3 (should include)
- Unique headers (potential differentiators)

---

### Step 7: Identify Content Gaps and Opportunities

**A. Header/Topic Gap Analysis** - Create comparison matrix
**B. Questions Gap Analysis** - Cross-reference questions against competitor content
**C. Identify Opportunities** - Missing topics, underserved questions, depth gaps, freshness gaps, format gaps
**D. Determine Angle** - Based on gaps, decide how to differentiate

---

## Output

Save to `./1-research/[keyword-slug].md` with sections for:
- Keyword Targeting (primary + secondary keywords)
- Questions Report
- SERP Analysis (top 10 results + search intent analysis)
- Top 3 Content Analysis (header structures)
- Common Patterns
- Content Gaps & Opportunities
- Recommended Approach

---

## Common MCP Parameters

**Date format:** `"2026-02-17"` (YYYY-MM-DD)
**Country codes:** `"us"`, `"gb"`, `"de"`, `"au"`, `"ca"`
**Filter syntax:**
```json
{"field": "volume", "is": ["gte", 100]}
{"and": [filter1, filter2]}
```