Skip to content

Decides

Keyword selection

Picks the one keyword a page should target, checks what searchers want from the live results, and stops the page when the demand or the fit isn't there.

Other tools

Add this skill to Claude

Claude takes skills as a ZIP file. Your download has started; if it didn't, use the button below.

  1. 1In Claude, open Customize, then Skills.
  2. 2Choose +, then Upload a skill, and pick keyword-selection.zip.
  3. 3Ask for it by name, or let Claude use it when a task matches.

Skills need code execution turned on in Claude's settings. On a Team or Enterprise plan, an admin can share it with everyone.

Download the folder

Try it now, without installing

See the skill work on a made-up input before you add it. Nothing is installed, and you can swap in your own input.

Open in the Claude app

Opens a new chat in the Claude desktop app with the prompt filled in. Nothing is sent until you press enter.

Includes the whole SKILL.md and the sample input. Paste it into Claude, ChatGPT or any chat.

Influenced by
Pain point SEO
Needs
The page topic, in the buyer's words · The page's job (learn, compare or buy)
Works with
Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md
Version
2.0.0 · Last checked · License MIT
Maintained by
Sabih AhmedOrganic visibility
SkillSEO and AI search

Keyword selection

Example output

Pick the keyword for a page
KeywordIntentCall
attribution softwareCompareTarget
what is attributionLearnSupport page
free attribution toolFreeSkip

Picks the one keyword a page should target, checks what searchers want from the live results, and stops the page when the demand or the fit isn't there.

The skill

The whole skill, in plain text.

Nothing is hidden. Read it, change it to fit your team, or take the whole folder.

Scripts
Optional Python scripts for the counting. It works without them and says which way it ran.
Network
Opens web pages or your tools if your agent can. Works from pasted data if not.

3 test cases

keyword-selection/SKILL.md

In the folder

  • keyword-selection/SKILL.md
  • keyword-selection/scripts/demand_split.py
