blog-cluster

What this skill does

# Blog Cluster (Semantic Topic Cluster Engine)

Plans and executes entire interlinked content ecosystems from a single seed
keyword. Three layers: Semantic Clustering (the brain), Cluster Architecture
(the structure), and Execution Engine (the machine).

> Adapted from the **semantic-cluster-engine** submission by Lutfiya Miller
> (winner, AI Marketing Hub Pro Challenge, March 2026, 95/100 Exemplary).
> Original repository: https://github.com/Drfiya/semantic-cluster-engine
> This port keeps the Plan + Execute architecture and the cluster context
> innovation, removes brand-specific (ScienceExperts.ai) styling and image
> prompts, and routes through claude-blog's existing sub-skills.

## Commands

| Command | What it does |
|---------|--------------|
| `/blog cluster` | Interactive. Asks whether to plan or execute. |
| `/blog cluster plan <seed-keyword>` | SERP-based semantic analysis. Outputs cluster plan + map. |
| `/blog cluster plan --from strategy [path]` | Imports existing `blog-strategy` cluster build plan and validates against SERP data. |
| `/blog cluster execute [path-to-plan]` | Sequential `blog-write` calls with cluster context and auto-interlinks. |

## Key references (load on demand)

- `references/semantic-clustering.md` (SERP overlap analysis, intent classification, keyword universe expansion)
- `references/cluster-architecture.md` (hub-and-spoke specs, schema strategy, link-density rules)
- `references/execution-workflow.md` (execution order, context injection, scorecard, failure handling)

## Cross-references to existing claude-blog skills

| Skill | When this skill calls it |
|-------|--------------------------|
| `/blog strategy` | Upstream planning. `plan --from strategy` consumes its Cluster Build Plan tables. |
| `/blog write` | Per-post execution. Each spoke and the pillar are produced by `blog-write` with a prepended cluster-context block. |
| `/blog chart` | Invoked internally by `blog-write` for inline SVG charts. No direct call from this skill. |
| `/blog image` | Optional hero image generation per post (graceful fallback if `nanobanana-mcp` is not configured). |
| `/blog seo-check` | Recommended after execution for per-post on-page validation. |
| `/blog cannibalization` | Recommended after execution to confirm zero keyword overlap across the cluster. |
| `/blog schema` | Recommended after execution to add `BreadcrumbList`, `ItemList`, and `Article` schema. |

This skill never modifies files belonging to other skills. It calls them via the Task tool or as orchestrated sub-skills.

## Command Routing

1. Parse the user's command to determine the sub-command.
2. If the user typed only `/blog cluster`, ask: "Would you like to **plan** a new cluster or **execute** an existing plan?"
3. Route:
   - `plan <keyword>` to the Plan Phase (below)
   - `plan --from strategy [path]` to the Strategy Import flow (below)
   - `execute [path]`, `build`, or `run` to the Execute Phase (below)

---

## Plan Phase: `/blog cluster plan <seed-keyword>`

Reference: `references/semantic-clustering.md`

### Step 1. Seed keyword expansion

Use WebSearch to expand the seed into a keyword universe of 30 to 50 phrases:

1. Direct search of `<seed>` to capture related searches and "People also ask".
2. Long-tail expansion: `<seed> guide`, `<seed> tips`, `<seed> tools`, `<seed> examples`, `<seed> vs`, `best <seed>`, `how to <seed>`.
3. Question mining: `what is <seed>`, `how does <seed> work`, `why <seed>`, `<seed> for beginners`.
4. Intent variants: add commercial modifiers (best, top, review, comparison, pricing), informational modifiers (guide, tutorial, explained, examples), and transactional modifiers (buy, download, tool, software, service).
5. Year freshness: `<seed> 2026`.

### Step 2. Semantic clustering

Group the expanded keywords using the priority rules in `references/semantic-clustering.md`:

