SERP-based semantic topic clustering for content architecture planning. Groups keywords by actual Google SERP overlap (not text similarity), designs hub-and-spoke content clusters with internal link matrices, and generates interactive visualizations. Optionally executes content creation if antigravity-blog is installed. Use when user says "topic cluster", "content cluster", "semantic clustering", "pillar page", "hub and spoke", "content architecture", "keyword grouping", or "cluster plan".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
SERP-based semantic topic clustering for content architecture planning. Groups keywords by actual Google SERP overlap (not text similarity), designs hub-and-spoke content clusters with internal link matrices, and generates interactive visualizations. Optionally executes content creation if antigravity-blog is installed. Use when user says "topic cluster", "content cluster", "semantic clustering", "pillar page", "hub and spoke", "content architecture", "keyword grouping", or "cluster plan".
user-invokable
true
argument-hint
<seed-keyword or url>
license
MIT
metadata
{"author":"dotusmanali","original_author":"Lutfiya Miller (Pro Hub Challenge Winner)","version":"2.0.0","category":"seo"}
id
seo-cluster
domain
research
invoked_by
["seo-cluster","seo"]
depends_on
[]
Semantic Topic Clustering (v1.9.0)
Shared Data Cache
Step 0 -- Check shared data cache:
Before gathering, check .seo-cache/ for reusable context from related SEO skills.
Reference: ../seo/references/shared-data-cache.md for schemas and dependency map.
Check these cache files when present:
.seo-cache/site-meta.json for domain, business type, industry, and crawl context
.seo-cache/audit-scores.json for prior full-audit priorities
.seo-cache/pages/{url-slug}/page-analysis.json for page-level context when a URL is provided
If found: parse and use clearly valid fields (note "Using cached [X] from [date]")
If missing, corrupt, or irrelevant: continue with fresh evidence
If the user says "refresh" or "re-run": ignore cache reads and overwrite on write
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
Command
What it does
/seo cluster plan <seed-keyword>
Full planning workflow: expand, cluster, architect, visualize
/seo cluster plan --from strategy
Import from existing /seo plan output
/seo cluster execute
Execute plan: create content via antigravity-blog or output briefs
/seo cluster map
Regenerate the interactive cluster visualization
Planning Workflow
Step 1: Seed Keyword Expansion
Expand the seed keyword into 30-50 variants using WebSearch:
Related searches — Search the seed, extract "related searches" and "people also search for"
People Also Ask (PAA) — Extract all PAA questions from SERP results
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:
Group keywords by initial intent guess (reduces pairwise comparisons)
For each candidate pair within a group, WebSearch both keywords
Count shared URLs in the top 10 organic results (ignore ads, featured snippets, PAA)
Apply thresholds:
Shared Results
Relationship
Action
7-10
Same post
Merge into single target page
4-6
Same cluster
Group under same spoke cluster
2-3
Interlink
Place in adjacent clusters, add cross-links
0-1
Separate
Assign to different clusters or exclude
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 WebSearch for SERP data. Run python scripts/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 WebSearch.
Step 3: Intent Classification
Classify each keyword into one of four intent categories:
Intent
Signals
Include in Clusters?
Informational
how, what, why, guide, tutorial, learn
Yes
Commercial
best, top, review, comparison, vs, alternative
Yes
Transactional
buy, price, discount, coupon, order, sign up
Yes
Navigational
brand names, specific product names, login
No (exclude)
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:
Select the pillar keyword — Highest volume, broadest intent, most SERP overlap with other keywords
Group spokes into clusters — Each cluster is a subtopic area (2-5 clusters per pillar)
Assign posts to clusters — Each cluster gets 2-4 spoke posts
Select templates per post — Based on intent classification:
Intent Pattern
Template Options
Informational (broad)
ultimate-guide
Informational (how)
how-to
Informational (list)
listicle
Informational (concept)
explainer
Commercial (compare)
comparison
Commercial (evaluate)
review
Commercial (rank)
best-of
Transactional
landing-page
Set word count targets:
Pillar page: 2500-4000 words
Spoke posts: 1200-1800 words
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:
Link Type
Direction
Requirement
Spoke to pillar
spoke -> pillar
Mandatory (every spoke)
Pillar to spoke
pillar -> spoke
Mandatory (every spoke)
Spoke to spoke (within cluster)
spoke <-> spoke
2-3 links per post
Cross-cluster
spoke -> spoke (other cluster)
0-1 links per post
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:
Validate extracted data: check for duplicates, missing keywords, incomplete entries
Enrich with SERP data: run SERP overlap analysis on extracted keywords
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 /seo plan first, or provide a seed keyword for fresh clustering."
Execution Workflow
When /seo cluster execute is invoked:
Check for antigravity-blog
Test: Does skills/blog/SKILL.md exist in the plugin directory?
If antigravity-blog IS installed:
Load references/execution-workflow.md for the full algorithm
Read cluster-plan.json from the current directory
Check for resume state: scan output directory for already-written posts
Execute in priority order: pillar first, then spokes by volume (highest first)
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)
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 antigravity-blog is NOT installed:
Generate detailed content briefs for each post in the cluster plan
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
Write briefs to cluster-briefs/ directory as individual markdown files
Inform user: "Install antigravity-blog
to auto-create content. Briefs saved to cluster-briefs/."
Cluster Scorecard
Post-execution quality report. Run automatically after /seo cluster execute or
on demand via analysis of the output directory.
Metric
Target
How Measured
Coverage
100%
Posts written / posts planned
Link Density
3+ per post
Count internal links per post
Orphan Pages
0
Posts with < 1 incoming link
Cannibalization
0 conflicts
Check for duplicate primary keywords
Image Count
1+ per post
Posts with at least one image
Pillar Links
100%
All spokes link to pillar and vice versa
Cross-Links
80%+
Recommended spoke-to-spoke links implemented
Content Gaps
0
Planned posts that were skipped or incomplete
Map Regeneration
When /seo cluster map is invoked:
Read cluster-plan.json from the current directory
Scan output directory and update post statuses (planned vs written)
Regenerate cluster-map.html with updated statuses
Report: posts written vs planned, link completion percentage
Output Files
All outputs are written to the current working directory:
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
FLOW Framework Integration
For prompt-guided keyword research and gap analysis, use /seo flow find [url|topic] — FLOW's 5 find-stage prompts complement the SERP-overlap clustering methodology with structured discovery prompts.
Write to shared data cache
After completing all work, write a concise JSON summary to .seo-cache/ when the workflow produced durable findings.
Use the schemas and naming rules in ../seo/references/shared-data-cache.md; include at least cache_type, analyzed_at, source URL/domain, key findings, issues, recommendations, and tool limitations. Add .seo-cache/ to .gitignore if it is missing.
Extended Capabilities (from blog-cluster)
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 antigravity-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.
{"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 (antigravity-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.
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).
Parse the table. Extract the pillar row (marked P), the spoke rows, template assignments, target keywords, word counts, and link relationships.
Validate and enrich. Run SERP overlap validation (Plan Phase Step 2) on each keyword. Add volume estimates and verify cluster groupings semantically.
If SERP data contradicts the strategy table, flag the conflict; do not silently override the user's strategic intent.
Generate cluster-plan.json and cluster-map.html using the same outputs as the standard Plan Phase.
Present the converted plan with any SERP-based adjustments highlighted, and wait for user confirmation.
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
Pillar page first (so spokes can link to a known filename).
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).
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:
Scan all previously written posts in the cluster directory for [INTERNAL-LINK: keyword -> filename.md] markers that reference the just-written post.
Replace each match with a real markdown link: [keyword](filename.md).
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)
File
Phase
Format
cluster-plan.json
Plan
JSON
cluster-map.html
Plan
Static HTML + inline SVG, no JavaScript
pillar-<slug>.md
Execute
Markdown (or platform-detected format)
<spoke-slug>.md
Execute
Markdown (or platform-detected format)
images/<post-slug>-hero.png
Execute (optional)
PNG via seo-image-gen
cluster-scorecard.md
Execute
Markdown
Quality Gates
Gate
Check
Action on fail
Cluster minimum
At least 2 clusters with at least 2 posts each
Warn during plan; suggest expansion
Cannibalization
No two posts share primary keyword
Block execution; require plan adjustment
Link completeness
Every post has 3 or more incoming internal links
Warn in scorecard
Word count
Pillar at least 2,500 words; spokes at least 1,200 words
Pass to blog-write as a hard constraint
Intent diversity
At least 2 distinct intents across clusters
Warn in scorecard
Template diversity
At least 3 distinct templates across the cluster
Warn in scorecard
Error Handling
Scenario
Action
Seed keyword too broad (more than 50 keyword variants)
Suggest narrowing the focus before clustering.
Seed keyword too narrow (fewer than 5 keyword variants)
Offer a smaller cluster (pillar plus 2 to 3 spokes) or suggest broadening.
WebSearch unavailable
Fall back to Antigravity's reasoning for keyword expansion and grouping. Note the reduced accuracy in the scorecard.
blog-write fails for one post
Log, skip, continue. Mark the gap in the scorecard.
blog-write not installed
Return: "seo-cluster requires antigravity-blog. Install it before running this skill."
cluster-plan.json malformed
Validate JSON and report parse errors with line numbers.
User cancels execution
Save progress; resume on next invocation with already-written posts auto-detected.
nanobanana-mcp not configured
Skip hero image generation; warn once at start of execute, not per post.
Differentiation from related antigravity-blog skills
Skill
Role
What seo-cluster adds
blog-strategy
Plans 3 to 5 content pillars and draws hub-and-spoke diagrams as a strategic exercise
Performs SERP-based semantic clustering, then executes the plan into real, interlinked posts.
blog-calendar
Schedules publication dates around topic clusters
Does not build clusters or write posts; this skill does both.
blog-cannibalization
Detects keyword overlap in existing content
Diagnostic only. seo-cluster prevents cannibalization at the planning stage.
blog-write
Writes one post at a time
seo-cluster orchestrates many blog-write calls with shared cluster context and bidirectional linking.
blog-outline
Generates a single SERP-informed outline
seo-cluster generates an outline-equivalent across an entire cluster, then writes the posts.
seo-cluster is the general contractor: it analyzes the topic, draws the data-driven plan, and builds the entire structure from a single seed keyword.