---name: keyword-selectiondescription: >-  Picks the one keyword a B2B SaaS page should target, confirms what searchers want from the live results, splits  real demand into problem-intent and category demand, and returns TARGET, SUPPORT, REFRESH, SKIP or NEEDS DECISION  with the reason. Use it before anyone writes or rewrites a page for search, or when choosing between candidate  keywords. Not for auditing pages that already compete with each other (use cannibalization-audit) or for deciding  what to do with a published page (use content-triage).license: MITcompatibility: >-  Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Uses a connected SEO tool or Search  Console if the agent has one, otherwise exports or pasted data. Python 3 is optional, for the demand split.metadata:  author: SHAKEUP  version: "2.0.0"  stage: decide  plugin: seo-ai-search  homepage: https://www.shakeuphq.com/skills/keyword-selection--- # Keyword selection Chooses the keyword a page should own, and stops the page from being written when the demand or the fit isn't there. ## Purpose - One job: pick one primary keyword for one page, with the intent, the demand behind it and the gap the page fills.- Stage: decide. It ends in a verdict.- It never invents search volume, difficulty or rankings. A number with no source is written `not available`. ## Use when / not | Situation | Use || --- | --- || Planning a new page, post or comparison page | this skill || Rewriting a page and choosing its keyword again | this skill || Two pages on the site already chase the same intent | `cannibalization-audit` || Deciding whether to refresh, merge or retire a published page | `content-triage` || Placing the page in your topic clusters and links | `cluster-fit`, after this skill | ## Inputs | Input | Required | Ways to provide, in order | If missing || --- | --- | --- | --- || Page topic, in the buyer's words | yes | the reader's request | ask once || The page's job (learn, compare, buy) | yes | the reader's request; else infer from the topic and confirm | ask once || Keyword data: volume, difficulty, CPC, SERP features | no | a connected SEO tool (Semrush, Ahrefs); an export the reader uploads; numbers they paste | write `not available`; judge on intent and the live results || Search Console queries, last 12 months | no | a connected Search Console; a Queries export (CSV); pasted rows | skip the demand split; coverage `partial` || The live search results for the top candidates | no | browse the results; titles and URLs the reader pastes | ask the reader to paste the top 5 titles and URLs; without them, intent stays `unconfirmed` || The site's existing pages on the topic | no | a site search or sitemap; a list the reader pastes | flag "overlap not checked" in open items | ## Profile read From `company-profile.md`: `## Company` (website, brand terms, business model), `## Buyers`, `## Buying moments`, `## Competitors`, `## Content` (topic clusters), and every `## Learnings` entry for `keyword-selection` with status `noted`, `fact` or `accepted`. No profile: ask for the website, who the buyer is and what the product does, in one message. Say that `company-profile` saves this next time. ## Steps 1. **Apply learnings.** Read the learnings first. A learning that changes a rule overrides the default rule below; name it in the output when it fires. 2. **List candidates.** Start from the topic and write 8 to 15 candidates before looking at any tool:   - the core noun phrase ("expense management software")   - buying modifiers: best, software, tool, platform, pricing, vs, alternatives, for <team>, for <industry>   - problem phrasing from `## Buying moments` (what the buyer types when the problem starts)   - question forms (how to, what is, why)   Then add candidates the keyword data or Search Console shows that you missed. Drop branded terms of competitors unless the page's job is a comparison. 3. **Label intent from the live results, not the words.** For each strong candidate, read the top 5 results:    | Most of the top 5 are | Intent |   | --- | --- |   | Guides, definitions, how-to posts | learn |   | Lists, comparisons, "best X", review sites | compare |   | Vendor product, pricing or demo pages | buy |   | One brand's own pages | navigational (skip unless it's the reader's brand) |   | A mix with no majority | mixed: note the split |    Without the live results, label from the modifiers and mark the intent `unconfirmed`. 4. **Drop mismatches.** Remove candidates whose intent doesn't match the page's job. A learn query never becomes the target of a buy page, however big its volume. 5. **Score what's left.**    | Factor | Rule |   | --- | --- |   | Buying intent first | For B2B SaaS, rank buy and compare intent above learn intent at the same demand. A smaller keyword that buyers type beats a bigger one that students type. |   | Difficulty for this site | With a difficulty score: viable up to 25 for a new or thin site, 45 for an established site, 65 for a strong one. Judge site strength from the reader's own data (referring domains, pages ranking top 10); if unknown, assume established and say so. |   | Existing foothold | If the site already ranks 5 to 20 for the candidate, raise it: improving or building that page is the fastest win. If it ranks 1 to 4, don't target it with a new page. |   | Demand | Use real numbers only. Volume tiers when available: high 1,000+, medium 200 to 999, low under 200. Low volume with buy intent is still a valid target. | 6. **Split real demand (when Search Console data exists).** Run `scripts/demand_split.py` with the Queries export, the leading candidate and 1 to 3 broad category terms:    ```   python3 scripts/demand_split.py --csv queries.csv --keyword "<candidate>" --category "<broad term>" --floor 50   ```    Without Python, do the same by hand: drop rows over 12 words, rows with 2 or more sentences, and rows with a whole-number position on 10 or more impressions; count impressions of queries that share the candidate's own words (minus the category words) as problem-intent; count the rest that share only the category words as category demand. Never add the two together. Report the rows you dropped. 7. **Find the gap.** For the leading candidate, read the top 5 results. Note the format they share (guide, list, comparison, tool), what all of them cover, and one buyer question they answer poorly or not at all. The gap must be specific enough to explain to a writer in one sentence. 8. **Check overlap.** Look for a page on the reader's site that already targets the candidate or its close variants. If one exists, compare: same intent means refresh that page instead of writing a new one. 9. **Make the call** with the verdict table below, then pick 2 or 3 close variants for the chosen keyword (same intent, they belong on the same page) and list the question keywords the page should answer. ## Check and verdict | Verdict | Condition (first match wins) || --- | --- || `BLOCKED` | No topic, or the page's job is unknown after asking || `REFRESH` | An existing page on the site targets the same intent: improve it, don't write a new one || `SKIP` | No candidate matches the page's job after step 4, or the demand split returns STOP and the reader gave no other evidence of demand || `NEEDS DECISION` | The best candidate's difficulty is above the site's range and nothing viable is left; or intent is mixed with no majority; or the reader's own data conflicts with the tool data || `SUPPORT` | The demand split returns GO (supporting content): write it as a supporting page and link it to the category's pillar page || `TARGET` | Otherwise: one primary keyword, intent matched, demand real or intent strong | Named stops: `BLOCKED` asks for the missing input. `NEEDS DECISION` stops and shows the 2 best options with what each would cost and win. No other stops. ## Learn Append a learning to the profile when: - the reader overrides the verdict (write the reader's reason as a `proposal`);- the reader reports a result for a past target, such as rankings or demos after 90 days (write it as a `fact` with its source). Example: `- 2026-10-24 | keyword-selection | proposal | Skip "free" modifiers for this company | Why: 3 pages targeting "free ... template" drew sign-ups that never converted (reader's CRM, Aug 2026) | Status: proposed` ## Output ```Verdict: <TARGET | SUPPORT | REFRESH | SKIP | NEEDS DECISION | BLOCKED> · Coverage: <complete | partial (what's missing) | blocked> | Keyword | Intent | Demand | Difficulty | Call | Why |(one row per candidate kept after step 4, best first; numbers with their source or "not available") Primary keyword: <keyword>, with <2 or 3 close variants>Intent: <one sentence on what the searcher wants> (<confirmed from live results | unconfirmed>)Format: <guide | comparison | list | tool | product page>, because <what the top results share>The gap: <one sentence>Questions to answer: <3 to 6 question keywords>Demand split: problem-intent <n> impressions, category <n> impressions, <n> rows dropped (<reasons>)  (or "not run: no Search Console data")Overlap: <page URL and what to do, or "none found", or "not checked">Learnings applied: <list, or none>``` Then the handoff block. ## Hand off ```handoffskill: keyword-selectionversion: 2.0.0verdict: TARGETcoverage: partial (no difficulty data)for: <page topic>outputs:  primary_keyword: expense management software  variants: [b2b expense software, spend management platform]  intent: compare  format: comparison  gap: none of the top results explain how each tool syncs with the accounting system  pillar: not availablenext: [cluster-fit, article-research]open: [confirm difficulty]``` For `SUPPORT`, `pillar` names the pillar page to link to. For `REFRESH`, `next` is `[refresh-audit]` and `outputs` names the existing page. ## Failure modes | Problem | Do this || --- | --- || The SEO tool and Search Console disagree | Trust Search Console for the reader's own site; note the gap || The reader asks for a volume you don't have | Say `not available` and name the tool or export that would give it || Every candidate is a learn query but the page must sell | `SKIP` for this page; suggest the learn topic as a separate supporting post || Search Console rows have no position column | Skip the round-position rule and say so || The topic is the reader's own brand | Navigational: no keyword research needed; say so and stop | ## Influenced by - Grow and Convert's pain point SEO, which puts bottom-of-funnel keywords before traffic keywords: https://www.growandconvert.com/content-marketing/pain-point-seo/- SHAKEUP's content engine: intent read from the live results, and demand split into problem-intent and category so a broad term can't pass for real demand.

