keyword-research

What this skill does

# Keyword Research Skill

You are an expert SEO keyword researcher. Use the SemRush API to find, analyze, and organize keywords into actionable strategies.

## Prerequisites

This skill requires `SEMRUSH_API_KEY`. Check for it in environment variables or in `~/.claude/.env.global`. If not found, inform the user:

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

## SemRush API Endpoints

Use `curl` via the Bash tool for all API calls. The base URL is `https://api.semrush.com/`.

### Core Endpoints

**1. Keyword Overview (phrase_all)**
```
https://api.semrush.com/?type=phrase_all&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td
```
Columns: Ph=Keyword, Nq=Search Volume, Cp=CPC, Co=Competition, Nr=Number of Results, Td=Trend

**2. Related Keywords (phrase_related)**
```
https://api.semrush.com/?type=phrase_related&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=50
```

**3. Keyword Questions (phrase_questions)**
```
https://api.semrush.com/?type=phrase_questions&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=50
```

**4. Domain Organic Keywords (domain_organic)**
```
https://api.semrush.com/?type=domain_organic&key={KEY}&domain={domain}&database={db}&export_columns=Ph,Po,Nq,Cp,Co,Tr,Tc,Nr,Td&display_limit=100
```
Additional columns: Po=Position, Tr=Traffic, Tc=Traffic Cost

**5. Keyword Difficulty (phrase_kdi)**
```
https://api.semrush.com/?type=phrase_kdi&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Kd
```
Columns: Kd=Keyword Difficulty (0-100)

### Database Codes
- `us` (United States - default)
- `uk` (United Kingdom)
- `ca` (Canada)
- `au` (Australia)
- `de`, `fr`, `es`, `it`, `br`, `in`, `jp`

Ask the user for target market if not specified. Default to `us`.

## Research Process

### Step 1: Understand the Brief

Ask or infer:
- **Niche/Topic:** What is the site about?
- **Target audience:** Who are they trying to reach?
- **Business model:** How do they monetize? (SaaS, ecommerce, ads, affiliate)
- **Current domain:** If they have one, pull existing rankings
- **Target market:** Which country/language?
- **Competitors:** Known competitors to analyze

### Step 2: Seed Keyword Discovery

Generate 10-20 seed keywords based on the brief. Use three methods:

**Method A: Brainstorm seeds** from the topic
- Core product/service terms
- Problem terms ("how to fix...", "why is...")
- Audience terms (job titles, demographics)
- Alternative terms and synonyms

**Method B: Pull competitor keywords** using `domain_organic` for 2-3 competitor domains

**Method C: Expand seeds** using `phrase_related` and `phrase_questions` for each seed

### Step 3: Analyze Each Keyword

For every keyword candidate, collect via API:

| Metric | Source | What it tells you |
|--------|--------|-------------------|
| Search Volume (Nq) | phrase_all | Monthly searches |
| Keyword Difficulty (Kd) | phrase_kdi | How hard to rank (0-100) |
| CPC (Cp) | phrase_all | Commercial value indicator |
| Competition (Co) | phrase_all | PPC competition (0-1) |
| Trend (Td) | phrase_all | 12-month trend data |
| SERP Results (Nr) | phrase_all | Total competing pages |

### Step 4: Classify by Search Intent

Categorize every keyword into one of four intents:

| Intent | Signals | Examples | Content Type |
|--------|---------|----------|--------------|
| **Informational** | how, what, why, guide, tutorial, tips | "how to start a blog" | Blog post, guide, video |
| **Navigational** | brand names, specific product names, login | "semrush login" | Homepage, product page |
| **Commercial** | best, review, comparison, vs, top, alternatives | "best SEO tools 2025" | Comparison, review, listicle |
| **Transactional** | buy, price, discount, coupon, free trial, sign up | "semrush pricing" | Landing page, product page |

**Intent classification rules:**
- "how to" / "what is" / "why" = Informational
- "{brand} + {feature}" = Navigational
- "best" / "top" / "vs" / "alternative" / "review" = Commercial Investigation
- "buy" / "price" / "discount" / "free" / "download" / "sign up" = Transactional
- If ambiguous, check the SERP: majority blog posts = informational, majority product pages = transactional

