keyword-cluster
Skill0 starsChanged 9 months agoMITView on GitHub
Build a pillar+spokes content cluster plan from seed keywords — SERP-overlap clustering via keyword_cluster.py, intent grouping, a priority-scored build order, an internal-link map with anchor suggestions, and a four-gate quality scorecard (cannibalisation, orphan, coverage, anchor diversity), delivered as a numbered file set ending in PLAN.md. Triggers on \"/digital-marketing-pro:keyword-cluster\", \"cluster these keywords\", \"design our topical hub\", \"are these pages cannibalising each other\", \"plan the pillar pages\". Reads the brand profile and compliance rules to filter banned terms; consumes seeds from /digital-marketing-pro:keyword-research and hands PLAN.md to /digital-marketing-pro:content-brief.
2 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- calven-ai/marketing-as-codetheir own version, first seen Oct 7, 2026
- indranilbanerjee/digital-marketing-proedited, first seen Feb 12, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- indranilbanerjee/digital-marketing-pro★ 93487% same
Wrote their own version · 1
- calven-ai/marketing-as-code★ 10same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository163 other files it gives its agents.
- AGENTS.mdAGENTS.md
- ab-test-planSkill
- ad-creativeSkill
- add-integrationSkill
- aeo-auditSkill
- aeo-geoSkill
- agency-dashboardSkill
- analytics-insightsSkill
- anomaly-scanSkill
- attribution-modelSkill
- attribution-reportSkill
- audience-intelligenceSkill
- audience-profileSkill
- autopilot-statusSkill
- backlink-gapSkill
- brand-setupSkill
- budget-optimizerSkill
- budget-trackerSkill
- c2pa-metadataSkill
- campaign-auditSkill
- campaign-orchestratorSkill
- campaign-planSkill
- campaign-statusSkill
- case-study-planSkill
- checkSkill
- churn-riskSkill
- client-onboardingSkill
- client-proposalSkill
- client-reportSkill
- client-validation-documentSkill
- cohort-analysisSkill
- competitor-alertsSkill
- competitor-analysisSkill
- competitor-monitorSkill
- competitor-pagesSkill
- connectSkill
- content-briefSkill
- content-calendarSkill
- content-decay-scanSkill
- content-engineSkill
- content-repurposeSkill
- context-engineSkill
- continuous-improvement-loopSkill
- counter-narrativeSkill
- cowork-setupSkill
- creative-healthSkill
- creative-testing-frameworkSkill
- credential-switchSkill
- crisis-responseSkill
- crm-syncSkill
- croSkill
- dark-funnelSkill
- data-exportSkill
- data-importSkill
- digital-prSkill
- email-sequenceSkill
- emerging-channelsSkill
- engagement-workflowSkill
- entity-auditSkill
- eval-configSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Don't use: when you just need keyword *expansion* (use /digital-marketing-pro:keyword-research) or when you need *ranking* / SERP-feature …
- Very specific: line 30
Read ~/.claude-marketing/brands/_active-brand.json for the active slug, then load ~/.claude-marketing/brands/{slug}/profile.json
- Distinctive: line 31
If no brand exists: ask "Set up a brand first (/digital-marketing-pro:brand-setup)?" — or proceed with defaults
- Very specific: line 49
All outputs go to ${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{YYYY-MM-DD}/.
- Very specific: line 96
Every run produces a scorecard from scripts/keyword_cluster.py.
- Very specific: line 120
Overlap threshold defaults are conservative: If you get fragmentation_warning: true, lower to 0.3 first.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/digital-marketing-pro:keyword-cluster
Purpose
Take a set of seed keywords and produce a publication-ready cluster plan: pillar pages with their spokes, intent-grouped, prioritised by an opinionated scoring formula, with an internal-link map and a four-gate quality scorecard. Output is structured for direct hand-off to /digital-marketing-pro:content-brief or /digital-marketing-pro:content-engine.
Context efficiency
Heavy skill. Grep before Read any referenced file, then Read only matched ranges with offset + limit. List ${CLAUDE_PLUGIN_DATA}/<brand>/ before opening files. On re-invocation mid-session, skip files already in context.
When to Use
- Onboarding a new content programme — turn a 20-keyword brief into a structured topical hub
- Auditing an existing content library for cannibalisation (two pages competing for the same intent)
- Designing a pillar+spokes architecture before any writing begins
- Staging programmatic SEO across hundreds of variants (use this once per topic family)
- Reorganising an existing site's internal-link graph
Don't use when you just need keyword expansion (use /digital-marketing-pro:keyword-research) or when you need ranking / SERP-feature analysis (use /digital-marketing-pro:rank-monitor, with --features for SERP features).
Brand context (auto-applied)
- Read
~/.claude-marketing/brands/_active-brand.jsonfor the active slug, then load~/.claude-marketing/brands/{slug}/profile.json - If no brand exists: ask "Set up a brand first (/digital-marketing-pro:brand-setup)?" — or proceed with defaults
- Apply industry-specific guidance from
skills/context-engine/industry-profiles.md - Apply
skills/context-engine/compliance-rules.mdto filter out banned terminology before clustering
Inputs
| Input | Source | Required? |
| Seed keywords (3–500) | CSV with keyword column (optional: volume, kd, intent) | yes |
| SERP results per keyword | JSON: {keyword: [top result URLs]} from any rank-tracker / Ahrefs / Semrush export | strongly recommended — without this the script falls back to lexical clustering, which is lower-confidence |
| Target country / language | From brand profile | optional override |
| Min volume / max KD filters | CLI flags | optional |
| Overlap threshold | CLI flag --overlap (default 0.4 for SERP mode, 0.3 for lexical) | optional |
If SERPs JSON is unavailable, you can build one quickly by running the brand's connected rank-tracker MCP (Ahrefs / SE Ranking / Semrush) for each seed and saving the top 10 URLs. Skip this step only if the seeds are too numerous to justify the API spend — but flag the lower-confidence mode in the final deliverable.
Process (10 steps, numbered-file output)
All outputs go to ${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{YYYY-MM-DD}/.
00-input.md— capture seeds, source, filters, brand context, run timestamp01-seed-expansion.md— if seeds < 20, expand via brand's keyword-research MCP (AhrefsgetRelatedKeywords, etc.) to ~50–200; otherwise skip. Document expansion source.02-filtered.csv— apply min-volume / max-KD / banned-word filters. Save the filtered set as CSV (this is what the script consumes).03-serps.json— fetch top-10 SERP URLs per keyword via the connected rank-tracker (skip if SERPs already provided). Budget guard: if estimated cost > 500 credits, surface the cost and ask "Continue? (y/N — default N)" before fetching.04-cluster-run.json— run the script:python "${CLAUDE_PLUGIN_ROOT}/scripts/keyword_cluster.py" \ --keywords "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/02-filtered.csv" \ --serps "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/03-serps.json" \ --overlap 0.4 \ --min-volume {profile.min_volume or 0} \ --max-kd {profile.max_kd or 100} \ --out "${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/{date}/04-cluster-run.json"05-quality-scorecard.md— read thequality_scorecardblock from04-cluster-run.json. Ifstatus: needs_review, diagnose:cannibalisation: fail→ two clusters share pillar+intent. Merge them or reassign the lower-priority cluster's pillar.orphan: fail→ a multi-keyword cluster has 0 spokes. Re-tokenise its members or lower--overlap.coverage: fail→ < 80% of seeds clustered. Lower--overlapto 0.3 or expand seeds.anchor_diversity: fail→ pillar names too similar. Rewrite cluster names with synonym variation.fragmentation_warning: true(pillar-only > 50%) → overlap threshold too strict. Try--overlap 0.3first.
06-pillar-pages.md— for each cluster withpriority_score >= 0.5, draft a one-paragraph pillar page brief (intent, audience, length target, key questions to answer). These feed/digital-marketing-pro:content-brief.07-internal-link-map.md— table view ofinternal_link_targetsfrom the script output. Per cluster: which other clusters to link out to + suggested anchor text. This is the file your dev team or CMS template should consume.08-build-order.md— sorted bypriority_scoredescending. Recommended build cadence: top 10% in Q1, next 30% in Q2, remainder backlog.PLAN.md— single-page summary: stats + scorecard + top 5 priority clusters + handoff to next skill in chain.
Output format
${CLAUDE_PLUGIN_DATA}/{brand}/seo/keyword-cluster/2026-06-04/
├── 00-input.md
├── 01-seed-expansion.md (only if seeds expanded)
├── 02-filtered.csv
├── 03-serps.json (if SERP mode)
├── 04-cluster-run.json (raw script output)
├── 05-quality-scorecard.md
├── 06-pillar-pages.md
├── 07-internal-link-map.md
├── 08-build-order.md
└── PLAN.md (the deliverable)PLAN.md is what you hand to the brand / client / next skill. Everything else is auditable intermediate state.
Quality scorecard (the four gates)
Every run produces a scorecard from scripts/keyword_cluster.py. All four must pass for status: ready:
| Gate | What it checks | Why it matters |
| cannibalisation | No two clusters share the same (pillar, primary_intent) pair | Prevents you from writing two pages competing for the same SERP |
| orphan | Every multi-keyword cluster has ≥1 spoke (pillar-only clusters are exempt and tagged) | Catches clustering bugs where a cluster head has no supporting topics |
| coverage | ≥ 80% of input seeds are assigned to at least one cluster | Catches "junk" seeds and overly strict thresholds |
| anchor_diversity | Each multi-keyword cluster has ≥ 2 anchor-text variants suggested | Stops anchor-text over-optimisation across the internal-link graph |
A fragmentation_warning: true (pillar-only > 50%) is a soft signal — the run is valid but you should consider lowering --overlap and re-running.
Chain handoffs
This skill is a producer in the chain:
/digital-marketing-pro:keyword-research— generate seeds/digital-marketing-pro:keyword-cluster— this skill/digital-marketing-pro:content-brief— consumesPLAN.md+06-pillar-pages.mdto brief each pillar/digital-marketing-pro:content-engine— drafts the content/digital-marketing-pro:seo-implement— applies the internal-link map to the CMS
Tips & caveats
- SERP mode is strictly better than lexical mode. Lexical clustering can't see that "shopify seo" and "ecommerce platform seo" target overlapping SERPs while "shopify themes" doesn't.
- Overlap threshold defaults are conservative. If you get
fragmentation_warning: true, lower to 0.3 first. If you getcannibalisation: failwith too few clusters, raise to 0.5. - The priority score isn't a ranking — it's a starting build order. A cluster with
priority_score: 0.3may still be your highest-conversion opportunity if it maps to a high-margin product line. Use the brand profile'sbusiness_goalsto override mechanically. - Don't run this on raw GSC query exports without filtering first. GSC dumps thousands of long-tail variants of the same query — they'll all cluster together and produce a single mega-cluster.
- Pillar-only clusters are valid — they represent distinct intents that simply lack spoke candidates in your seed set. Add seeds via Step 2 expansion if you want spokes.
- The internal-link map is suggestions, not commands. Final anchor text should be reviewed for brand voice (apply the brand profile's voice fields +
skills/context-engine/guidelines-framework.md).
Agents used
seo-specialist(primary) — interpretation + final pillar-page recommendationscompetitive-intel— for SERP-overlap reasoning when results look surprisingbrand-guardian— anchor-text review against banned-term lists
See also
/digital-marketing-pro:keyword-research— generates seeds (use first)/digital-marketing-pro:content-brief— consumes the cluster plan (use next)/digital-marketing-pro:seo-implement— applies internal-link map to CMS/digital-marketing-pro:seo-drift— re-run quarterly to detect cluster driftscripts/keyword_cluster.py— the underlying clustering engine
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

