Keyword Discovery

---
name: keyword-discovery
description: >
  Keyword research, find keywords, what keywords should I target, keyword analysis.
  Covers seed discovery, expansion, intent classification, qualitative difficulty
  assessment, and topic clustering. Produces 150-300 prioritized keywords. Does NOT
  return numerical search volumes or difficulty scores — those require a keyword-data
  MCP (DataForSEO / Ahrefs / Semrush — Path B). Instead, uses observable SERP signals
  for relative assessment.
argument-hint: "[topic or seed keyword] [--non-interactive]"
allowed-tools: Read Glob Grep Write Bash WebFetch WebSearch
---

# Keyword Discovery Skill

Walk the user through a complete keyword research pipeline, producing a prioritized keyword plan they can act on immediately. Assume the user has never done keyword research before — explain every concept in plain language, but keep the process moving.

## Cross-model note

Works identically on Opus 4.7 / Sonnet 4.6 / Haiku 4.5. Expansion + intent classification + clustering all benefit from batch parallelism where per-keyword work is independent.

## Execution: parallel-first

- **Phase 1 seed gathering**: user interview serializes naturally
- **Phase 2 expansion**: long-tail / question / modifier / LSI / medium-tail expansion runs per-seed; per-seed WebSearch-autocomplete checks parallelize
- **Phase 3 intent classification**: per-keyword SERP inspection independent — batch WebSearch calls
- **Phase 4 difficulty assessment**: per-keyword SERP + competitor inspection independent — batch
- **Phase 5 clustering**: synthesis step, not parallelizable
- **Phase 6 prioritization**: synthesis step, not parallelizable

## Capability Honesty

Read `references/CAPABILITIES.md`. Key constraints:
- **Real search volume numbers** (e.g., "1,200 searches/month") require a keyword-data API — Path B
- **Real keyword difficulty scores** (e.g., "KD 42") require link-graph + SERP competitor strength — Path B
- **What this skill DOES provide**: observable SERP signals (who ranks, SERP feature presence, autocomplete prominence, competition density) interpreted qualitatively (High/Medium/Low, Easy/Moderate/Hard)

When the user wants real numbers, recommend a DataForSEO / Ahrefs / Semrush MCP integration.

## Mode Flags

- `--non-interactive` — Use reasonable defaults for Phase 1 questions, record unanswered items in `awaiting_user_review`

---

## Overview

Six phases in order:

1. **Seed Keyword Discovery** — gather raw inputs
2. **Keyword Expansion** — broaden the list
3. **Search Intent Classification** — tag every keyword
4. **Qualitative Difficulty Assessment** — observable competition signals
5. **Topic Cluster Mapping** — organize into hierarchy
6. **Prioritization** — produce ranked action plan

Work through each phase sequentially. Present findings after each phase before moving on.

---

## Phase 1: Seed Keyword Discovery

### Gather Context

Before generating a single keyword, ask:

1. **Business basics** — What does the business do? Products / services?
2. **Target audience** — Ideal customers? Language / jargon they use?
3. **Top 3 competitors** — Up to three main rivals (URLs or brands)
4. **Existing keywords** — Already targeting any? List them, or "none"

### Seed Sources

Mine seeds from every source below:

| Source | What to extract |
|---|---|
| **Business context** | Industry terms, product names, service categories, brand modifiers |
| **Competitor analysis** | Terms competitors rank for (from WebSearch of competitor sites); recurring themes in their title tags, H1s, meta descriptions |
| **Customer language** | Phrases from support tickets, reviews, forum posts, testimonials — words *customers* use, not marketing copy |
| **Question mining** | Questions from Reddit, Quora, "People Also Ask" boxes (observable via WebSearch) |
| **Google autocomplete** | Type each seed + capture suggested completions; same for YouTube + Amazon if relevant |
| **Internal site search** | If available, top queries visitors type on-site |

Deliver as a numbered table. Aim for **30-50 seed keywords** before moving on.

