/blog-cluster

name: blog-cluster
description: >
  Semantic topic cluster planning and automated execution engine for claude-blog.
  Performs SERP-based keyword research, groups keywords by search intent and
  SERP overlap, builds a hub-and-spoke cluster architecture, generates an
  interactive SVG cluster map, and executes the full cluster by orchestrating
  blog-write calls with shared cluster context and automatic internal-link
  injection. Fills the strategy-to-execution gap: blog-strategy plans the
  blueprint, blog-cluster builds the house.
  Use when user says "blog cluster", "topic cluster", "content cluster",
  "cluster plan", "cluster execute", "cluster map".
license: MIT
compatibility: Requires Claude Code and claude-blog (provides blog-write, blog-chart, blog-image)
metadata:
  author: AgriciDaniel
  version: "2.3.2"
  category: blog
user-invocable: true
argument-hint: "[plan|execute] [seed-keyword|cluster-plan.json]"

Blog Cluster (Semantic Topic Cluster Engine)

Bundled paths below use host Markdown substitution of `${CLAUDE_SKILL_DIR}`; it is not an exported shell variable. Resolve them before execution, quote paths, and refuse nonabsolute overrides. Pass `blog_reference_root` resolved from `${CLAUDE_SKILL_DIR}/../blog/references`, `blog_template_root` from `${CLAUDE_SKILL_DIR}/../blog/templates`, and needed sibling roots to agents. Read the main reference `orchestration-details.md` before loading project context; pass only its helper-fenced output to downstream agents.

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: no longer available as of 2026-10-12. > 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)

• `${CLAUDE_SKILL_DIR}/references/semantic-clustering.md` (SERP overlap analysis, intent classification, keyword universe expansion)
• `${CLAUDE_SKILL_DIR}/references/cluster-architecture.md` (hub-and-spoke specs, schema strategy, link-density rules)
• `${CLAUDE_SKILL_DIR}/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` (internal) | Invoked by the orchestrator during `blog-write` for inline SVG charts. No direct call from this skill. | | `/blog image` | Not called by this skill. Each post's hero is created once by `blog-write`'s delivery contract (via `generate_hero.py`); see Step 4. | | `/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. The orchestrator invokes the sub-skills (`blog-write`, `blog-analyze`) itself, one post at a time, never inside an agent: `blog-write` starts its own agents (researcher, writer, reviewer), and an agent cannot start another agent.

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: `${CLAUDE_SKILL_DIR}/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> <current year>`. Take the current year from the system date; never hard-code a year.

Step 2. Semantic clustering

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

1. **SERP Overlap Analysis** is the primary signal. Two keywords with 4 or more shared top-10 results usually target the same intent and should be considered for one post. 2. **Intent Classification** assigns each keyword to informational, commercial, transactional, or navigati