# Keyword Clustering

Cluster keywords by intent and map them to existing or proposed pages.

- Repository: https://github.com/every-app/open-seo (25988 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add every-app/open-seo --skill keyword-clustering -g -a claude-code -y`
Codex: `npx skills add every-app/open-seo --skill keyword-clustering -g -a codex -y`
Cursor: `npx skills add every-app/open-seo --skill keyword-clustering -g -a cursor -y`
Gemini CLI: `npx skills add every-app/open-seo --skill keyword-clustering -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add every-app/open-seo`

## Description

Cluster keywords by intent and map them to existing or proposed pages.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# OpenSEO Keyword Clustering

## Goal

Group keywords into page-level clusters and decide which existing or new page should target each cluster. This is a keyword mapping workflow, not just a semantic grouping exercise.

## Required inputs

- `projectId`
- A keyword list, saved keyword tag, seed topic, or target domain
- Optional existing URLs/pages to map against

If keywords are not provided, use `list_saved_keywords` for saved sets, `research_keywords` for seed discovery, or `get_ranked_keywords` when the user starts from a target domain.

## Project context

The project-context tools are free and shared with the app and other agents.

1. Call `get_project_context` first and ground the mapping in it, the saved key pages are the existing pages clusters should map to, and the business and goal decide which clusters are worth targeting.
2. This skill needs key pages. If none are saved, run a minimal inline setup: ask the user for the pages that matter, or propose a shortlist from the site, an audit, or Search Console and confirm it, write it back with `update_project_context` (`addKeyPages`), then continue the clustering. Never front-load the full interview; suggest `seo-project-setup` at the end for the rest.
3. Before spending credits, check the research log. If the same research ran within the last 30 days, reuse that result and say so instead of re-buying it.
4. On finish, write back what is durable with `update_project_context`, new or corrected `addKeyPages` entries with the topic each page now targets, and append a research log entry: `{ appendResearchLog: { summary: "Keyword clustering: <keyword set>. Verdict: <conclusion>" } }`.

## Deliver as a report

Deliver through the `seo-report` skill, saving with `skill: "keyword-clustering"`. If that skill is not available, say so and stop before writing HTML.

## OpenSEO MCP tools

The rest: https://github.com/every-app/open-seo/blob/HEAD/.agents/skills/keyword-clustering/SKILL.md