How to use the SEO Keyword Cluster Planner agent skill

What an agent skill is and what seo-cluster makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent how to carry out a specific task. When the skill is installed, the agent can load its instructions and follow them when a request matches the skill's description.

The seo-cluster skill covers content planning. Given a seed keyword or URL, it expands the keyword into 30-50 variants by running web searches, then groups those variants by checking how many top-10 Google results two keywords share. Keywords that share 7-10 results are merged into one target page, and keywords that share 4-6 are grouped under the same spoke cluster.

From there the skill designs a central pillar page with supporting spoke posts, sets an internal link matrix so each spoke links to the pillar and to related spokes, and generates an interactive HTML cluster map. If a companion writing skill (claude-blog's blog-write) is installed, the execute step can draft the posts; otherwise it produces content briefs.

• Expansion uses related searches, People Also Ask questions, long-tail modifiers, question variants and intent modifiers.
• Intent is classified as informational, commercial, transactional or navigational; navigational keywords are excluded from clustering.
• Output includes cluster-map.html, which you open in a browser.

Install the seo-cluster skill from a ZIP or the Claude apps

Download the ZIP for seo-cluster from this page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

The skill's files are SKILL.md, references/execution-workflow.md, references/hub-spoke-architecture.md, references/serp-overlap-methodology.md and templates/cluster-map.html. Keep the folder structure intact so the references and template load correctly.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Check the requirements before you start

The skill needs the agent to have WebSearch capability, because keyword expansion and SERP checks depend on it. Without web search the core clustering step cannot run.

Two things are optional. The DataForSEO MCP server and account provide paid SERP data; the skill shows cost estimates and asks for approval before running a batch. The blog-write skill from claude-blog drafts posts during the execute step. The plugin's scripts/ directory is used for the DataForSEO cost check.

• Required: WebSearch capability in the agent
• Optional: DataForSEO MCP server and account
• Optional: claude-blog's blog-write skill for drafting posts
• Optional: the plugin's scripts/ directory (claude-seo runner) for the DataForSEO cost check

Trigger the skill with a natural request or a command

The skill's argument hint is a seed keyword or URL. You can name the planning task directly in a request, or use the command form the skill documents. The planning command takes a seed keyword and runs the full workflow: expand, cluster, architect and visualize.

After a plan exists, the execute command turns it into content, and the map command regenerates the interactive visualization. If you already have output from an SEO plan, the strategy import option builds the cluster from that output.

• Plan: /seo cluster plan <seed-keyword>
• Import an existing plan: /seo cluster plan --from strategy
• Execute the plan: /seo cluster execute
• Regenerate the map: /seo cluster map

Example requests and what you get back

A useful request names the topic, the site type and the output you need. For example, you might ask the agent to plan a blog hub around a seed keyword for a small accounting software company, then review the cluster map before writing anything.

Expect the planning run to take a while, since it performs many web searches. Review the groupings before you approve execution, because the skill flags borderline intent cases for manual review and removes navigational keywords.

• Ask for a plan for a seed keyword and say whether you want a blog hub or a content hub.
• Ask the agent to import an existing SEO plan with the strategy option.
• Ask the agent to regenerate the cluster map after you edit the plan.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The workflow runs web searches and, if DataForSEO is connected, calls its SERP endpoint. The cost check is run through the plugin's scripts/ directory, and paid calls are shown with a cost estimate and need your approval; if the cost check reports blocked, the skill falls back to WebSearch.

When the cluster map is generated, the skill writes every < in the JSON as \u003c so that a page title cannot break out of the script block. Still, review any script the agent proposes to run and check what it sends over the network.

• Approve DataForSEO costs when prompted; the skill does not spend without the approval step.
• Review the files in the skill folder before installing if you need to audit them.
• Do not paste confidential keyword research into a session you have not checked for network use.

Tips for better cluster plans

Start with a specific seed keyword that matches a topic you can cover in depth. Broad seeds produce large, loosely related sets that take longer to sort.

Treat search volume as unverified. The skill relies on web search and optional paid data rather than guaranteed metrics, so check volumes in your own tool before committing budget.

Edit the plan before executing. Drafted posts still need fact-checking and editing, and the link matrix should match how your site is actually organized.

• Use a clear seed keyword rather than a vague topic.
• Confirm search volumes in a dedicated tool.
• Read the generated briefs or drafts before publishing.