seo-cluster

[{"code":"payment","match":"pricing","path":"SKILL.md"}]

# Execution Workflow

## Overview

The execution phase transforms a `cluster-plan.json` into actual content. It handles
priority ordering, context injection for the blog writer, backward link updates,
resume capability, and post-execution quality scoring.

## Priority Algorithm

Content is created in this strict order:

1. **Pillar page first** -- The hub must exist before any spokes can link to it
2. **Spokes by search volume (descending)** -- Highest-volume spokes first for
   maximum early impact
3. **Within same volume, by cluster index** -- Process Cluster 0 before Cluster 1
4. **Within same cluster, by post index** -- Process Post 0 before Post 1

Rationale: The pillar establishes the topical authority foundation. High-volume
spokes generate the most organic traffic, so they should be published earliest
for faster compounding returns.

## Cluster Context Injection

When invoking `blog-write` for each post, pass a structured context block:

```json
{
  "cluster_context": {
    "role": "pillar|spoke",
    "pillar_title": "The Complete Guide to ...",
    "pillar_url": "/guide/...",
    "cluster_name": "Cluster Name",
    "cluster_index": 0,
    "post_index": 0,
    "primary_keyw

# Hub-and-Spoke Content Architecture

## Structure Overview

A hub-and-spoke cluster consists of one pillar page (the hub) connected to multiple
spoke clusters, each containing 2-4 individual posts. The pillar provides broad
coverage; spokes provide deep dives into subtopics.

```
                    [Spoke 1a] --- [Spoke 1b]
                         \       /
                      [Cluster 1]
                           |
[Spoke 2a] -- [Cluster 2] -- [PILLAR] -- [Cluster 3] -- [Spoke 3a]
[Spoke 2b] /                                        \ [Spoke 3b]
                           |
                      [Cluster 4]
                         /       \
                    [Spoke 4a] --- [Spoke 4b]
```

## Pillar Page Specifications

| Attribute | Requirement |
|-----------|-------------|
| Word count | 2,500-4,000 words |
| Keyword | Broadest, highest-volume keyword in the set |
| Content type | Comprehensive overview covering all cluster subtopics |
| Template | `ultimate-guide` (default) |
| Internal links | Link to EVERY spoke post in every cluster (mandatory) |
| Structure | Table of contents, section per cluster, summary per subtopic |
| Schema | Article + BreadcrumbList + ItemList

# SERP Overlap Methodology

## Core Principle

Two keywords that return the same Google results should be targeted by the same page.
Two keywords that return completely different results need separate pages. This is the
foundation of SERP-based clustering -- using Google's own ranking decisions to determine
content architecture rather than relying on keyword text similarity or stemming.

## Scoring Algorithm

### Step 1: Collect SERP Data

For each keyword in the candidate set, retrieve the top 10 organic results:
- Use WebSearch or DataForSEO `serp_organic_live_advanced`
- Extract only organic result URLs (ignore ads, featured snippets, PAA, knowledge panels)
- Normalize URLs: strip protocol, trailing slash, and query parameters (except meaningful ones)
- Store as a set of 10 URLs per keyword

### Step 2: Pairwise Comparison

For each pair of keywords (A, B):
1. Retrieve the URL sets: `urls_A` and `urls_B`
2. Compute overlap: `shared = urls_A intersection urls_B`
3. Score: `overlap_score = len(shared)`

### Step 3: Apply Thresholds

| Overlap Score | Relationship | Action |
|--------------|-------------|--------|
| 7-10 | **Same post** | Merge keywords into one target page. Use hi

---
name: seo-cluster
description: >
  SERP-based semantic topic clustering for content architecture planning. Groups
  keywords by actual Google SERP overlap (not text similarity), designs hub-and-spoke
  content clusters with internal link matrices, and generates interactive
  visualizations. Optionally executes content creation if claude-blog is installed.
  Use when user says "topic cluster", "content cluster", "semantic clustering",
  "pillar page", "hub and spoke", "content architecture", "keyword grouping",
  or "cluster plan".
user-invocable: true
argument-hint: "<seed-keyword or url>"
license: MIT
metadata:
  author: AgriciDaniel
  original_author: "Lutfiya Miller (Pro Hub Challenge Winner)"
  version: "2.2.5"
  category: seo
---

# Semantic Topic Clustering

SERP-overlap-driven keyword clustering for content architecture. Groups keywords
by how Google actually ranks them (shared top-10 results), not by text similarity.
Designs hub-and-spoke content clusters with internal link matrices and generates
interactive cluster map visualizations.

**Scripts:** Located at the plugin root `scripts/` directory.

---

## Quick Reference

| Command | What it does |
|---------|---------