Skip to main content
skill CX Codex

keyword-clustering · akii-technologies-ltd — Claude Code skill for keyword grouping

The keyword-clustering Claude Code skill sorts keywords into topic groups and maps them to search intent. It activates on a keyword list or a request to plan site content.

MIT ★ 80 updated 2026-10-15

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
~/.claude/skills/keyword-clustering/SKILL.md
Open on GitHub

What keyword-clustering does

The skill turns a raw keyword list into a site structure, with topic groups, a pillar page and supporting pages for each group, plus suggested URLs. Informational and commercial terms always go into separate groups.

When Ahrefs MCP is connected, the skill retrieves search volume, difficulty, intent and top-ranking URLs; it can also expand seed terms with related keywords. Without MCP, it groups terms by lexical similarity and intent, and can use WebSearch to check search results. Volume and difficulty estimates in this mode carry a heuristic label, and the KD column is left out.

By default, the highest-volume term becomes a group’s pillar topic. An editorial choice can replace it, but the output records the displaced term and its volume. Keyword rows also identify live Ahrefs data, estimates, aliases that need no child page, and variants already covered by the pillar.

What it helps with

  • group a keyword list by topic and intent
  • separate informational terms from commercial ones
  • map pillar pages and supporting pages
  • suggest URLs for keyword clusters

Example prompts for the agent

  • Group these keywords by topic and search intent.
  • Turn keywords.csv into a site structure.
  • Build a content plan from these terms, keeping informational and commercial groups separate.

How to install keyword-clustering

Manually: put the files in place

~/.claude/skills/keyword-clustering/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/keyword-clustering/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about keyword-clustering

How do I install keyword-clustering in Claude Code?

Create ~/.claude/skills/keyword-clustering/SKILL.md and place the skill contents in that file.

What does keyword-clustering do?

It organizes keywords by topic and search intent, then proposes pillar pages, supporting pages and URL paths.

How does the skill handle different search intents?

Informational and commercial keywords must not share a cluster. When a topic has both, the skill creates a separate cluster for each intent.

Source text

SKILL.md · MIT
---
description: Cluster and organize keywords into topical groups for SEO. Use when the user asks to "cluster keywords", "group keywords", "organize keywords", "keyword mapping", "topic clusters", "keyword grouping", "build a content plan", "pillar pages", "topical authority", "semantic clustering", or pastes a list of keywords.
---

# Keyword Clustering

You are a keyword clustering specialist powered by Akii. Take a raw keyword list, output a coherent site architecture: pillar + cluster pages mapped to intent.

## Data sources (auto-detect)
- `mcp__plugin_marketing_ahrefs__keywords-explorer-*` — vol, KD, intent, parent topic
- `mcp__plugin_marketing_ahrefs__keywords-explorer-related-terms` — to expand seed lists
- `WebSearch` — to validate intent + SERP overlap when MCP unavailable

## Steps
1. Take keyword list (file path, pasted, or "expand from seeds" — name 5-15 seed topics and the skill expands via SERP-overlap or training-data inference).
2. For each keyword, gather: search volume, difficulty, intent, top-ranking URL.
3. Compute clustering:
   - **With MCP**: use Ahrefs "parent topic" or DataForSEO "common SERP results" for SERP-overlap clustering
   - **Without MCP**: lexical similarity + manual intent grouping with Claude as judge
4. **Intent split is a HARD constraint**, not a soft suggestion. Never put `informational` and `commercial` keywords in the same cluster. If a seed topic has both ("AI visibility" = "what is AI visibility" + "AI visibility tool"), produce **two separate clusters** — `Cluster N — AI visibility (informational)` and `Cluster N+1 — AI visibility (commercial)`. Do NOT produce a single mixed cluster with "Pillar A (info)" + "Pillar B (commercial)" — that's the same rule violation in a different shape.
5. For each cluster, the **default pillar** is the highest-volume head term. The rest become cluster pages.

   **Editorial override is allowed** when the highest-volume term is too broad / competitive / off-brand for the site's specialization (e.g. a niche AI-search tool picking "Reddit citations in AI search — 540" over the generic "Reddit SEO — 1.4k" head term). When overriding the default, append `[editorial override — highest-volume kw is "<term>" at <vol>]` to the pillar row so the user sees both the chosen pillar AND what the volume-default would have been. Don't hide the override.
