Topic clustering groups related search queries into pages and connected content hubs. Claude SEO compares shared URLs in dated result snapshots, adds intent and page-scope heuristics, and proposes hub-and-spoke architectures with internal link matrices. It outputs an interactive cluster map for human review.
By Daniel Agrici · Last updated:
CONTRIBUTED BY LUTFIYA MILLER · PRO HUB CHALLENGE WINNER · original repo
The skill starts from a seed keyword and expands it into 30 to 50 variants using related searches, People Also Ask, long-tail modifiers, and intent modifiers. Then it runs the part most other tools skip: for every candidate pair, it pulls the top 10 organic SERP results for both keywords and measures how many URLs overlap.
Claude SEO's default review bands treat 7 to 10 shared URLs as a same-page review, 4 to 6 as a shared-cluster review, 2 to 3 as weak adjacency, and 0 to 1 as likely separation. These are vendor heuristics, not Google thresholds. The reviewer should consider locale, device, date, query features, audience, and page purpose before approving the hub-and-spoke plan.
The skill bundles six things most teams stitch together from separate tools. SERP-overlap scoring is the core; the other five make the output usable for content production.
01
SERP-OVERLAP CLUSTERING
Measures shared URLs between dated search-result snapshots. Overlap becomes one review input alongside language, intent, page scope, locale, device, and time.
02
INTENT CLASSIFICATION
Proposes informational, commercial, transactional, or navigational labels from the observed result mix. The labels guide, but do not decide, page format and template review.
03
HUB-AND-SPOKE ARCHITECTURE
Designs the cluster as a hub (pillar page) plus 3-12 spokes (deep articles). Suggests URLs, slugs, and content templates per intent.
04
INTERNAL LINK MATRIX
Generates the recommended internal linking structure: hub-to-spoke, spoke-to-spoke, sibling clusters. Anchor text suggestions per link.
05
INTERACTIVE CLUSTER MAP
Outputs cluster-map.html with every cluster as a node sized by total search volume. Drop in browser, no build step. Share with stakeholders.
06
CONTENT EXECUTION
If claude-blog is installed, /seo cluster execute hands off to write the hub and spokes with the agreed link matrix. Otherwise outputs editorial brief.
// USAGE
How do you run topic clustering?
Commands
Command
What it does
/seo cluster <seed>
Full plan: expansion, SERP overlap, intent, hub-and-spoke, link matrix, map
/seo cluster plan <seed>
Architecture only, no execution. Outputs cluster-plan.json and cluster-plan.md
/seo cluster execute <plan-file>
Hand off to claude-blog. Writes hub and spokes with the agreed link matrix
/seo cluster map <plan-file>
Regenerate cluster-map.html, refresh post statuses (planned vs written)
How SERP-Overlap Scoring Works
For each candidate keyword pair, the skill fetches the top 10 organic results (ignoring ads, featured snippets, and PAA) for both queries and computes a Jaccard-like score over the URL sets. Concretely: if keyword A has top-10 URLs {a1...a10} and keyword B has {b1...b10}, the score is |A ∩ B|, the count of shared URLs. The score maps directly to a clustering action:
Shared URLs
Relationship
Action
7-10
Strong observed overlap
Review whether one page can satisfy both queries
4-6
Moderate observed overlap
Review a shared cluster with separate page scopes
2-3
Weak observed overlap
Inspect adjacency before proposing links
0-1
Little observed overlap
Usually separate, subject to manual review
For 40 keywords, full pairwise comparison would be 780 calls. The skill optimizes by pre-grouping with intent guesses (4 groups of ~10 = 180 comparisons) and only cross-checking group boundaries. Long-tail variants of the same head term are assumed to share a cluster without an explicit SERP call.
Output Files
All outputs land in the current working directory:
cluster-plan.json: machine-readable cluster plan with keywords, clusters, links, and meta
cluster-plan.md: human-readable cluster plan summary
cluster-map.html: interactive SVG visualization, no build step required
cluster-briefs/: per-post content briefs, generated when claude-blog is not installed
When the DataForSEO MCP server is installed, the skill uses serp_organic_live_advanced instead of WebSearch for higher-quality SERP data. A cost check runs before every batch via claude-seo run dataforseo_costs.py check <endpoint> [--count N]. If the budget is blocked, the skill falls back to WebSearch automatically. See /seo dataforseo for setup.
// FAQ
What should you know about topic clustering?
Text similarity measures language, while SERP overlap compares the URLs returned in a dated search snapshot. Overlap adds useful evidence about result-set similarity, but it varies by time, location, device, and provider. Claude SEO combines it with context and manual review instead of treating it as a Google intent label or ranking signal.
An interactive HTML file (cluster-map.html) with each cluster as a node, sized by total search volume. Edges connect related clusters. Each cluster expands to show its keywords, suggested URL, intent classification, and recommended internal links to sibling clusters. Drop the file in any browser, no build step. Useful for content team kickoffs and stakeholder reviews.
If you have claude-blog installed, yes. /seo cluster plan generates the architecture; /seo cluster execute hands off to claude-blog to write hub and spoke posts with the agreed internal linking matrix. If claude-blog is not installed, the skill outputs an editorial brief you can hand to a writer.
The skill proposes intent labels from result types, query wording, and search features in the captured snapshot. Articles can suggest informational needs, comparisons can suggest commercial research, and product pages can suggest transactions. These are reviewable inferences, not permanent labels supplied by Google.
Lutfiya Miller, winner of the AI Marketing Hub Pro Hub Challenge. The original implementation is at github.com/Drfiya/semantic-cluster-engine. The submission was reviewed, security-audited, and integrated into Claude SEO v1.9.0 with Lutfiya's permission.
// RELATED SKILLS
EXPLORE MORE
FLOW FRAMEWORK
FLOW's Find stage handoff: clusters turn discovered keywords into a reviewable content architecture.
