1---2name: cannibalization-audit3description: >-4 Checks whether pages on a B2B SaaS site compete for the same search intent. Topic mode compares one planned page5 with the site and returns PROCEED, DIFFERENTIATE, REFRESH or BLOCK. Library mode finds query-level clashes in6 Search Console data, gives each group of competing pages a severity and a move (consolidate, redirect,7 differentiate, leave) and returns PASS or FAIL. Use it before writing a page, or monthly across the library. Not8 for choosing a keyword (use keyword-selection) or sorting pages by performance (use content-triage).9license: MIT10compatibility: >-11 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Uses a connected Search Console or a12 crawl if the agent has one, otherwise exports or pasted lists. Python 3 is optional, for the clash finder.13metadata:14 author: SHAKEUP15 version: "2.0.0"16 stage: check17 plugin: seo-ai-search18 homepage: https://www.shakeuphq.com/skills/cannibalization-audit19---20 21# Cannibalization audit22 23Stops a site from competing with itself: before a new page is written, and across the pages already live.24 25## Purpose26 27- One job: find pages that serve the same searcher need and say what to do about each clash.28- Stage: check. It ends in a verdict with the rule that fired, and a severity per clash.29- It judges intent, not words. 2 pages that share a keyword but serve different needs are not a clash.30- It never redirects, merges or deletes anything. It writes the move; a person makes it.31 32## Use when / not33 34| Situation | Use |35| --- | --- |36| A new page is planned and might repeat one you have | this skill, topic mode |37| Rankings bounce between 2 URLs, or the library grew without a plan | this skill, library mode |38| Choosing the keyword for a page | `keyword-selection` (run it first; its handoff feeds topic mode) |39| Deciding refresh, retire or protect by performance | `content-triage` (it reads this skill's clash groups) |40| Placing a cleared page in a cluster | `cluster-fit`, after a PROCEED or DIFFERENTIATE |41 42## Inputs43 44| Input | Required | Ways to provide, in order | If missing |45| --- | --- | --- | --- |46| Mode | yes | the reader's request (a planned page means topic, an audit means library) | infer, say which |47| The planned page: topic, buyer, job (learn, compare, buy), primary keyword | topic mode | the `keyword-selection` handoff; the reader's request | ask once |48| The site's pages: URL, title, H1 | yes | a crawl or sitemap the agent can read; a crawl export (CSV); a pasted list | `NO VERDICT`, ask for it |49| Search Console, page and query rows, last 12 months | library mode; optional in topic mode | a connected Search Console; an export with both page and query columns; pasted rows | topic: health unknown, listed as a gap; library: group by title and H1 only, coverage `partial`, severity capped at moderate |50| Page modified dates | no | crawl metadata; sitemap `lastmod`; the date on the page | unknown counts as stale, listed as a gap |51| External links to candidate pages | no | a connected SEO tool; a backlinks export | any redirect move becomes a named stop |52 53## Profile read54 55From `company-profile.md`: `## Company` (website, brand terms), `## Buyers` (who the pages are for), `## Content` (site sections, topic clusters), `## Accounts and data` (whether Search Console is connected), and every `## Learnings` entry for `cannibalization-audit` with status `noted`, `fact` or `accepted`.56 57No profile: ask for the website and the brand terms (name, product names, common misspellings) in one message. Brand terms matter because branded queries are dropped before any clash is counted. Say that `company-profile` saves this next time.58 59## Steps60 611. **Apply learnings.** Read them first. A learning that changes a threshold or a move overrides the default below; name it in the output when it fires.62 632. **Pick the mode** and confirm the inputs it needs. Topic mode runs steps 3 to 8. Library mode runs steps 9 to 14.64 65### Topic mode66 673. **Write the intent fingerprint** of the planned page in one sentence: "<buyer> who want to <learn | compare | buy> <the specific thing>, at the <awareness | consideration | decision> stage." Take the buyer from `## Buyers` and the job from the request or the `keyword-selection` handoff.68 694. **Shortlist candidates** from the page list, at most 10. A page is a candidate when any of these hold:70 71 | Signal | Threshold | Why |72 | --- | --- | --- |73 | Slug similarity to the keyword | 0.6 or more | close slugs usually mean a page someone already aimed at it |74 | Word overlap with the title or H1 | 0.3 or more | a third of the words in common is a shared topic |75 | Search Console impressions on matching queries | any | Google already tests this page for the need |76 | Your read of the page | same need in other words | 2 pages can use different words for one need |77 785. **Score each candidate 0 to 4** with the fingerprint questions. Each yes adds 1.79 80 | Question | Yes when |81 | --- | --- |82 | Same buyer? | the page speaks to the same role and company type |83 | Same need? | it answers the same core question |84 | Same stage? | same job: learn, compare or buy |85 | Would the searcher stop there? | someone who found it would not need the planned page |86 87 4 is `OVERLAP`. 2 or 3 is `ADJACENT`. 0 or 1 is `NONE`.88 896. **Check health for every OVERLAP page.** Healthy needs all 3; unknown is not healthy and goes in the data gaps.90 91 | Test | Healthy when | Why |92 | --- | --- | --- |93 | Fresh | modified in the last 12 months | in a year, stats, tools and the live results move |94 | Demand | 50 or more non-branded impressions on matching queries, 12 months | below 50 there is too little demand to say the page owns anything |95 | Complete | it answers the fingerprint's core question in full (read it) | a thin page that ranks is a refresh, not a wall |96 977. **Run the rules.** With Python, write the candidates to JSON and run:98 99 ```100 python3 scripts/clash_finder.py topic --json topic.json101 ```102 103 Without Python, apply the verdict table below in order, compute slug similarity by eye (same words in the same order counts as near-exact), and say you ran it by hand.104 1058. **Name the differentiation** for an ADJACENT result: the angle in one sentence (a narrower buyer, a different stage, a format the other page lacks) and the sibling URL the new page links to. If you can't name an angle a writer could hold for a whole page, there isn't one.106 107### Library mode108 1099. **Load the rows.** Drop branded queries (any brand term from the profile) and queries under 10 impressions in the window (noise). Report both counts.110 11110. **Find clashes.** For each query, list the pages that each take 10% or more of its impressions (below 10% is a brief test, not a clash). 2 or more such pages is a clash. Run:112 113 ```114 python3 scripts/clash_finder.py library --csv pages_queries.csv --brand "<brand term>"115 ```116 117 Without Python, sort the rows by query, compute each page's share of the query's impressions, and keep queries with 2 or more pages at 10% or more. Group pages that share any clash query.118 11911. **Confirm intent per group.** Write the fingerprint of each page in the group. The data shows a shared query, not a shared need: a pricing page and a guide can share "<category> pricing" and both be right. Different fingerprints drop the group to `low` and the move to leave.120 12112. **Set severity.**122 123 | Severity | Condition (first match wins) | Why |124 | --- | --- | --- |125 | critical | same intent, 2 or more pages each at 20% or more of shared queries, 100 or more shared impressions | Google is alternating between them on real demand |126 | moderate | same intent and 50 or more shared impressions; or same intent from titles and H1s with no Search Console data | the split is real but small, or unproven |127 | low | different intent, or under 50 shared impressions | monitor; acting costs more than it wins |128 12913. **Pick the keeper and the move.** The keeper has the most clicks on the shared queries; ties go to more total clicks, then more external links, then the shorter URL.130 131 | Condition (first match wins) | Move |132 | --- | --- |133 | Different intent | leave both; link them to each other |134 | The other page's own (non-shared) queries show a distinct need, with 50 or more impressions | differentiate: re-aim it at that need, cut the overlapping sections, link to the keeper |135 | Keeper has 2x or more the other page's clicks on shared queries (clearly stronger) | redirect the other page to the keeper (301), after moving any section the keeper lacks |136 | Neither has 2x the other | consolidate: merge the best sections into the keeper, 301 the rest, then `refresh-audit` the keeper |137 138 A query that is a narrower form of the same need ("<topic> definition" beside "<topic> guide") is not a distinct need.139 14014. **Check external links** before any redirect. A page with external links pointing at it is a named stop, whatever its traffic.141 142## Check and verdict143 144Topic mode:145 146| Verdict | Condition (first match wins) |147| --- | --- |148| `NO VERDICT` | No planned topic, or no page list after asking |149| `BLOCK` | An OVERLAP page is healthy: link to it, don't write a new page |150| `REFRESH` | OVERLAP pages exist and none is healthy: improve the strongest (consolidate if 2 or more) |151| `DIFFERENTIATE` | Best match is ADJACENT and an angle and a sibling URL are named; or no overlap but a near-exact slug or title match (0.9 or more) exists |152| `BLOCK` | Best match is ADJACENT and no distinct angle can be named |153| `PROCEED` | No candidate scores 2 or more |154 155Library mode:156 157| Verdict | Condition (first match wins) |158| --- | --- |159| `NO VERDICT` | No page list and no Search Console rows |160| `FAIL` | 1 or more critical groups |161| `PASS WITH NOTES` | Moderate or low groups only |162| `PASS` | No clashes |163 164Named stops: every `REFRESH` that consolidates and every redirect or consolidate move waits for the reader to confirm the keeper (redirects move links and history). Any move on a page with external links stops for the reader. `NO VERDICT` asks for the missing input. No other stops.165 166## Learn167 168Append a learning to the profile when:169 170- the reader overrides a verdict or a move (write their reason as a `proposal`);171- the reader reports what happened after a merge or redirect, such as clicks to the keeper 60 days later (a `fact`, with its source);172- the reader marks a group as different intent that the rules called the same (a `proposal` to treat that page pair or page type as distinct).173 174Example: `- 2026-10-24 | cannibalization-audit | proposal | Treat /pricing and /guides/<category>-pricing as different intent | Why: reader confirmed the guide brings demos the pricing page doesn't (CRM, Oct 2026) | Status: proposed`175 176## Output177 178Topic mode:179 180```181Verdict: <PROCEED | DIFFERENTIATE | REFRESH | BLOCK | NO VERDICT> · Coverage: <complete | partial (what's missing) | blocked> · Rules run: <script | by hand>182Rule fired: <the condition, in words>183Fingerprint: <one sentence>184 185| Page | Score (0 to 4) | Class | Fresh | Demand (impressions) | Complete | Notes |186(candidates, best first; "not available" where data is missing)187 188Target page: <URL, or none>189Angle (DIFFERENTIATE only): <one sentence> · Link to: <sibling URL>190Data gaps: <list, or none>191Learnings applied: <list, or none>192```193 194Library mode:195 196```197Verdict: <PASS | PASS WITH NOTES | FAIL | NO VERDICT> · Coverage: <...> · Rows: <n> in, <n> branded dropped, <n> low-volume queries dropped198Counts: <n> critical, <n> moderate, <n> low199 200| Group | Severity | Pages | Keeper | Shared queries | Shared impressions | Move | Why |201(critical first)202 203Redirects proposed: <from URL> to <keeper URL>, one per line, each marked "confirm"204Learnings applied: <list, or none>205```206 207Then the handoff block.208 209## Hand off210 211```handoff212skill: cannibalization-audit213version: 2.0.0214verdict: REFRESH215coverage: partial (no modified dates)216for: <planned page, or "library audit">217outputs:218 mode: topic219 target_url: https://example.com/blog/attribution-software220 angle: not available221 clash_groups: 0222next: [refresh-audit]223open: [confirm the keeper before any redirect]224```225 226`next` by verdict: `PROCEED` and `DIFFERENTIATE` go to `[cluster-fit]`; `REFRESH` to `[refresh-audit]`; `BLOCK` to `[internal-linking]` (link to the page that owns the intent); library mode to `[content-triage]`, with `clash_groups` and each keeper listed in `outputs`.227 228## Failure modes229 230| Problem | Do this |231| --- | --- |232| The Search Console export has no page column (queries only) | Library mode can't find clashes from it. Ask for the page and query export; meanwhile group by title and H1, coverage `partial` |233| Every query looks branded because the brand is a common word | Use the full brand terms from the profile only, and list the queries you kept |234| A clash is between a page and its own URL with parameters or a trailing slash | Not a clash: a canonical problem. Report it as one and point to `agent-readiness` |235| The site has thousands of pages | Library mode on the script; topic mode on the 10 best candidates only |236| The reader wants a page written anyway after BLOCK | Record the override as a learning and hand the angle question to `keyword-selection` |237| Two pages target different countries or languages | Not a clash if each serves its own region; check hreflang instead |238 239## Influenced by240 241- SHAKEUP's content engine: verdicts from ordered rules anchored on intent, page health read from freshness, demand and completeness, and a near-exact match that can never pass as new.242- Google's guidance on consolidating duplicate URLs, which explains how redirects and canonicals pass signals to one page: https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls