openseo-keyword-clustering

OpenSEO Keyword Clustering

Group keywords into page-level clusters and assign each to an existing URL, a new page proposal, or a do-not-target bucket. Output lands in marketing/seo/clusters/*.md (per-cluster briefs) and feeds seo-content / seo-machine with measured page targets.

On Activation

1. Catalog + binding: mktg catalog info openseo --json --fields configured and .seo/openseo.json for projectId. No binding → openseo-project-setup first. No OpenSEO at all → do lexical clustering with Exa context but label every cluster "SERP-unvalidated."
2. Keyword source: prefer (a) brand/keyword-plan.md populated sections, (b) list_saved_keywords with a tag, (c) GSC live data, (d) seed discovery via research_keywords. Under 10 usable terms → simple map, no clustering ceremony.

OpenSEO MCP Tools

• get_search_console_performance with dimensions: ["query","page"]: the cannibalization truth source — one query splitting impressions across multiple URLs means existing cannibalization, not theoretical risk.
• get_ranked_keywords: domain/page-driven clustering from exact ranking rows + URLs.
• get_serp_results: SERP-overlap validation for borderline terms (small batches, ≤10).
• list_saved_keywords / research_keywords: source sets.
• save_keywords: apply cluster tags ONLY after confirmation.

Workflow

1. Assemble the candidate set from the source hierarchy above; dedupe and drop off-strategy terms.
2. Cluster by intent and page type: same SERP intent + similar ranking pages belong together; different intent/buyer stage/SERP format splits. Lexical similarity is NOT evidence of same-page fit.
3. Borderline terms: small get_serp_results overlap check.
4. Assign each cluster: existing URL (if supplied and fitting), new-page proposal, or do-not-target/later.
5. Cannibalization check: GSC query+page data first; otherwise flag where two proposed pages share one intent.
6. Write per-cluster briefs to marketing/seo/clusters/<cluster-slug>.md: page type, searcher problem, required sections, internal-link targets, priority.
7. Optionally tag clusters with save_keywords after confirmation.
8. Hand off: seo-content for single pages, seo-machine for programmatic batches — both now have measured targets instead of vibes.

Output Format

Summary first: cluster count, pages to create, pages to update, cannibalization issues. Then:

Anti-Patterns

• Clustering by word similarity alone — because "best crm for dentists" and "crm pricing dentists" share words but not intent, and forcing them onto one page guarantees neither ranks. SERP intent wins; check overlap when unsure.
• Clustering tiny sets — because 6 keywords don't need a clustering framework, they need a paragraph. Under 10 terms, write a simple map.
• Theoretical cannibalization warnings without data — because crying cannibalization on every overlapping term freezes page production; GSC query+page splits are the only proof. No GSC → label it "potential," not "confirmed."
• Retagging saved keywords without confirmation — because tags are shared account state; a bulk retag can destroy someone else's organization. Confirm first.
• Producing clusters with no page assignment — because a cluster without a target page is trivia. Every cluster ends in an existing URL, a new proposal, or an explicit do-not-target decision.

Adapted from every-app/open-seo .agents/skills/keyword-clustering (MIT). Workflow upstream; mktg artifact paths, brand-memory reads, and handoff wiring added here.