Semantic Topic Clustering (v1.9.0)

scripts/

Quick Reference

/seo cluster plan <seed-keyword>

/seo cluster plan --from strategy

/seo plan

/seo cluster execute

/seo cluster map

Planning Workflow

Step 1: Seed Keyword Expansion

1. Related searches — Search the seed, extract "related searches" and "people also search for"
2. People Also Ask (PAA) — Extract all PAA questions from SERP results
3. Long-tail modifiers — Append common modifiers: "best", "how to", "vs", "for beginners", "tools", "examples", "guide", "template", "mistakes", "checklist"
4. Question mining — Generate who/what/when/where/why/how variants
5. Intent modifiers — Add commercial modifiers: "pricing", "review", "alternative", "comparison", "free", "top"

Step 2: SERP Overlap Clustering

references/serp-overlap-methodology.md

1. Group keywords by initial intent guess (reduces pairwise comparisons)
2. For each candidate pair within a group, WebSearch both keywords
3. Count shared URLs in the top 10 organic results (ignore ads, featured snippets, PAA)
4. Apply thresholds:

• Pre-group by intent (4 groups of ~10 = 4 x 45 = 180 comparisons)
• Only cross-check group boundary keywords
• Skip pairs where both are long-tail variants of the same head term (assume same cluster)

serp_organic_live_advanced

python scripts/dataforseo_costs.py check serp_organic_live_advanced --count N

"status": "needs_approval"

"status": "blocked"

Step 3: Intent Classification

Step 4: Hub-and-Spoke Architecture

references/hub-spoke-architecture.md

1. Select the pillar keyword — Highest volume, broadest intent, most SERP overlap with other keywords
2. Group spokes into clusters — Each cluster is a subtopic area (2-5 clusters per pillar)
3. Assign posts to clusters — Each cluster gets 2-4 spoke posts
4. Select templates per post — Based on intent classification:

1. Set word count targets:
   • Pillar page: 2500-4000 words
   • Spoke posts: 1200-1800 words
2. Cannibalization check — No two posts share the same primary keyword. If SERP overlap is 7+, merge those keywords into a single post targeting both.

Step 5: Internal Link Matrix

• Every post must have minimum 3 incoming internal links
• No orphan pages (every post reachable from pillar in 2 clicks)
• Anchor text must use target keyword or close variant (no "click here")
• Link placement: within body content, not just navigation/sidebar

{
  "links": [
    { "from": "pillar", "to": "cluster-0-post-0", "type": "mandatory", "anchor": "keyword" },
    { "from": "cluster-0-post-0", "to": "pillar", "type": "mandatory", "anchor": "keyword" }
  ]
}

Step 6: Interactive Cluster Map

cluster-map.html

templates/cluster-map.html

1. Read the template file
2. Build the

   CLUSTER_DATA

   JSON object from the cluster plan:
   javascript

   {
     pillar: { title, keyword, volume, template, wordCount, url },
     clusters: [{ name, color, posts: [{ title, keyword, volume, template, wordCount, url, status }] }],
     links: [{ from, to, type }],
     meta: { totalPosts, totalClusters, totalLinks, estimatedWords }
   }

3. Replace the

   CLUSTER_DATA

   placeholder in the template with the actual JSON
4. Write the completed HTML file to the output directory
5. Inform user: "Open

   cluster-map.html

   in a browser to explore the interactive cluster map."

Strategy Import

--from strategy

1. Look for the most recent

   /seo plan

   output in the current directory (search for files matching

   *SEO*Plan*

   ,

   *strategy*

   ,

   *content-strategy*

   )
2. Parse markdown tables for: keywords, page types, content pillars, URL structures
3. Validate extracted data: check for duplicates, missing keywords, incomplete entries
4. Enrich with SERP data: run SERP overlap analysis on extracted keywords
5. Build cluster plan using the imported keywords as the starting set (skip Step 1)

/seo plan

Execution Workflow

/seo cluster execute

Check for claude-blog

Test: Does ~/.claude/skills/blog/SKILL.md exist?

1. Load

   references/execution-workflow.md

   for the full algorithm
2. Read

   cluster-plan.json

   from the current directory
3. Check for resume state: scan output directory for already-written posts
4. Execute in priority order: pillar first, then spokes by volume (highest first)
5. For each post, invoke the

   blog-write

   skill with cluster context:
   • Cluster role (pillar or spoke)
   • Position in cluster (cluster index, post index)
   • Target keyword and secondary keywords
   • Template type and word count target
   • Internal links to include (with anchors)
   • Links to receive from future posts (placeholder markers)
6. After each post is written, scan previous posts for backward link placeholders and inject the new post's URL
7. After all posts are written, generate the cluster scorecard

1. Generate detailed content briefs for each post in the cluster plan
2. Each brief includes:
   • Title and meta description
   • Primary keyword and secondary keywords
   • Template type and suggested structure (H2/H3 outline)
   • Word count target
   • Internal links to include (with anchor text)
   • Key points to cover
   • Competing pages to differentiate from
3. Write briefs to

   cluster-briefs/

   directory as individual markdown files
4. Inform user: "Install claude-blog to auto-create content. Briefs saved to

   cluster-briefs/

   ."

Cluster Scorecard

/seo cluster execute

Map Regeneration

/seo cluster map

1. Read

   cluster-plan.json

   from the current directory
2. Scan output directory and update post statuses (planned vs written)
3. Regenerate

   cluster-map.html

   with updated statuses
4. Report: posts written vs planned, link completion percentage

Output Files

cluster-plan.json

cluster-plan.md

cluster-map.html

cluster-briefs/

cluster-scorecard.md

Cross-Skill Integration

seo-plan

seo-content

seo-schema

seo-dataforseo

seo-google

/seo google report

Error Handling

--from strategy

/seo plan

/seo cluster plan

Security

• All URLs fetched via

  python scripts/fetch_page.py

  (SSRF protection via

  validate_url()

  )
• No credentials stored or transmitted
• Output files contain no PII or API keys
• DataForSEO cost checks run before every API call