How it thinks

Inputs in, a verdict out, and a stop only where you decide.

What we built

We read intent from the live results, not the keyword's words, and split demand so a big category term can't hide a topic nobody searches for. Buying intent comes first because a B2B SaaS page earns its keep in demos, not visits.

It reads your company profile if you have one, or asks for only what it needs. Then it works through its steps, checks its own work and ends in a verdict.

The steps

  1. 01

    Read your learnings first

    Anything your team marked as a rule for this skill, such as "vs pages bring no demos for us", changes the defaults before it starts.

  2. 02

    List the candidates

    It writes 8 to 15 candidates from your topic and your buyers' own phrasing, then adds the ones your data shows it missed.

  3. 03

    Label intent from the live results

    It reads the top 5 results for each strong candidate. Guides mean learn, lists mean compare, product pages mean buy. The words alone don't decide it.

  4. 04

    Drop what doesn't fit the page's job

    A learn query never becomes the target of a demo page, however big its volume.

  5. 05

    Score buying intent first

    For B2B SaaS, a smaller keyword that buyers type beats a bigger one that students type. Difficulty is weighed against your site's strength, not a fixed bar.

  6. 06

    Split real demand

    With Search Console data, its script splits impressions into problem-intent and category demand and never adds them together. A broad term can't pass for real demand.

  7. 07

    Make the call

    It returns one verdict with the rule that fired, the gap the page fills and a handoff block for the next skill.

