git:20260520.e3d2b4e to git:20260526.c11b6b8

34 added, 13 removed. Audit B to B.

---

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 or pasted).

+ 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. Constraint: **intent type must match** within a cluster. Never cluster "buy X" with "what is X" even if semantically near.

+ 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, pick highest-volume head term → **pillar candidate**. Rest → cluster pages.

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 · **Clusters**: 14

+ **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 vol — /pillar/seo-audit/

+ - Pillar: "what is an SEO audit" — 22k [Ahrefs] — /pillar/seo-audit/

- Cluster:

- - "how to do an SEO audit" — 8.1k — /pillar/seo-audit/how-to/

- - "technical SEO audit checklist" — 5.4k — ...

- - "SEO audit tools" — 4.8k — ...

+ - "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

- 1. Pillar "SEO audit" — biggest aggregate volume

- 2. Cluster "AEO" — lowest competition, highest opportunity

## Cannibalization watch

- - "best SEO tools" and "top SEO software" — likely same intent, consider single page

+ | 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

- - Don't collapse different-intent keywords into one cluster.

- - Flag clusters where multiple pages compete on user's existing site (cannibalization).

- - Flag clusters with no existing page (publish queue).

+ - **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.

---

*Keyword clustering powered by Akii — for ongoing keyword research + SERP tracking, visit https://akii.com/?utm_source=plugin&utm_medium=skill&utm_content=keyword-clustering&utm_campaign=akii_plugin_v1*