1---2name: cluster-fit3description: >-4 Places a planned B2B SaaS page in the site's topic clusters: decides whether it is a pillar or a supporting page,5 names the gap it fills in its cluster, and lists the pages it should link to and get links from. Returns6 SUPPORTING, PILLAR, PILLAR FIRST, NEW CLUSTER, STANDALONE, NEEDS DECISION or BLOCKED. Use it after7 keyword-selection and cannibalization-audit clear a page, before the outline. Not for writing anchor text or8 placing links in a draft (use internal-linking) or for checking clashes (use cannibalization-audit).9license: MIT10compatibility: >-11 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads a crawl or sitemap if the agent12 can browse, otherwise a pasted page list. Python 3 is optional, for the placement score.13metadata:14 author: SHAKEUP15 version: "1.0.0"16 stage: decide17 plugin: seo-ai-search18 homepage: https://www.shakeuphq.com/skills/cluster-fit19---20 21# Cluster fit22 23Gives a new page a place in the site before it is written, so it doesn't ship as an orphan with no pillar above it and no links in.24 25## Purpose26 27- One job: decide the role of one planned page in the site's clusters, the gap it fills and its link targets.28- Stage: decide. It ends in a verdict with the rule that fired.29- It picks pages to link, never anchor text or placement (that is `internal-linking`).30- It never invents a pillar URL or a page that doesn't exist; a missing page is listed as a missing target.31 32## Use when / not33 34| Situation | Use |35| --- | --- |36| A page has a keyword and passed the clash check | this skill |37| Planning a new cluster and its first page | this skill (it returns NEW CLUSTER or STANDALONE) |38| The keyword isn't chosen yet | `keyword-selection` first |39| You don't know if the page repeats one you have | `cannibalization-audit` first |40| You need anchors and positions for links in a draft | `internal-linking`, after this skill |41 42## Inputs43 44| Input | Required | Ways to provide, in order | If missing |45| --- | --- | --- | --- |46| Primary keyword, variants, intent, demand tier | yes | the `keyword-selection` handoff; the reader's request | ask once |47| Clash result | no | the `cannibalization-audit` handoff | say "clash not checked" in open items |48| Cluster map: each cluster's name, pillar URL, pillar keyword | no | `## Content` topic clusters in the profile; a clusters file the reader keeps; inferred from the page list | infer from the page list, coverage `partial` |49| The site's pages: URL and title | yes | a crawl or sitemap the agent can read; a crawl export; a pasted list (URLs alone work, weaker) | `BLOCKED`, ask for it |50| Planned topics | no | the reader's content plan or calendar | adjacent gaps can't be checked against the plan |51 52## Profile read53 54From `company-profile.md`: `## Content` (topic clusters with pillar URLs, site sections), `## Product` (product pages a page can link to), `## Buying moments` (to judge whether an unmatched topic deserves a new cluster), `## Buyers`, and every `## Learnings` entry for `cluster-fit` with status `noted`, `fact` or `accepted`.55 56No profile: ask for the website and, if they keep one, their list of topic clusters with pillar URLs, in one message. Say that `company-profile` saves this next time.57 58## Steps59 601. **Apply learnings.** Read them first; an accepted learning overrides the default rule it names.61 622. **Read the upstream verdicts.** If `cannibalization-audit` returned `REFRESH` or `BLOCK`, this is not a new page: stop with `BLOCKED` and point to `refresh-audit` or `internal-linking` for the existing page. If it returned `DIFFERENTIATE`, carry its angle and sibling URL into every step below.63 643. **Build the cluster map.** Start from the profile's clusters. Add the page list: group pages by URL folder and shared title words. For each cluster record:65 66 | Field | How |67 | --- | --- |68 | Pillar | the profile's pillar URL; else the broadest live page in the group; else `missing` |69 | Pillar keyword | the pillar's main topic in 1 to 3 words |70 | Supporting pages | URL, title, the sub-intent each serves |71 | Stage coverage | which of learn, compare and buy the cluster's pages serve |72 73 From URLs alone (no titles), read the slug as the title and mark the map `inferred`.74 754. **Score the match.** With Python, write the keyword, variants and map to JSON and run:76 77 ```78 python3 scripts/cluster_place.py --json place.json79 ```80 81 Without Python: for each cluster, count the keyword's words that also appear in the pillar keyword or a supporting title, divided by the words in both. Best at 0.05 or under is no match (the words barely meet). A second cluster within 0.10 of the best is ambiguous. Say which way you ran it.82 835. **Confirm on meaning.** A word match is a candidate, not a placement. Confirm that a buyer reading the cluster's pillar would expect this page as a next step. When the scores are ambiguous, pick the cluster whose pillar answers the question this page narrows; if both do, that is `NEEDS DECISION`.84 856. **Decide the role.**86 87 | Condition (first match wins) | Role | Why |88 | --- | --- | --- |89 | The keyword is the cluster's head term (it holds 80% or more of the pillar keyword's words and adds at most 1) and a live pillar exists | conflict: `NEEDS DECISION` | a pillar already owns the head term; a second one splits it |90 | Head term, no live pillar, and the page will link out to 3 or more supporting pages | `PILLAR` | a pillar is the broad page the rest point up to |91 | Narrower keyword (a modifier: a team, an industry, "vs", pricing, a use case, a how-to) and a live pillar | `SUPPORTING` | one sub-intent under an anchor |92 | Narrower keyword, matched cluster, no live pillar | `PILLAR FIRST` | a supporting page with no pillar has nothing to pass authority to |93 | No match, the topic sits on a buying moment or the profile's category, and 3 or more supporting topics can be named now | `NEW CLUSTER` (this page is its pillar) | a cluster needs a pillar and at least 3 pages under it |94 | No match otherwise | `STANDALONE` | a page with no cluster gets no links in and rarely earns its cost |95 96 With a demand tier from `keyword-selection`, a head term is usually high demand (1,000 or more searches a month). Without one, decide on breadth and say so.97 987. **Name the gap.** Write it in this form: "This page covers <sub-intent> for <buyer>, which no page in <cluster> covers." Check the supporting pages: if one already serves the sub-intent, go back to `cannibalization-audit`. Also note:99 - a stage gap it fills (the cluster had no compare or buy page, say);100 - up to 3 adjacent gaps it surfaces but doesn't fill, as future topics.101 1028. **List link targets** (pages and reasons, no anchors):103 104 | Direction | Role | Targets |105 | --- | --- | --- |106 | Out | SUPPORTING | the pillar (always), 2 to 4 siblings with related but different sub-intents, at most 1 product page from `## Product` when the topic maps to it |107 | Out | PILLAR, NEW CLUSTER | every live supporting page in the cluster, and the main product page |108 | In | any | up to 5 live pages: the pillar, siblings that mention this sub-intent, pages that now link to a weaker page on it |109 | Missing | any | pages it should link to that don't exist yet, listed as future topics |110 111 Never list a page with a 4xx or 5xx status, a redirect, or a legal, login or ad landing page.112 113## Check and verdict114 115| Verdict | Condition (first match wins) |116| --- | --- |117| `BLOCKED` | No keyword; no page list after asking; or the clash check returned REFRESH or BLOCK |118| `NEEDS DECISION` | The head term of a cluster whose pillar is live; or 2 clusters fit equally on meaning; or `keyword-selection` named a pillar this map contradicts |119| `PILLAR FIRST` | Narrower page for a cluster with no live pillar |120| `PILLAR` | Head term, no live pillar, 3 or more supporting pages to link out to |121| `SUPPORTING` | Narrower page under a live pillar |122| `NEW CLUSTER` | No match; the topic sits on a buying moment or the category; 3 or more supporting topics named |123| `STANDALONE` | No match otherwise |124 125Named stops: `NEEDS DECISION` shows the 2 options (which cluster, or which page is the pillar) and what each costs. `BLOCKED` asks for the missing input or routes to the skill that fits. No other stops: `PILLAR FIRST` and `STANDALONE` are calls with reasons, not questions.126 127## Learn128 129Append a learning to the profile when:130 131- the reader overrides the role or the cluster (a `proposal` with their reason);132- the reader confirms or adds a cluster and its pillar URL: update `## Content` topic clusters and record a `fact`;133- a result comes back, such as a supporting page that ranked only after its pillar shipped (a `fact` with its source).134 135Example: `- 2026-10-24 | cluster-fit | fact | Pipeline reporting cluster has a pillar at /guides/pipeline-reporting | Why: reader confirmed, page published 2026-10-20 | Status: noted`136 137## Output138 139```140Verdict: <SUPPORTING | PILLAR | PILLAR FIRST | NEW CLUSTER | STANDALONE | NEEDS DECISION | BLOCKED> · Coverage: <complete | partial (what's missing) | blocked> · Score: <script | by hand>141Rule fired: <the condition, in words>142 143Cluster: <name> · Pillar: <URL | missing> · Match score: <n> (second: <cluster, n>)144Role: <role>, because <reason>145Gap filled: <one sentence in the form above>146Stage gap: <stage it fills, or none>147Adjacent gaps (future topics): <up to 3>148 149| Direction | Page | Why |150(out, then in, then missing)151 152Flags: <pillar missing, possible clash, inferred map, or none>153Learnings applied: <list, or none>154```155 156Then the handoff block.157 158## Hand off159 160```handoff161skill: cluster-fit162version: 1.0.0163verdict: SUPPORTING164coverage: partial (cluster map inferred from URLs)165for: <primary keyword>166outputs:167 cluster: attribution168 pillar: https://example.com/guides/b2b-attribution169 role: supporting170 gap: how each tool reads CRM lifecycle stages, for RevOps171 links_out: [https://example.com/guides/b2b-attribution, https://example.com/blog/b2b-attribution-models]172 links_in: [https://example.com/guides/b2b-attribution]173next: [article-research, internal-linking]174open: [confirm no planned post covers the same sub-intent]175```176 177For `PILLAR FIRST`, `next` is `[keyword-selection]` for the pillar's keyword. For `NEEDS DECISION`, `next` waits on the reader.178 179## Failure modes180 181| Problem | Do this |182| --- | --- |183| The profile's pillar URL returns a 404 or redirects | Treat the pillar as missing and flag the broken URL |184| Every page sits in one folder (/blog/) so folders say nothing | Group by title words and the sub-intents you read, and mark the map inferred |185| The site has no clusters at all | Run the NEW CLUSTER or STANDALONE rule, and list the 3 clusters the profile's buying moments suggest |186| The keyword fits a cluster but the buyer differs (a CFO page in a RevOps cluster) | Place it by need, note the buyer shift for the writer |187| A product page is the best pillar | Allowed: a product page can anchor a buy-stage cluster. Say so |188 189## Influenced by190 191- SHAKEUP's content engine: placement scored on word overlap first, with ambiguity flagged for a judgment on meaning, and a rule that a supporting page never ships without a pillar to point to.192- Google's link guidance, which explains how crawlers find pages through internal links and read anchor context: https://developers.google.com/search/docs/crawling-indexing/links-crawlable