1---2name: keyword-selection3description: >-4 Picks the one keyword a B2B SaaS page should target, confirms what searchers want from the live results, splits5 real demand into problem-intent and category demand, and returns TARGET, SUPPORT, REFRESH, SKIP or NEEDS DECISION6 with the reason. Use it before anyone writes or rewrites a page for search, or when choosing between candidate7 keywords. Not for auditing pages that already compete with each other (use cannibalization-audit) or for deciding8 what to do with a published page (use content-triage).9license: MIT10compatibility: >-11 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Uses a connected SEO tool or Search12 Console if the agent has one, otherwise exports or pasted data. Python 3 is optional, for the demand split.13metadata:14 author: SHAKEUP15 version: "2.0.0"16 stage: decide17 plugin: seo-ai-search18 homepage: https://www.shakeuphq.com/skills/keyword-selection19---20 21# Keyword selection22 23Chooses the keyword a page should own, and stops the page from being written when the demand or the fit isn't there.24 25## Purpose26 27- One job: pick one primary keyword for one page, with the intent, the demand behind it and the gap the page fills.28- Stage: decide. It ends in a verdict.29- It never invents search volume, difficulty or rankings. A number with no source is written `not available`.30 31## Use when / not32 33| Situation | Use |34| --- | --- |35| Planning a new page, post or comparison page | this skill |36| Rewriting a page and choosing its keyword again | this skill |37| Two pages on the site already chase the same intent | `cannibalization-audit` |38| Deciding whether to refresh, merge or retire a published page | `content-triage` |39| Placing the page in your topic clusters and links | `cluster-fit`, after this skill |40 41## Inputs42 43| Input | Required | Ways to provide, in order | If missing |44| --- | --- | --- | --- |45| Page topic, in the buyer's words | yes | the reader's request | ask once |46| The page's job (learn, compare, buy) | yes | the reader's request; else infer from the topic and confirm | ask once |47| 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 |48| Search Console queries, last 12 months | no | a connected Search Console; a Queries export (CSV); pasted rows | skip the demand split; coverage `partial` |49| 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` |50| 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 |51 52## Profile read53 54From `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`.55 56No 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.57 58## Steps59 601. **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.61 622. **List candidates.** Start from the topic and write 8 to 15 candidates before looking at any tool:63 - the core noun phrase ("expense management software")64 - buying modifiers: best, software, tool, platform, pricing, vs, alternatives, for <team>, for <industry>65 - problem phrasing from `## Buying moments` (what the buyer types when the problem starts)66 - question forms (how to, what is, why)67 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.68 693. **Label intent from the live results, not the words.** For each strong candidate, read the top 5 results:70 71 | Most of the top 5 are | Intent |72 | --- | --- |73 | Guides, definitions, how-to posts | learn |74 | Lists, comparisons, "best X", review sites | compare |75 | Vendor product, pricing or demo pages | buy |76 | One brand's own pages | navigational (skip unless it's the reader's brand) |77 | A mix with no majority | mixed: note the split |78 79 Without the live results, label from the modifiers and mark the intent `unconfirmed`.80 814. **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.82 835. **Score what's left.**84 85 | Factor | Rule |86 | --- | --- |87 | 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. |88 | 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. |89 | 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. |90 | 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. |91 926. **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:93 94 ```95 python3 scripts/demand_split.py --csv queries.csv --keyword "<candidate>" --category "<broad term>" --floor 5096 ```97 98 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.99 1007. **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.101 1028. **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.103 1049. **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.105 106## Check and verdict107 108| Verdict | Condition (first match wins) |109| --- | --- |110| `BLOCKED` | No topic, or the page's job is unknown after asking |111| `REFRESH` | An existing page on the site targets the same intent: improve it, don't write a new one |112| `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 |113| `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 |114| `SUPPORT` | The demand split returns GO (supporting content): write it as a supporting page and link it to the category's pillar page |115| `TARGET` | Otherwise: one primary keyword, intent matched, demand real or intent strong |116 117Named 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.118 119## Learn120 121Append a learning to the profile when:122 123- the reader overrides the verdict (write the reader's reason as a `proposal`);124- 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).125 126Example: `- 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`127 128## Output129 130```131Verdict: <TARGET | SUPPORT | REFRESH | SKIP | NEEDS DECISION | BLOCKED> · Coverage: <complete | partial (what's missing) | blocked>132 133| Keyword | Intent | Demand | Difficulty | Call | Why |134(one row per candidate kept after step 4, best first; numbers with their source or "not available")135 136Primary keyword: <keyword>, with <2 or 3 close variants>137Intent: <one sentence on what the searcher wants> (<confirmed from live results | unconfirmed>)138Format: <guide | comparison | list | tool | product page>, because <what the top results share>139The gap: <one sentence>140Questions to answer: <3 to 6 question keywords>141Demand split: problem-intent <n> impressions, category <n> impressions, <n> rows dropped (<reasons>) (or "not run: no Search Console data")142Overlap: <page URL and what to do, or "none found", or "not checked">143Learnings applied: <list, or none>144```145 146Then the handoff block.147 148## Hand off149 150```handoff151skill: keyword-selection152version: 2.0.0153verdict: TARGET154coverage: partial (no difficulty data)155for: <page topic>156outputs:157 primary_keyword: expense management software158 variants: [b2b expense software, spend management platform]159 intent: compare160 format: comparison161 gap: none of the top results explain how each tool syncs with the accounting system162 pillar: not available163next: [cluster-fit, article-research]164open: [confirm difficulty]165```166 167For `SUPPORT`, `pillar` names the pillar page to link to. For `REFRESH`, `next` is `[refresh-audit]` and `outputs` names the existing page.168 169## Failure modes170 171| Problem | Do this |172| --- | --- |173| The SEO tool and Search Console disagree | Trust Search Console for the reader's own site; note the gap |174| The reader asks for a volume you don't have | Say `not available` and name the tool or export that would give it |175| Every candidate is a learn query but the page must sell | `SKIP` for this page; suggest the learn topic as a separate supporting post |176| Search Console rows have no position column | Skip the round-position rule and say so |177| The topic is the reader's own brand | Navigational: no keyword research needed; say so and stop |178 179## Influenced by180 181- 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/182- 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.