blog-cluster

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:
4. plan <keyword> to the Plan Phase (below)
5. plan --from strategy [path] to the Strategy Import flow (below)
6. 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

{
  "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 &, < with <, > with >, " with ", and ' with ' 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 inte