yuzushi-dev/hermes-seo/seo-cluster

Semantic Topic Clustering

SERP-overlap-driven keyword clustering for content architecture. Groups keywords by how Google actually ranks them (shared top-10 results), not by text similarity. Designs hub-and-spoke content clusters with internal link matrices and generates interactive cluster map visualizations.

Scripts: Located at the plugin root scripts/ directory.

Quick Reference

Planning Workflow

Step 1: Seed Keyword Expansion

Expand the seed keyword into 30-50 variants using web_search:

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"

Deduplication: Normalize variants (lowercase, strip articles), remove exact duplicates. Target: 30-50 unique keyword variants. If under 30, run a second expansion pass with the top PAA questions as seeds.

Step 2: SERP Overlap Clustering

This is the core differentiator. Load references/serp-overlap-methodology.md for the full algorithm.

Process:

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

Optimization: With 40 keywords, full pairwise = 780 comparisons. Instead:

• 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)

DataForSEO integration: If DataForSEO MCP is available, use serp_organic_live_advanced instead of web_search for SERP data. Run hermes seo run dataforseo_costs.py check serp_organic_live_advanced --count N before each batch. If "status": "needs_approval", show cost estimate and ask user. If "status": "blocked", fall back to web_search.

Step 3: Intent Classification

Classify each keyword into one of four intent categories:

Remove navigational keywords from clustering. Flag borderline cases for manual review. Keywords can have mixed intent (e.g., "best CRM software" is both commercial and informational) -- classify by dominant intent.

Step 4: Hub-and-Spoke Architecture

Load references/hub-spoke-architecture.md for full specifications.

Design the cluster structure:

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

1. 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

Design the bidirectional linking structure:

Rules:

• 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

Generate the link matrix as a JSON adjacency list:

{
  "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

Generate cluster-map.html using the template at templates/cluster-map.html.

1. read_file 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 } } ``

1. Replace the CLUSTER_DATA placeholder in the template with the actual JSON
2. write_file the completed HTML file to the output directory
3. Inform user: "Open cluster-map.html in a browser to explore the interactive cluster map."

Strategy Import

When invoked with --from strategy:

1. Look for the most recent hermes-seo:seo-plan output in the current directory (search for

files matching *SEO*Plan*, *strategy*, *content-strategy*)

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

If no strategy file is found, prompt the user: "No existing SEO plan found in the current directory. Run hermes-seo:seo-plan first, or provide a seed keyword for fresh clustering."

Execution Workflow

When hermes-seo:seo-cluster execute is invoked:

Check for a compatible writing skill

Use Hermes skills_list to discover whether a blog-writing or long-form content skill is available. If one is available, load it with skill_view(name="<exact skill name from skills_list>") and confirm it supports drafting full articles before using it. The writing skill can be called inline or through delegate_task; pass each post's cluster role, keyword, template, word count, internal links, and outline. Execute in priority order: pillar first, then spokes by volume (highest first). After each post is written, scan previous posts for backward-link placeholders and inject the new post's URL. After all posts are written, generate the cluster scorecard.

If no compatible writing skill is available, continue with the workflow below and produce complete content briefs. Do not check Claude-specific directories or assume a writing skill is installed.

Brief-only workflow

1. Generate detailed content briefs for each post in the cluster plan.
2. Include in each brief:

• 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

1. Use write_file to save briefs in cluster-briefs/ as individual Markdown files.
2. Tell the user that the briefs are ready and that a compatible writing skill can be installed or enabled later for article drafting.

Cluster Scorecard

Post-execution quality report. Run automatically after hermes-seo:seo-cluster execute or on demand via analysis of the output directory.

Map Regeneration

When hermes-seo:seo-cluster map is invoked:

1. read_file 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

All outputs are written to the current working directory:

Cross-Skill Integration

After cluster planning or execution completes, offer: "Generate a PDF report? Use hermes-seo:seo-google report"

Error Handling