---
name: seo-keyword-strategy
description: |
  Keyword strategy and research for SEO campaigns.
  Triggers: keyword research, keyword analysis, keyword gap, search volume,
  keyword clustering, intent classification, 키워드 전략, 키워드 분석,
  키워드 리서치, 검색량 분석, 키워드 클러스터링.
---

# SEO Keyword Strategy & Research

## Purpose

Expand seed keywords, classify search intent, cluster topics, and identify competitor keyword gaps for comprehensive keyword strategy development.

## Core Capabilities

1. **Keyword Expansion** - Matching terms, related terms, search suggestions
2. **Korean Market** - Suffix expansion, Naver autocomplete, Korean intent patterns
3. **Intent Classification** - Informational, navigational, commercial, transactional
4. **Topic Clustering** - Group keywords into semantic clusters
5. **Gap Analysis** - Find competitor keywords missing from target site

## Data Source Selection

This skill can pull keyword data from multiple backends. **Pick one per task** — don't fan out to every backend by default (cost + rate limits).

| Backend | Best for | Notes |
|---|---|---|
| **Semrush MCP** (`mcp__semrush__*`) | Default for keyword volume, related/matching terms, organic competitor pulls | Call pattern: `keyword_research` → `get_report_schema` → `execute_report`. `database="us"` default; `"kr"` for Korean market. |
| **Ahrefs MCP** (`mcp__ahrefs__*`) | Ahrefs DR/UR weighting; first-party `gsc-keywords` (only Ahrefs integrates GSC inside its MCP) | `keywords-explorer-overview`, `-matching-terms`, `-related-terms`, `-search-suggestions`, `-volume-by-country`, `gsc-keywords`. |
| **OurSEO Agent CLI** (`our keywords *`) | DataForSEO under the hood — cheapest per call, batch-friendly, Korean-aware via `--location 2410` | Claude Code only (needs Bash). Wrap calls: `our keywords volume`, `ideas`, `for-site`, `intent`, `difficulty`. |
| **OurSEO Agent MCP** (`mcp__ourseo__*`) | Claude Desktop equivalent for crawl-derived keywords + Knowledge Graph entity expansion | `search_knowledge_graph` for entity seeding; `crawl_website` to extract on-page keyword inventory from the target site itself. |
| **DataForSEO MCP** (`mcp__dfs-mcp__*`) | Direct fallback when `our` CLI isn't available | Same data as `our keywords *`. |
| **GSC** (via `our research search-console` or Ahrefs `gsc-*`) | First-party queries the site actually ranks for — ground truth, not estimates | Use to validate/prune Semrush or Ahrefs lists with real impressions/CTR. |

### How to pick

Apply these in order; stop at the first match:

1. **User named a backend explicitly** in the prompt → use it.
2. **User preference memory** — read `feedback_seo_tool_preferences.md`; honor the task-type default there.
3. **Task needs a capability only one backend has** (e.g., `gsc-keywords` first-party data, or `mcp__ourseo__search_knowledge_graph` entity expansion) → use that backend.
4. **Default by market**:
   - English-market or unspecified → **Semrush MCP** with `database="us"`.
   - Korean market → **OurSEO CLI** `our keywords <subcmd> --location 2410 --language ko` (Claude Code), or **Semrush MCP** with `database="kr"` (Claude Desktop).
5. **Still ambiguous on a non-trivial task** → ask once via `AskUserQuestion` listing the top 2–3 candidates.

### Backend call patterns

**Semrush MCP (default):**
```
mcp__semrush__keyword_research(query="<seed>", database="us")
mcp__semrush__get_report_schema(report_id="...")
mcp__semrush__execute_report(report_id="...", params={...})
```

**OurSEO CLI (Korean default, Claude Code):**
```bash
our keywords volume "<keyword>" --location 2410 --language ko
our keywords ideas "<keyword>" --location 2410 --limit 50
our keywords for-site <competitor.com> --location 2410 --limit 100
our keywords intent "<kw1>" "<kw2>" "<kw3>"
our keywords difficulty "<kw1>" "<kw2>"
```

**Ahrefs MCP (when user requests, or for GSC first-party):**
```
mcp__ahrefs__keywords-explorer-overview(keyword="<seed>", country="us")
mcp__ahrefs__keywords-explorer-matching-terms(keyword="<seed>", country="us")
mcp__ahrefs__keywords-explorer-volume-by-country(keyword="<seed>")
mcp__ahrefs__gsc-keywords(...)
```

**OurSEO Agent MCP (Claude Desktop, KG/entity expansion):**
```
mcp__ourseo__search_knowledge_graph(query="<brand or entity>")
mcp__ourseo__crawl_website(url="<target>", max_pages=50)
```

### Common parameters across backends

| Concept | Semrush | Ahrefs | DataForSEO / `our` CLI |
|---|---|---|---|
| Korean market | `database="kr"` | `country="kr"` | `--location 2410` |
| US market | `database="us"` | `country="us"` | `--location 2840` |
| Japan | `database="jp"` | `country="jp"` | `--location 2392` |
| Language | (database-bound) | (country-bound) | `--language ko`/`en`/`ja` |

## Workflow

### 1. Seed Keyword Expansion
1. Determine backend via **Data Source Selection** above.
2. Fetch search volume for the seed.
3. Expand via the chosen backend's "related" / "ideas" / "matching-terms" endpoint.
4. Apply Korean suffix expansion if Korean market (regardless of backend).
5. Deduplicate and merge.

### 2. Intent Classification & Clustering
1. Classify each keyword by search intent (informational / navigational / commercial / transactional).
2. Group keywords into topic clusters.
3. Identify pillar topics and supporting terms.
4. Calculate cluster-level metrics (total volume, avg KD).

### 3. Gap Analysis
1. Pull organic keywords for target via chosen backend.
2. Pull organic keywords for competitors (parallel).
3. Identify keywords present in competitors but missing from target.
4. Score opportunities by volume/difficulty ratio.
5. Prioritize by intent alignment with business goals.

## Output Format

```markdown
## Keyword Strategy Report: [seed keyword]

### Overview
- Data source: [Semrush | Ahrefs | OurSEO CLI | OurSEO MCP | GSC]
- Market: [database/location code]
- Total keywords discovered: [count]
- Topic clusters: [count]
- Total search volume: [sum]

### Top Clusters
| Cluster | Keywords | Total Volume | Avg KD |
|---|---|---|---|
| ... | ... | ... | ... |

### Top Opportunities
| Keyword | Volume | KD | Intent | Cluster |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |

### Keyword Gaps (vs competitors)
| Keyword | Volume | Competitor Position | Opportunity Score |
|---|---|---|---|
| ... | ... | ... | ... |
```

Always record the chosen data source in the **Overview** so future audits can compare apples to apples.

## Notion Output (Required)

All audit reports MUST be saved to OurDigital SEO Audit Log:
- **Database ID**: `2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
- **Properties**: Issue (title), Site (url), Category, Priority, Found Date, Audit ID
- **Language**: Korean with English technical terms
- **Audit ID Format**: KW-YYYYMMDD-NNN
