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

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

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

{
  "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 interlinks, estimated words, and the file paths. Ask for confirmation before proceeding to execution. Wait for explicit user approval. Do not auto-execute.

Strategy Import: /blog cluster plan --from strategy [path]

Bridges blog-strategy output into a cluster plan.

1. Locate strategy output. Scan the current directory (or the user-specified path) for a file containing a Cluster Build Plan table with the columns # | Spoke Topic | Template | Target Keyword | Word Count | Internal Links (the format produced by /blog strategy).
2. Parse the table. Extract the pillar row (marked P), the spoke rows, template assignments, target keywords, word counts, and link relationships.
3. Validate and enrich. Run SERP overlap validation (Plan Phase Step 2) on each keyword. Add volume estimates and verify cluster groupings semantically.
4. If SERP data contradicts the strategy table, flag the conflict; do not silently override the user's strategic intent.
5. Generate cluster-plan.json and cluster-map.html using the same outputs as the standard Plan Phase.
6. Present the converted plan with any SERP-based adjustments highlighted, and wait for user confirmation.

Execute Phase: /blog cluster execute [path-to-plan]

Reference: references/execution-workflow.md

Step 1. Load plan

Read cluster-plan.json from the user-specified path or the most recent cluster-*/cluster-plan.json in the working directory. Validate JSON structure. If no plan exists, return: "No cluster plan found. Run /blog cluster plan <seed-keyword> first."

Step 2. Determine execution order

1. Pillar page first (so spokes can link to a known filename).
2. Then spokes, ordered by (cluster priority, search_volume_estimate desc, post id alphabetical). Cluster priority is the sum of estimated volumes within the cluster (highest first).
3. Alternating between clusters when more than 2 clusters exist diversifies the early content spread.

Step 3. For each post: build cluster context and call blog-write

Construct the cluster context block (full schema in references/execution-workflow.md) and prepend it to the topic prompt passed to the Task tool invoking blog-write. The context tells blog-write the cluster name, the post's role (pillar or spoke), the primary and secondary keywords, the chosen template, the word count target, the list of already-written posts (link to these), the list of upcoming posts (use [INTERNAL-LINK] placeholders), and the linking requirements for this post.

FLOW evidence triple propagation (required). The cluster context must include this directive for every spoke and the pillar: "Apply the FLOW evidence triple to every public statistic. Year anchor in prose ('In 2026,'), inline citation with publisher and title, URL with retrieval date in the source block. Drop unverifiable stats. Replace contradicted ones."

This cascade is required because cluster execution is a high-leverage operation (5 to 15 posts at once). Without explicit propagation, individual spokes could silently skip evidence discipline. See skills/blog/references/flow-alignment.md.

The context also instructs blog-write to run autonomously: skip topic clarification, skip outline approval, do not auto-detect template, do not pause.

Output format: standard markdown (.md) by default, matching blog-write's default. If the user explicitly requests HTML, set the platform target accordingly. Do not impose any brand-specific CSS or wordmark; that is the user's responsibility downstream.

Step 4. Per-post optional hero image

If nanobanana-mcp is configured, call /blog image generate via the Task tool to produce a 16:9 hero image for the post and place it in cluster-<slug>/images/<post-slug>-hero.png. Insert a standard markdown image reference in the post's frontmatter (coverImage:) and at the top of the body. If the MCP is unavailable or fails, log a warning and continue without images. Image generation is non-blocking.

Step 5. Backward link injection

After each post is written:

1. Scan all previously written posts in the cluster directory for [INTERNAL-LINK: keyword -> filename.md] markers that reference the just-written post.
2. Replace each match with a real markdown link: [keyword](filename.md).
3. Add a cluster metadata block to the post's frontmatter on first pass (cluster:, cluster_role:, cluster_group:).

Step 6. Failure handling

If blog-write fails for a single post (timeout, error, or quality gate fail), log the failure and continue with remaining posts. Do not abort the cluster. The scorecard will mark the gap and recommend a retry with /blog write invoked manually for that post.

If the user cancels mid-execution, save progress and note completed posts. On the next /blog cluster execute, detect already-written files and resume from the next unwritten post.

Step 7. Generate cluster-scorecard.md

After all attempted posts complete, produce a markdown scorecard covering:

• Per-post status (written, failed, skipped) with file path and word count.
• Per-post quality score (call /blog analyze on each in parallel) and the cluster average.
• Cluster cohesion score: a 0 to 100 composite of link reciprocity, intent diversity, template diversity, and keyword coverage (formula in references/execution-workflow.md).
• Internal-link audit: outgoing and incoming counts per post, orphan flags, unresolved [INTERNAL-LINK] markers.
• Cannibalization check: any two posts sharing primary keyword, or any pair with greater than 70% keyword overlap. Recommend running /blog cannibalization for a deeper pass.
• Image generation summary: hero images generated vs. skipped.
• Recommended next actions: schema generation (/blog schema), per-post SEO validation (/blog seo-check), repurposing (/blog repurpose).

Step 8. Final report

Return a concise summary to the user with totals, the scorecard path, and the next-action commands.

Output Artifacts (summary)

Quality Gates

Error Handling

Differentiation from related claude-blog skills

blog-cluster is the general contractor: it analyzes the topic, draws the data-driven plan, and builds the entire structure from a single seed keyword.