keyword-cluster-architect

# Keyword Cluster Architect

Map 50-200+ keywords into topical clusters grouped by search intent. Build a content roadmap for dominating a topic with hub-and-spoke architecture. Google rewards topical authority — this skill builds the strategic map that tells you exactly what content to create and in what order.

## Stage

S3: Blog & SEO — This is the strategic planning layer FOR blog content. Before writing individual posts, you need a map of the entire keyword landscape organized into clusters.

## When to Use

- User wants to plan SEO content strategy for a niche
- User asks about keyword research, clustering, or topical authority
- User says "keyword", "SEO plan", "content roadmap", "topic cluster", "hub and spoke"
- Before running `affiliate-blog-builder` — to know WHICH articles to write
- After `monopoly-niche-finder` — to map the keyword universe for the winning niche

## Input Schema

```yaml
niche: string                 # REQUIRED — the topic to cluster
                              # e.g., "AI video tools", "email marketing for SaaS"

seed_keywords: string[]       # OPTIONAL — starting keywords to expand from
                              # Default: auto-generated from niche

depth: string                 # OPTIONAL — "quick" (50 keywords) | "standard" (100) | "deep" (200+)
                              # Default: "standard"

affiliate_products: string[]  # OPTIONAL — products you promote (to prioritize commercial keywords)
                              # Default: none
```

**Chaining from S1 monopoly-niche-finder**: Use `monopoly_niche.intersection` as the `niche` input.

## Workflow

### Step 1: Generate Seed Keywords

If not provided, generate 5-10 seed keywords from the niche:
- Product-focused: "[product] review", "best [category]"
- Problem-focused: "how to [solve problem]", "[problem] solution"
- Comparison: "[product A] vs [product B]", "alternatives to [product]"
- Tutorial: "how to use [product]", "[product] tutorial"

### Step 2: Expand Keywords

For each seed, use `web_search` to discover related keywords:
1. Search: `"[seed keyword]"` — note related searches, People Also Ask
2. Search: `"[seed keyword] guide" OR "[seed keyword] tutorial"` — informational variants
3. Search: `"best [seed keyword]" OR "[seed keyword] review"` — commercial variants

Collect 50-200+ unique keywords depending on `depth`.

### Step 3: Classify by Intent

Read `shared/references/seo-strategy.md` for clustering methodology.

Classify each keyword:
- **Informational** (I): Learning, how-to, what-is → blog posts, tutorials
- **Commercial** (C): Comparing, evaluating, reviewing → comparison posts, reviews
- **Transactional** (T): Ready to buy, pricing, discount → landing pages, deal pages
- **Navigational** (N): Brand-specific, login → skip (not your traffic to capture)

### Step 4: Cluster by Topic

Group keywords that share the same search intent (would be answered by the same page):

```
Cluster: "[Main Topic]"
  Type: [I/C/T]
  Hub keyword: [highest volume keyword]
  Supporting keywords:
    - [keyword 1] — [est. volume]
    - [keyword 2] — [est. volume]
  Content type: [blog post / comparison / review / tutorial / landing page]
  Priority: [1-5 based on volume × intent × competition]
```

### Step 5: Build Content Roadmap

Organize clusters into a hub-and-spoke map:

1. Identify the hub page (broadest, highest-volume cluster)
2. Connect spoke pages (specific clusters that link back to hub)
3. Prioritize by: commercial intent first (revenue), then informational (traffic)
4. Estimate effort: number of articles needed, suggested publishing cadence

### Step 6: Self-Validation

- [ ] Clusters are based on actual search data, not guesses
- [ ] Each cluster has a clear search intent (I, C, or T)
- [ ] Hub-and-spoke structure is logical (hub is broad, spokes are specific)
- [ ] Priority ordering makes business sense (revenue-driving content first)
- [ ] Total content pieces are realistic for user's capacity

## Output Schema

```yaml
output_schema_version: "1.0.0"
keyword_clusters:
  niche: string
  total_keywords: number
  total_clusters: number

  hub:
    keyword: string
    cluster_name: string
    content_type: string
    priority: number

  clusters:
    - name: string
      intent: string          # "informational" | "commercial" | "transactional"
      hub_keyword: string
      keywords: string[]
      content_type: string    # "blog" | "comparison" | "review" | "tutorial" | "landing"
      priority: number        # 1-5
      estimated_volume: string

  content_roadmap:
    total_articles: number
    publishing_cadence: string
    priority_order: string[]  # Cluster names in order to write

  target_keywords: string[]   # Flat list of all keywords for chaining

chain_metadata:
  skill_slug: "keyword-cluster-architect"
  stage: "blog"
  timestamp: string
  suggested_next:
    - "affiliate-blog-builder"
    - "content-moat-calculator"
    - "comparison-post-writer"
    - "landing-page-creator"
```

## Output Format

```
## Keyword Cluster Map: [Niche]

### Overview
- **Total keywords:** XXX
- **Clusters:** XX
- **Hub topic:** [main hub]
- **Content pieces needed:** XX articles

### Hub & Spoke Map
```
           [HUB: Main Topic]
          /    |    |    \
     [Spoke] [Spoke] [Spoke] [Spoke]
       |       |       |       |
     [Sub]   [Sub]   [Sub]   [Sub]
```

### Clusters by Priority

#### Priority 1: [Cluster Name] (Commercial Intent)
- **Hub keyword:** [keyword] — [volume]
- **Content type:** [comparison / review]
- **Keywords:** [list]
- **Article idea:** [specific title]

#### Priority 2: [Cluster Name] (Informational Intent)
[same structure]

[Continue for all clusters]

### Content Roadmap
| Week | Cluster | Article | Intent | Priority |
|---|---|---|---|---|
| 1 | [cluster] | [title] | C | 1 |
| 2 | [cluster] | [title] | C | 1 |
| 3 | [cluster] | [title] | I | 2 |

### Next Steps
- Run `content-moat-calculator` to estimate effort for topical authority
- Run `affiliate-blog-