---

## Phase 2: Keyword Expansion

Expand each seed using four strategies. Go from ~40 seeds to **150-300 candidate keywords**.

### 2a. Long-Tail Variations (3-5 word phrases)
Add specificity. Long-tail keywords convert better because they match precise needs.

### 2b. Question-Based Keywords
Prepend: who, what, when, where, why, how.

### 2c. Modifier Keywords
- **Best / Top / Review / Comparison / vs** — commercial intent
- **Alternative / Cheap / Free** — budget-conscious buyers
- **Near me / [City]** — local intent
- **Template / Example / Checklist** — resource seekers
- **For beginners / For enterprises / For [audience]** — audience fit

### 2d. LSI / Semantic Keywords
Related terms that appear alongside the seed in top-ranking content.

### 2e. Medium-Tail Keywords
"Sweet spot" — 2-3 words, moderate competition. Often fastest wins.

Group the expanded list by strategy so the user can see where each keyword came from.

---

## Phase 3: Search Intent Classification

Every keyword gets exactly one intent tag.

### Intent Types

| Intent | Signal words | What Google shows |
|---|---|---|
| **Informational** | how to, what is, guide, tutorial, why, tips | Blog posts, Wikipedia, knowledge panels, videos |
| **Commercial** | best, top, review, comparison, vs, alternative | Listicles, review sites, comparison tables |
| **Transactional** | buy, price, discount, coupon, sign up, download | Shopping results, product pages, pricing pages |
| **Navigational** | [brand name], login, support, contact, app | Official site, login, app store |

### How to Classify

Look at the actual SERP (WebSearch):
- Shopping carousel / product ads → Transactional
- Video pack or PAA → likely Informational
- Comparison articles dominate → Commercial
- Single brand dominates positions 1-3 → Navigational

Mixed intent → label dominant, note secondary.

Add an "Intent" column to the keyword table.

---

## Phase 4: Qualitative Difficulty Assessment

**Honest framing**: This phase uses observable SERP signals to estimate relative difficulty (Easy / Moderate / Hard). It does NOT produce numerical difficulty scores. For real Keyword Difficulty metrics, integrate a DataForSEO / Ahrefs / Semrush MCP (Path B).

### Factors to Evaluate (per target keyword, batch WebSearch)

| Factor | Easy signal | Hard signal |
|---|---|---|
| **Who ranks now** | Forums, small blogs, thin content | Major brands, .gov, Wikipedia |
| **Content format** | Short articles, outdated posts | In-depth guides, interactive tools |
| **SERP features** | Featured snippet available | Knowledge panel from Wikipedia |
| **Commercial value** | No ads = lower commercial value | Heavy ads = lucrative but competitive |
| **Domain diversity** | 10 different domains on p1 | 3 domains own 7 results |
| **Content age** | Many results from 3+ years ago | All results from last 6 months |

### Difficulty Scale (qualitative)

- **Easy**: Thin/outdated content ranks; few strong domains; featured snippet available. Well-written article can rank in weeks.
- **Moderate**: Mix of strong and weak pages; requires comprehensive content + some backlinks. Expect 2-6 months.
- **Hard**: P1 is all high-authority with deep content. Requires significant authority, backlinks, time (6-12+ months).

Add "Difficulty" and "Observed Opportunity" columns:

```
#  | Keyword | Intent | Difficulty | Observed Opportunity
1  | project management for nonprofits | Commercial | Easy | Featured snippet slot available, weak top-3
2  | project management software | Commercial | Hard | Heavy ad spend, strong DR domains
```

### Volume Signal (qualitative, not numerical)

Use observable signals to estimate relative volume:
- **High signal**: prominent autocomplete, multiple SERP features, heavy ad coverage
- **Medium signal**: autocomplete present, some SERP features
- **Low signal**: no autocomplete, thin SERP, no ads

Do NOT invent "monthly search volume" numbers. Mark relative volume as High/Medium/Low.

