keyword-finder

---
name: keyword-finder
description: Finds the searches your buyers actually type, ranked by which bring business. Use before writing any page or post, or when deciding what to publish next.
---

# Find the searches your buyers actually type

One ranked list of real search phrases, grouped into pages, with the intent behind each.

## Claude does

1. Asks five things and refuses to guess any: your website, what you sell in your own words, the areas you serve, three competitors you lose work to, and whether you want customers now or readers now.
2. Reads your site and pulls the words you already use. Buyers type your words back at you.
3. Builds seeds from how customers speak: problem, job, near-me, price, comparison, emergency.
4. Expands each seed against the live web: Google suggestions, People Also Ask, forum questions, competitor headings.
5. Labels every phrase informational, commercial, transactional or local. Intent decides the page type, never the word count.
6. Clusters by SERP overlap, not wording. Same top ten results, one page. Different results, two pages.
7. Sizes the prize on published click-through rate by position. Position one takes roughly a quarter to a third of clicks and collapses by position five. Where an AI Overview or local pack sits above the results, click share drops again, so those phrases are marked lower value even on high volume.
8. Marks anything unproven as unverified, and never states a search volume as fact unless you supplied tool data.
9. Gives you the top twenty phrases with a one-line reason each, then hands the bulk to Codex.

## Then Codex does

Codex does the mechanical half: expanding seeds into variants, deduplicating, tagging intent, clustering, writing a CSV plus a short report. Hundreds of rows of string work is where a coding agent beats a chat.

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

Claude fills in first: {BUSINESS}, {LOCATIONS}, {SEEDS}, {COMPETITORS}, {INTENT_GOAL}.

## Claude checks

1. Opens the CSV and counts rows. A printed count that does not match the file means reject and rerun.
2. Reads ten rows out of the file itself, never retyping a number into a summary. A hand-copied figure is how a false finding gets reported as real.
3. Confirms every cluster states a SERP-overlap reason, not just similar wording.
4. Rejects any row claiming a search volume that came from nowhere.
5. Confirms location phrases name places you actually serve.
6. Rejects more than thirty location clusters without your yes. Mass location pages get treated as doorway pages.

Reject and rerun: name the fault, hand the file back to Codex, check again.

## Rules

- Intent decides the page, never length. Google states length alone does not rank.
- Never use a meta keywords tag. Google does not read it.
- One page per SERP cluster. Two pages chasing one result set fight each other.
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.

## If Codex is not installed

Claude does the expansion itself in the same format and says it did both halves.

## Built from

- AgriciDaniel/claude-seo, https://github.com/AgriciDaniel/claude-seo, 16,344 stars (api.github.com, 5 Sep 2026). Location-page caps.
- inhouseseo/superseo-skills, https://github.com/inhouseseo/superseo-skills, 305 stars (api.github.com, 5 Sep 2026). CTR-by-position table.
- seranking/seo-skills, https://github.com/seranking/seo-skills, 135 stars (api.github.com, 5 Sep 2026). SERP-overlap clustering.
- Google Search Central SEO Starter Guide, https://developers.google.com/search/docs/fundamentals/seo-starter-guide. Google's own rules.

# Find the searches your buyers actually type - Codex task

You are expanding a seed keyword list into a full, clustered, intent-tagged keyword map. You have no memory of any earlier conversation. Everything you need is below.

## You are given

- {BUSINESS} - what the business sells, in plain words.
- {LOCATIONS} - the towns, cities or areas it serves.
- {SEEDS} - the seed search phrases already built by hand.
- {COMPETITORS} - three competitor website addresses.
- {INTENT_GOAL} - either "customers now" or "readers now".

## Produce

Two files in the working folder.

1. `keywords.csv` with exactly these columns, in this order:
   `phrase, seed, intent, modifier_type, location, cluster_id, cluster_page_title, page_type, priority, volume_source, notes`
   - `intent` is one of: informational, commercial, transactional, local.
   - `modifier_type` is one of: problem, job, near-me, price, comparison, emergency, brand, other.
   - `page_type` is one of: service page, location page, guide, comparison, FAQ.
   - `priority` is high, medium or low. High only when intent matches {INTENT_GOAL}.
   - `volume_source` is either the named tool the figure came from, or the word `unverified`. Never leave it blank.
   - Minimum 150 rows, maximum 600 rows.

2. `keyword-map.md`, under 700 words, listing each cluster with: cluster id, the one page it should become, the phrases in it, the intent, and one sentence on why those phrases belong on the same page.

## Rules

- Deduplicate on the lowercased phrase with punctuation and stop words stripped. Keep the most natural wording of each duplicate group.
- Cluster by likely shared search results, not by string similarity. Phrases with different intent never share a cluster even when the wording is close.
- One cluster becomes exactly one page. Never split a cluster across pages.
- Cap location pages at 30 clusters. If {LOCATIONS} would produce more, stop at 30 and write a line in `keyword-map.md` saying how many were left out and why.
- Never invent a search volume, a difficulty score or a click figure. `unverified` is a correct answer.
- Do not add any phrase naming a location that is not in {LOCATIONS}.
- Do not add competitor brand names as target phrases. They may appear only in comparison clusters, labelled `comparison`.
- Public information only. Do not scrape anything behind a login.
- British English throughout.

## Return

Print exactly these lines to stdout when finished, and nothing else:

```
ROWS: <integer row count of keywords.csv, excluding the header>
CLUSTERS: <integer number of distinct cluster_id values>
LOCATION_CLUSTERS: <integer>
UNVERIFIED_ROWS: <integer count where volume_source is unverified>
INTENT_SPLIT: informational=<n> commercial=<n> transactional=<n> local=<n>
FILES: keywords.csv, keyword-map.md
SAMPLE:
<ten full CSV rows copied verbatim from the file, not retyped>
```