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:

Pull top 100 keywords for each competitor via
```
domain_organic
```
Identify keywords where competitors rank but user does not
Filter for keywords with KOB > 20
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, append city/state to seed keywords.
Seasonal keywords. Note if trends show seasonality; plan content 2-3 months before peak.
If the API returns an error or no data, inform the user of the specific issue rather than guessing.

Supplementary API Integrations

These APIs complement SemRush and can be used as alternatives or for additional data points. They are not required if SemRush is available.

DataForSEO (Alternative/Complement to SemRush)

DATAFORSEO_LOGIN

and

DATAFORSEO_PASSWORD

are available, use DataForSEO for keyword search volume and related data. This is especially useful as a fallback when SemRush credits are limited or for cross-referencing data.

Search Volume Endpoint:

bash

# Get keyword search volume data from DataForSEO
curl -s -X POST "https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live" \
  -H "Authorization: Basic $(echo -n "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '[{"keywords": ["keyword1", "keyword2", "keyword3"], "location_code": 2840, "language_code": "en"}]'

Parsing the response:

bash

# Extract keyword metrics from DataForSEO response
curl -s -X POST "https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/live" \
  -H "Authorization: Basic $(echo -n "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '[{"keywords": ["keyword1", "keyword2"], "location_code": 2840, "language_code": "en"}]' | \
  jq '.tasks[0].result[] | {
    keyword: .keyword,
    search_volume: .search_volume,
    competition: .competition,
    competition_index: .competition_index,
    cpc: .cpc,
    monthly_searches: .monthly_searches
  }'

Key fields:

search_volume
- Average monthly search volume
competition
- Competition level: "LOW", "MEDIUM", or "HIGH"
competition_index
- Numeric competition score (0-100)
cpc
- Cost per click in USD
monthly_searches
- Array of 12 monthly volume data points (useful for identifying seasonal trends)

Common location codes:

```
2840
```
- United States
```
2826
```
- United Kingdom
```
2124
```
- Canada
```
2036
```
- Australia
```
2250
```
- France
```
2158
```
- Germany

Keyword Suggestions Endpoint:

bash

# Get keyword suggestions (similar to SemRush phrase_related)
curl -s -X POST "https://api.dataforseo.com/v3/keywords_data/google_ads/keywords_for_keywords/live" \
  -H "Authorization: Basic $(echo -n "${DATAFORSEO_LOGIN}:${DATAFORSEO_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '[{"keywords": ["seed keyword"], "location_code": 2840, "language_code": "en", "sort_by": "search_volume"}]'

When to use DataForSEO vs SemRush:

Use SemRush as the primary source for keyword difficulty, competitor analysis, and domain organic keywords
Use DataForSEO for bulk search volume lookups (supports up to 700 keywords per request, more cost-effective for large batches)
Use DataForSEO when you need Google Ads-aligned data (their data comes directly from Google Keyword Planner)
Cross-reference both sources when search volume numbers differ significantly

SerpAPI (People Also Ask & Related Searches)

SERPAPI_API_KEY

is available, use SerpAPI to extract "People Also Ask" questions and related searches directly from Google SERPs. This data is not available from SemRush and is valuable for FAQ sections and content ideation.

Search Endpoint:

bash

# Get SERP data including People Also Ask and related searches
curl -s "https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10"

Parsing People Also Ask:

bash

# Extract People Also Ask questions
curl -s "https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10" | \
  jq -r '.related_questions[] | {
    question: .question,
    snippet: .snippet,
    link: .link,
    title: .title
  }'

Key response sections:

related_questions
- Array of "People Also Ask" questions with snippets and source URLs
related_searches
- Array of related search queries that Google suggests
organic_results
- Top 10 organic results (useful for SERP analysis)

Parsing Related Searches:

bash

# Extract related searches for content ideation
curl -s "https://serpapi.com/search.json?q={keyword}&api_key=${SERPAPI_API_KEY}&num=10" | \
  jq -r '.related_searches[] | .query'

How to use SerpAPI data in keyword research:

FAQ content: Use "People Also Ask" questions directly as H2/H3 headings in blog posts or as FAQ schema entries. These are questions Google already associates with the keyword.
Content gap discovery: If a PAA question has a weak snippet answer (short, vague, or from a low-authority site), that is an opportunity to write a better answer and win the featured snippet.
Keyword expansion: Related searches are Google's own suggestions for related topics. Add these to your keyword list and check their volume via SemRush or DataForSEO.
Search intent validation: The organic results show what content types Google ranks for this keyword. If all top 10 are blog posts, write a blog post. If they are product pages, a blog post will not rank.
Cluster building: Group PAA questions and related searches by subtopic to identify natural content clusters.

Additional SerpAPI parameters:

```
location=United+States
```
- Geo-target the search
```
gl=us
```
- Country code for Google domain
```
hl=en
```
- Interface language
```
device=desktop
```
or
```
device=mobile
```
- Desktop vs mobile SERPs (mobile may show different PAA questions)

Note: SerpAPI charges per search. Use it strategically for your highest-priority keywords rather than for bulk research. Pair it with SemRush for volume data and DataForSEO for bulk lookups.

keyword-research

NPX Install

Tags

SKILL.md Content

Keyword Research Skill

Prerequisites

SemRush API Endpoints

Core Endpoints

Database Codes

Research Process

Step 1: Understand the Brief

Step 2: Seed Keyword Discovery

Step 3: Analyze Each Keyword

Step 4: Classify by Search Intent

Step 5: Build Topic Clusters

Step 6: Prioritize with the KOB Score

Step 7: Find Content Gaps

Output Format

Tips for Better Results

Supplementary API Integrations

DataForSEO (Alternative/Complement to SemRush)

SerpAPI (People Also Ask & Related Searches)