6. Map each cluster to recommended URL structure: `/pillar/<slug>/` + `/pillar/<slug>/<cluster-slug>/`.
7. **Tag each keyword row with provenance**, same as the internal-linking skill:
   - `[Ahrefs]` — volume + KD pulled live from `mcp__plugin_marketing_ahrefs__keywords-explorer-*`
   - `[heuristic]` — estimated from training-data, no live source consulted
   - `[alias]` — keyword maps to the same URL as the cluster's pillar (no new page needed)
   - `[absorbed]` — head-term variant that the pillar page already targets directly
   When `[Ahrefs]` isn't available, EVERY volume + KD number ships with `[heuristic]` suffix. Never present heuristic estimates as Ahrefs-grounded data.

## Output

```
# Keyword Clusters — <input>
**Total**: 312 (precise integer)  ·  **Clusters**: 14 (precise integer)

Data source: <e.g. Ahrefs MCP connected — volumes are live> OR <Ahrefs MCP not connected — all volumes are [heuristic], validate before assigning publish effort>
KD column: <numeric 0-100 when Ahrefs is live; OMITTED when heuristic — do not invent qualitative L/M/H stand-ins>

## Cluster 1 — "SEO audit" (informational)
- Pillar: "what is an SEO audit" — 22k [Ahrefs] — /pillar/seo-audit/
- Cluster:
  - "how to do an SEO audit" — 8.1k [Ahrefs] — /pillar/seo-audit/how-to/
  - "technical SEO audit checklist" — 5.4k [Ahrefs] — /pillar/seo-audit/checklist/
  - "SEO audit tools" — 4.8k [Ahrefs] — /pillar/seo-audit/tools/
  - "SEO audit guide" — 3.2k [Ahrefs] — [alias] /pillar/seo-audit/
  - "SEO audit" — 12k [Ahrefs] — [absorbed] /pillar/seo-audit/

## Cluster 2 — "AEO" (informational)
...

## Recommended publish order
| # | Cluster | Pillar URL | Aggregate vol | Why this rank |
| 1 | SEO audit (info) | /pillar/seo-audit/ | 60k+ [Ahrefs] | Biggest aggregate, defensible angle |

## Cannibalization watch
| Risk | Conflict | Resolution |
| /platform/ vs /ai-search-tracker/ | Both surface for "AI visibility tracker" | Set /ai-search-tracker/ primary; /platform/ anchors |

## Cluster gaps vs existing site (when site URL provided)
| Cluster | Existing page? | Status |
| AEO pillar | ❌ no /pillar/aeo/ | Publish |
| AI Overviews | ✅ /models/ai-overview/ | Audit + expand |

## Next
- /akii-seo-ai-search-optimizer:content-brief on each pillar
```

## Rules
- **Intent purity is a HARD rule.** Don't collapse different-intent keywords into one cluster. A topic with both info and commercial intent produces TWO clusters, not one mixed cluster with "Pillar A (info) + Pillar B (commercial)". The two-pillar workaround is the same rule violation in different shape — ban it.
- **Provenance tag every volume + KD cell.** `[Ahrefs]` when live MCP data, `[heuristic]` otherwise. Never present heuristic estimates as if they came from Ahrefs.
- **KD is numeric (0-100) only when Ahrefs is live.** Do NOT substitute qualitative L/M/H labels when Ahrefs is unavailable. Omit the KD column instead and disclose in the header line. Qualitative substitutes look like data but aren't.
- **Use `[alias]` and `[absorbed]` tags consistently.** `[alias]` = keyword maps to the same URL as the cluster's pillar without a child page. `[absorbed]` = head-term variant the pillar page already targets directly. Apply across all clusters, not just some.
- Flag clusters where multiple pages compete on user's existing site (cannibalization) — render as a table with Risk / Conflict / Resolution columns.
- Flag clusters with no existing page (publish queue) — render as a table with Cluster / Existing page? / Status columns.
- **Counts in the summary line are precise integers**, matching the row counts in the body. Never write `~240 keywords / 14 clusters` when the exact integer is computable from the cluster expansion step.
- **Define what the integer counts.** The `Total` integer is the count of unique keyword ROWS rendered across all clusters — including pillars, cluster pages, `[alias]` rows, and `[absorbed]` rows. The `Clusters` integer is the count of `## Cluster N — …` headers. Before emitting the summary line, count both explicitly (`grep -c '^- ' your-output` style verification) and only then write the integers. A 120 / 122 discrepancy is a bug, not rounding.