1. **SERP Overlap Analysis** is the primary signal. Two keywords with 5 or more shared top-10 results target the same intent and belong in one post.
2. **Intent Classification** assigns each keyword to informational, commercial, transactional, or navigational.
3. **Entity Mapping** identifies the people, products, frameworks, and organizations Google associates with the topic.
4. **Grouping** combines keywords that share intent and topical proximity. Each group becomes one branch of the hub and spoke.

### Step 3. Cluster architecture design

Reference: `references/cluster-architecture.md`

Build the hub and spoke:

- **Pillar (hub)**: targets the broadest keyword. Word count 2,500 to 4,000. Template `pillar-page`. Links down to every spoke.
- **Spokes**: each targets a long-tail cluster. Word count 1,200 to 1,800. Template auto-selected by intent. Links up to the pillar and across to siblings.

Cluster formation rules:

- 2 to 5 clusters per pillar.
- 2 to 4 spokes per cluster.
- Total: 1 pillar plus 5 to 15 spokes.
- Every spoke targets a unique primary keyword (zero cannibalization).

### Step 4. Internal link matrix

For each spoke `S`:

- `S` to Pillar (always; anchor text uses the pillar's primary keyword).
- Pillar to `S` (always; anchor text uses `S`'s primary keyword).
- `S` to other spokes in the same cluster (2 to 3 links each, contextual anchors).
- `S` to spokes in adjacent clusters (0 to 1 links, only when semantically relevant).

Verify every spoke has at least 3 incoming links. Count total planned interlinks.

### Step 5. Generate output files

All plan and execute artifacts go into a single subdirectory of the current working directory:

```
<cwd>/
└── cluster-<seed-keyword-slug>/
    ├── cluster-plan.json
    ├── cluster-map.html
    ├── pillar-<slug>.md       (Execute Phase)
    ├── <spoke-slug>.md        (Execute Phase, one per spoke)
    └── cluster-scorecard.md   (Execute Phase)
```

#### `cluster-plan.json` schema

```json
{
  "seed_keyword": "<seed>",
  "generated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "pillar": {
    "id": "P",
    "title": "Title of the pillar",
    "primary_keyword": "broadest keyword",
    "secondary_keywords": ["..."],
    "search_volume_estimate": "high|medium|low",
    "template": "pillar-page",
    "word_count_target": 3000,
    "cluster": "pillar"
  },
  "clusters": [
    {
      "name": "Cluster A: Theme",
      "intent": "informational|commercial|transactional",
      "color": "#2563eb",
      "posts": [
        {
          "id": "A1",
          "title": "Post title",
          "primary_keyword": "long-tail keyword",
          "secondary_keywords": ["..."],
          "search_volume_estimate": "high|medium|low",
          "template": "how-to-guide",
          "word_count_target": 1500,
          "links_to": ["P", "A2"],
          "links_from": ["P", "A2"]
        }
      ]
    }
  ],
  "total_posts": 9,
  "total_interlinks": 23,
  "estimated_total_words": 18000
}
```

Note: volume estimates are relative indicators (high, medium, low) derived from SERP signals, not absolute search volumes. For precise data, the user should consult Ahrefs, SEMrush, or DataForSEO (claude-blog provides the `seo-dataforseo` companion sibling).

#### `cluster-map.html` (XSS-safe)

A static, self-contained HTML file with an embedded SVG visualization. Hard rules for the writer:

- No inline `<script>` blocks. No `onclick`, `onmouseover`, or any `on*` event attributes anywhere in the document.
- No external script `<src>` references.
- Every text label drawn into the SVG (titles, keywords, cluster names) must be escaped: replace `&` with `&amp;`, `<` with `&lt;`, `>` with `&gt;`, `"` with `&quot;`, and `'` with `&#39;` before insertion.
- Hover effects use CSS `:hover` only. No JavaScript.
- Use `<title>` child elements inside SVG nodes for accessible tooltips (browser native, no script).

The map shows: a central pillar node, color-coded cluster groups radiating outward, spoke nodes within each cluster, and link lines connecting related nodes.

### Step 6. Present plan to user

Show a summary table of clusters and posts, total int