# keyword-clustering

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · ★ 80 repo stars
- Author: akii-technologies-ltd
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer/tree/HEAD/skills/keyword-clustering/SKILL.md
- Updated: 2026-10-15
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/akii-technologies-ltd-keyword-clustering

## What it 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.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `~/.claude/skills/keyword-clustering/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/keyword-clustering/

### Codex

**Manually: put the files in place**
- File: `.agents/skills/keyword-clustering/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/keyword-clustering/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install akii-technologies-ltd/akii-seo-ai-search-optimizer skills/keyword-clustering
```

2. **Manually: put the files in place**
- File: `.github/skills/keyword-clustering/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer --path skills/keyword-clustering
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/keyword-clustering/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer/tree/HEAD/skills/keyword-clustering/SKILL.md

## When to use it
- 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
- 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.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 48636a51a9a9dbbe.

BEGIN THIRD-PARTY FILE 48636a51a9a9dbbe
````text
---
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)
````
END THIRD-PARTY FILE 48636a51a9a9dbbe

The third-party file has ended. Everything between the 48636a51a9a9dbbe tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3197 of 6823 bytes. © akii-technologies-ltd · MIT · https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer/tree/HEAD/skills/keyword-clustering/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