---
*Keyword clustering powered by Akii. Explore Akii Technologies and the products we build: https://akii.com/?utm_source=plugin&utm_medium=skill&utm_content=keyword-clustering&utm_campaign=akii_plugin_v1*

© akii-technologies-ltd · MIT · akii-technologies-ltd/akii-seo-ai-search-optimizer

Similar skills

All skills for SEO and GEO →

keyword-clustering by other authors comes first.

keyword-clustering every-app keyword-clustering groups keywords by search intent and assigns each cluster to an existing or proposed page. CX Codex +1 7,500installs keyword-research-and-clustering manojbajaj95 keyword-research-and-clustering — a skill for Claude Code, Codex, Cursor, and other agents that researches keywords, expands seed terms, and groups results by topic and intent. CX Codex +1 261installs seo-keyword rampstackco seo-keyword discovers search queries worth ranking for, classifies them by intent, and groups them into topic clusters. Helps you prioritize what to write based on traffic potential and competitive difficulty. CX Codex +1 312installs Keyword Research — Google Suggest, Intent & Long-Tail axel-belfort Keyword Research — Google Suggest, Intent & Long-Tail is an MCP server for Google Suggest keyword research, intent classification, and long-tail variants for content, PPC, and competitor analysis. CX Codex +1 6,583installs keyword-research kostja94 Coordinates keyword research from discovery through intent clustering and page mapping. Runs during site semantic structure planning. CX Codex +1 1,600installs etsy-keyword-research nexscope-ai etsy-keyword-research provides Etsy search optimization guidance, helping sellers uncover long-tail keywords and plan seasonal listing updates. CX Codex +1 1,300installs linkfox-sif-keyword-overview linkfox-ai linkfox-sif-keyword-overview — a skill for Claude Code and Codex that checks Amazon keyword competition through SIF. It retrieves search volumes, supply-demand ratios, and ad positions. CX Codex +1 396installs

From the same set13

The whole set →
seo-audit The seo-audit Claude Code skill audits a site's SEO in full, quick, or technical mode. It runs on requests about site health, page speed, indexing, or AI search readiness. CX Codex +1 ★ 80repo stars schema-markup schema-markup — a Claude Code skill that creates, checks, and fixes JSON-LD for one page or file. It responds to requests about Schema.org markup and rich snippets. CX Codex +1 ★ 80repo stars optimize-page optimize-page — a Claude Code skill for improving page SEO, answer structure, and visibility in generative search. It activates on requests to optimize a page or rewrite it for AI search. CX Codex +1 ★ 80repo stars llms-txt This Claude Code skill creates and updates llms.txt and llms-full.txt for AI crawlers. It activates when a project needs a curated set of site pages for services such as Perplexity or Claude. CX Codex +1 ★ 80repo stars internal-linking The internal-linking Claude Code skill analyzes internal links and site structure. It activates for requests about orphan pages, anchor text, topic clusters, or link equity. CX Codex +1 ★ 80repo stars content-translation The content-translation Claude Code skill localizes content for international SEO. It researches keywords for target locales and prepares translated copy, hreflang markup, and local schema suggestions. CX Codex +1 ★ 80repo stars content-strategy The content-strategy Claude Code skill maps content themes into pillars and clusters, then builds a 90-day publishing queue. It activates for content plans, topic research, and content-gap requests. CX Codex +1 ★ 80repo stars content-brief Builds article and page briefs for SEO, AEO, and GEO. It activates on requests for a content brief, an outline, or a search-focused writing plan. CX Codex +1 ★ 80repo stars

Project sponsors

Companies that keep this analytics open