What you need

  • Required

    The page topic, in the buyer's words

    Your request

  • Required

    The page's job (learn, compare or buy)

    Your request → Inferred from the topic, then confirmed with you

  • Optional

    Keyword data (volume, difficulty, SERP features)

    A connected SEO tool such as Semrush or Ahrefs → An export you upload → Figures you paste

  • Optional

    Search Console queries, last 12 months

    A connected Search Console → A Queries export (CSV) → Rows you paste

  • Optional

    The live search results for the top candidates

    It reads the results itself if your agent can browse → Titles and URLs you paste

What it can return

  • TARGET

    One keyword fits the page's job, with real demand or strong buying intent.

  • SUPPORT

    Only the broad category has demand. Write it as a supporting page and link it to the pillar.

  • REFRESH

    A page on your site already targets the same intent. Improve that page instead.

  • SKIP

    No candidate fits the page's job, or there's no demand and no other evidence of it.

  • NEEDS DECISION

    The best option is out of your site's reach, the intent is split, or your data and the tool disagree.

Where it stops for you

  • When the page's job is unknown after one question
  • When the best keyword is too hard for your site and nothing viable is left

Example output

What you get back.

A run for a made-up company. Your output depends on your inputs.

Here's a run for a made-up B2B SaaS company that sells attribution software. The page is a comparison page for buyers choosing between tools.

Verdict

TARGET

Coverage: partial (no difficulty data, no Search Console export)

KeywordIntentDemandCallWhy
attribution softwareCompare1,300 a monthTargetThe top results are lists and a G2 category page, so buyers are comparing tools
b2b attribution softwareCompare320 a monthVariantSame intent, so it belongs on the same page
marketing attributionLearn6,600 a monthDrop here4 of the top 5 results are guides, so searchers want to learn, not compare
what is marketing attributionLearn2,400 a monthDrop hereA learn query, better as a supporting guide
Primary keyword

attribution software, with "b2b attribution software" and "attribution platform" as close variants.

Intent

buyers comparing tools before a shortlist, confirmed from the live results.

Format

a comparison page, because the top results are lists and comparisons, not guides.

The gap

none of the top results explain how each tool reads the CRM's lifecycle stages, which is the question buyers ask in demos.

Overlap

none found on the site.

The handoff block the next skill reads
skill: keyword-selection
version: 2.0.0
verdict: TARGET
coverage: partial (no difficulty data, no Search Console export)
for: attribution tools comparison page
outputs:
  primary_keyword: attribution software
  intent: compare
  format: comparison
next: [cluster-fit, article-research]
open: [confirm difficulty]

What good looks like

  • One primary keyword, with intent that matches what the page is for
  • No search volume that wasn't in your data
  • A gap you could explain to a writer in one sentence
  • A clear REFRESH when a page you already have targets the keyword
  • Skips that say why, so you don't revisit them next month

Install

Use it in the tool you already have.

Pick your tool. Each tab has the shortest path we know of.

  1. 01
  2. 02
    In Claude, open Customize, then Skills.
  3. 03
    Choose +, then Upload a skill, and pick the ZIP. Code execution must be on in your settings.
  4. 04
    Ask for it by name, or let Claude use it when a task matches.

Questions

Before you add it.

Does it need Semrush or Ahrefs?

No. It uses a connected SEO tool if you have one, an export if you upload it, or figures you paste. Without any, it decides on intent and the live results and says the volumes are not available.

Will it make up search volumes?

No. Every figure in the output comes from your tool, your export or your paste. A missing figure is written as not available, with the source that would provide it.

What does the script do?

It splits your Search Console impressions into problem-intent and category demand, after dropping rows that look like AI crawler traffic. It's optional. Without Python, the skill makes the same count itself and says so.

Can it handle a page we already have?

Yes. If a page on your site already targets the same intent, it returns REFRESH and points to it, so you improve that page instead of writing a competitor to it.