/keyword-research

name: keyword-research
description: Perform keyword research using the SemRush API. Use when the user says "find keywords", "keyword research", "what should I rank for", "keyword ideas", "search volume", "keyword difficulty", "topic clusters", "content gaps", or asks about SEO keywords for a topic or niche.

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 prior