openseo-keyword-clustering
Cluster keywords by search intent and map each cluster to an existing or proposed page, with cannibalization detection from Search Console. Use this skill when the user has a keyword list (saved set,
SKILL.mdskills/openseo-keyword-clustering/SKILL.md
GitHubOpenSEO 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
- Readiness + binding:
mktg seo status --json --fields readiness,catalog.endpointError,project. No binding →openseo-project-setupfirst.not_configured→ do lexical clustering with Exa context but label every cluster "SERP-unvalidated." For a ready state, verify live access with the freewhoamiMCP tool before paid calls. - Keyword source: prefer (a)
brand/keyword-plan.mdpopulated sections, (b)list_saved_keywordswith a tag, (c) GSC live data, (d) seed discovery viaresearch_keywords. Under 10 usable terms → simple map, no clustering ceremony.
OpenSEO MCP Tools
get_search_console_performancewithdimensions: ["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
- Assemble the candidate set from the source hierarchy above; dedupe and drop off-strategy terms.
- 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.
- Borderline terms: small
get_serp_resultsoverlap check. - Assign each cluster: existing URL (if supplied and fitting), new-page proposal, or do-not-target/later.
- Cannibalization check: GSC query+page data first; otherwise flag where two proposed pages share one intent.
- Write per-cluster briefs to
marketing/seo/clusters/<cluster-slug>.md: page type, searcher problem, required sections, internal-link targets, priority. - Optionally tag clusters with
save_keywordsafter confirmation. - Hand off:
seo-contentfor single pages,seo-machinefor 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:
| Cluster | Primary keyword | Secondary keywords | Intent | Target page | Priority | Notes |
|---|
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.
Close the loop
After writing files, log completion so mktg plan / mktg status count the work (bare mktg run only logs loaded):
mktg run openseo-keyword-clustering --complete --writes <paths written> --result success --json
Adapted from every-app/open-seo .agents/skills/keyword-clustering (MIT). Workflow upstream; mktg artifact paths, brand-memory reads, and handoff wiring added here.