---

## Phase 5: Topic Cluster Mapping

Organize keywords into a content hierarchy.

### Hierarchy

```
Pillar Topic (broad, 1-2 words, high relative volume)
  +-- Subtopic A (medium-tail, 2-3 words)
  |     +-- Long-tail query 1
  |     +-- Long-tail query 2
  +-- Subtopic B
        +-- Long-tail query 3
        +-- Long-tail query 4
```

### How to Build Clusters

1. **Identify pillars** — broadest, highest-relative-volume terms → comprehensive pillar pages (2,000-4,000 words)
2. **Group subtopics** — medium-tail as subtopics → supporting articles (1,000-2,000 words)
3. **Attach long-tail** — become sections within subtopic articles, standalone FAQ entries, or short posts
4. **Map internal links** — every subtopic links up to pillar; pillar links down to every subtopic; subtopics in same cluster link to each other where relevant

Present the full cluster map and confirm with the user before prioritization.

---

## Phase 6: Prioritization

### Scoring Criteria (qualitative)

| Criterion | Scale | Description |
|---|---|---|
| **Business relevance** | 1-10 | How closely does this keyword relate to the product/service? |
| **Volume signal (relative)** | High / Medium / Low | From observable SERP signals — NOT numerical volume |
| **Competition level** | Easy / Moderate / Hard | From Phase 4 |
| **Content gap** | Yes / No | Does the site already have content targeting this? |
| **Estimated effort** | Low / Medium / High | Time + resources to create ranking content |

### The Three Lists

#### 1. Top 10 Quick Wins
Keywords where content already exists (or is easy to create), competition signals easy, rank in weeks.

#### 2. Top 10 Strategic Targets
High-relevance with moderate competition. Dedicated content + some link building. Expect results in 2-6 months.

#### 3. Top 10 Long-Term Plays
High-competition, high-reward. Build toward these by first ranking for easier related keywords.

### Content Type Recommendations

| Content Type | When to use |
|---|---|
| Blog post | Informational long-tail, how-tos |
| Landing page | Transactional, product comparisons |
| Comprehensive guide | Pillar topics, informational medium-tail |
| Tool or calculator | "Calculator", "template", "generator" queries |
| Video | "How to" queries where Google shows video results |
| FAQ section | Question-based long-tail |
| Case study | "[Industry] + results/example" |

### The 70/20/10 Content Mix

- **70% Foundation** — how-to guides, tutorials, listicles, FAQ. Safe, proven formats. Start here.
- **20% Growth** — original research, data-driven posts, expert roundups, detailed comparisons. Higher effort, differentiates.
- **10% Moonshots** — interactive tools, contrarian pieces, original frameworks, viral-potential content. Most underperform but wins are outsized.

Tag each content calendar entry with its mix category.

---

## Delivery Checklist

- [ ] 30-50 seed keywords with sources
- [ ] 150-300 expanded keywords grouped by strategy
- [ ] Every keyword tagged with search intent
- [ ] Top 50+ keywords assessed for qualitative difficulty
- [ ] Complete topic cluster map with pillar-subtopic hierarchy
- [ ] Internal linking plan between cluster pages
- [ ] Top 10 Quick Wins with specific actions
- [ ] Top 10 Strategic Targets with content recommendations
- [ ] Top 10 Long-Term Plays with cluster-building roadmap
- [ ] Content type recommendation for each priority keyword
- [ ] 70/20/10 mix labels on all recommended content
- [ ] Measurement-gaps note: "For numerical search volumes and KD scores, integrate a DataForSEO / Ahrefs / Semrush MCP"

## Tone and Style

- Plain language. Define jargon first time used.
- Specific actions. "Write a blog post" is not actionable. "Write a 2,000-word comparison of X vs Y targeting commercial intent" is.
- Tables for any list > 5 items.
- Summary after each phase.
- When lacking real search volume data, say so honestly and use relative estimates based on observable signals.