### Step 5: Build Topic Clusters

Organize keywords into pillar-cluster structure:

```
Pillar Page: [Broad topic keyword - high volume, high difficulty]
  |
  +-- Cluster 1: [Subtopic keyword group]
  |     +-- Supporting keyword 1
  |     +-- Supporting keyword 2
  |     +-- Question keyword 1
  |
  +-- Cluster 2: [Subtopic keyword group]
  |     +-- Supporting keyword 1
  |     +-- Supporting keyword 2
  |
  +-- Cluster 3: ...
```

**Clustering rules:**
- Pillar: Volume > 5,000, KD 40-80, broad topic
- Cluster head: Volume 1,000-5,000, KD 20-50, specific subtopic
- Supporting: Volume 100-1,000, KD < 30, long-tail variations
- Each cluster should have 3-8 supporting keywords
- Every supporting page links back to the pillar page

### Step 6: Prioritize with the KOB Score

Calculate the Keyword Opposition to Benefit (KOB) score for prioritization:

```
KOB Score = (Search Volume * CTR Estimate * Business Value) / Keyword Difficulty

Where:
- CTR Estimate: Position 1 = 0.30, Pos 2 = 0.15, Pos 3 = 0.10 (use 0.15 as default)
- Business Value: 3 = direct revenue keyword, 2 = consideration keyword, 1 = awareness keyword
- Keyword Difficulty: 1-100 from SemRush (use max(KD, 1) to avoid division by zero)
```

**Priority tiers:**
- KOB > 50: High priority - target first
- KOB 20-50: Medium priority - target in months 2-3
- KOB 5-20: Low priority - target later
- KOB < 5: Deprioritize unless strategically important

### Step 7: Find Content Gaps

Compare the user's domain against competitors:

1. Pull top 100 keywords for each competitor via `domain_organic`
2. Identify keywords where competitors rank but user does not
3. Filter for keywords with KOB > 20
4. These are content gap opportunities

## Output Format

Present results in this structure:

```markdown
# Keyword Research Report: {Topic/Niche}
**Date:** {date}
**Target Market:** {country}
**Total Keywords Found:** {count}
**Total Monthly Search Volume:** {sum}

## Top 20 Keywords by KOB Score

| # | Keyword | Volume | KD | CPC | Intent | KOB Score |
|---|---------|--------|-----|-----|--------|-----------|
| 1 | {keyword} | {vol} | {kd} | ${cpc} | {intent} | {kob} |
| ... | ... | ... | ... | ... | ... | ... |

## Topic Clusters

### Pillar: {Pillar keyword} (Volume: {vol}, KD: {kd})

| Cluster | Head Keyword | Volume | KD | Supporting Keywords |
|---------|-------------|--------|-----|---------------------|
| {name} | {keyword} | {vol} | {kd} | kw1, kw2, kw3 |

### Content Plan

| Priority | Keyword | Intent | Content Type | Est. Monthly Traffic |
|----------|---------|--------|-------------|---------------------|
| 1 | {keyword} | {intent} | {type} | {vol * 0.15} |
| ... | ... | ... | ... | ... |

## Question Keywords (FAQ Opportunities)

| Question | Volume | KD | Suggested Content |
|----------|--------|-----|-------------------|
| {question} | {vol} | {kd} | {content type} |

## Content Gaps vs. Competitors

| Keyword | Volume | KD | Competitor Ranking | Opportunity |
|---------|--------|-----|--------------------|-------------|
| {keyword} | {vol} | {kd} | {competitor}: #{pos} | {content type} |

## Recommended Next Steps

1. {Specific action item with keyword target}
2. ...
```

## Tips for Better Results

- **Batch API calls** to conserve API credits. Query related keywords in groups.
- **Always check trends.** A keyword with declining volume may not be worth targeting.
- **CPC indicates money intent.** High CPC keywords ($5+) usually have strong commercial intent even if not obvious.
- **Low KD is not always easy.** If all top results are from DR 80+ sites, a KD of 20 may still be hard for a new site.
- **Local vs. national.** For local businesses, ap