1---2name: internal-linking3description: >-4 Maps the internal links one B2B SaaS page should give and get: each destination, the anchor text, the section and5 the position, plus the existing pages that should link to it and the phrase to link there. Classifies the site's6 pages into link buckets from a crawl or a page list, checks the plan against caps, placement and anchor rules,7 fixes what fails (at most 2 rounds) and returns READY, READY WITH NOTES, NOT READY or BLOCKED. Use it on a draft8 before it ships or on a refreshed page. Not for choosing which cluster a page belongs to (use cluster-fit) or for9 links to other sites.10license: MIT11compatibility: >-12 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads the sitemap and page statuses if13 the agent can browse, otherwise a crawl export or a pasted page list. Python 3 is optional, for the bucket and plan14 checks.15metadata:16 author: SHAKEUP17 version: "1.0.0"18 stage: make19 plugin: seo-ai-search20 homepage: https://www.shakeuphq.com/skills/internal-linking21---22 23# Internal linking24 25Gives a page the links a reader and a crawler need, and nothing that reads as filler or points at a dead end.26 27## Purpose28 29- One job: produce the internal link map for one page, links out and links in, with anchors and positions.30- Stage: make. It runs its own check, fixes and checks again, at most 2 rounds.31- It owns links to pages on the reader's own site only. Links to other sites belong to the writer and `claim-check`.32- It never links a URL it hasn't seen in the page list, and never invents a page.33 34## Use when / not35 36| Situation | Use |37| --- | --- |38| A draft is close to final and needs its internal links | this skill |39| A page was refreshed and its links are stale | this skill, on the refreshed page |40| A new page just shipped and older pages should point to it | this skill, links in only |41| Deciding the page's cluster, pillar and link targets at the plan stage | `cluster-fit` (its targets feed this skill) |42| Checking whether 2 pages compete | `cannibalization-audit` |43 44## Inputs45 46| Input | Required | Ways to provide, in order | If missing |47| --- | --- | --- | --- |48| The page: draft text with headings, or the live URL | yes | a file the agent can read; the URL if it can browse; pasted text | ask for it |49| The site's pages: URL, title, status | yes | the sitemap and a status check if the agent can browse; a crawl export (CSV) with status codes; a pasted list | `BLOCKED`; never guess URLs |50| Planned targets | no | the `cluster-fit` handoff (`links_out`, `links_in`); the `refresh-audit` handoff | found from the page list alone |51| Page performance | no | a connected Search Console; a Pages export | links in are chosen on relevance only; say so |52 53## Profile read54 55From `company-profile.md`: `## Company` (website), `## Product` (product and feature pages worth an entity link), `## Content` (site sections, clusters, pillars), `## Voice` (for any sentence written to hold a link), and every `## Learnings` entry for `internal-linking` with status `noted`, `fact` or `accepted`.56 57No profile: ask for the website, in one message. Say that `company-profile` saves this next time.58 59## Steps60 611. **Apply learnings.** Read them first. A learning that reclassifies a URL pattern ("/academy/ is content") or changes a cap overrides the default.62 632. **Build the index.** List every page with its title and status. Keep only status 200 as linkable; a page whose status is unknown stays a candidate with a warning. Classify each by URL pattern, first match wins:64 65 | Bucket | URL patterns | Links per page | Placement |66 | --- | --- | --- | --- |67 | excluded | /privacy, /terms, /cookie, /legal, /help, /support, /faq, /kb, /status, /login, /account, /dashboard, /admin, /lp/, /landing/, tracking parameters | 0 | never |68 | conversion | /demo, /contact, /trial, /get-started, /signup, /book | 1 | final 20%, as the page's one call to action |69 | pricing | /pricing, /plans | 1 | after 70%, or in the closing call to action |70 | product | /product, /features, /solutions, /platform, /integrations, /use-cases | 1 | after 30%, only where the section is about that product |71 | resources | /case-studies, /customers, /reports, /research | 2 | after 10% |72 | company | /about, /team, /careers, the homepage | 0 | only with a person's yes |73 | content | /blog, /guides, /glossary, /learn, /compare, /vs | no cap | after 10%, where the concept is discussed |74 | uncategorised | anything else | 0 | flag for the reader to classify |75 76 Why the caps: one product, pricing and conversion link each keeps the page about the reader's question; more turns it into a sales page and buries the links that help.77 783. **Find links out.** With Python, write the index, the page's sections and any planned targets to JSON and run:79 80 ```81 python3 scripts/link_map.py --json links.json82 ```83 84 Without Python: for each section, list pages whose title words mostly appear in the section (half or more). Either way, keep a candidate only when the destination is specifically about the concept in that sentence, not just near it. Add every `cluster-fit` target: the pillar first.85 864. **Pick the anchor** for each link out:87 88 | Rule | Why |89 | --- | --- |90 | The phrase in the sentence that names the concept, 2 to 6 words | it tells the reader and the crawler what's on the other side |91 | Never "click here", "learn more", "read more", "this article" | says nothing about the destination |92 | Never the destination's full title | reads as a promotion, not a reference |93 | Read alone, it should feel incomplete | a self-contained label is usually generic |94 | Don't rewrite a sentence to fit an anchor; if no phrase fits, skip the link | a forced anchor reads worse than no link |95 | A named product or feature the site has a page for links to that page | it ties the entity name to its page |96 975. **Place each link.** At the first mention of the concept in a section, never in the intro, a heading or the first paragraph under a heading, never in the first 10% of the page's words. Each destination once per page; each anchor points to one destination. One exception: the page's closing call to action (the conversion link, and a pricing link inside it) may sit in the first paragraph of the final section, since that section exists to hold it.98 996. **Find links in.** Up to 5 existing pages that should link to this one: the pillar, siblings that mention the concept, and pages that now link to a weaker page on it. Prefer pages with clicks or impressions when the data exists (they are crawled more often). For each: the source URL, the sentence where the concept is mentioned, the anchor. If a source page never mentions the concept, write one sentence that does, in the profile's voice, and mark it for `voice-check`.100 1017. **Write the map** in the output shape, then run the loop.102 103## Check and verdict104 105The check runs on the map (`scripts/link_map.py` with the plan in the JSON, or each rule by eye; say which):106 107| Finding | Severity |108| --- | --- |109| Destination not in the page list, or not 200 | critical |110| Excluded or uncategorised destination | critical |111| Generic anchor | critical |112| Duplicate destination, or one anchor to 2 destinations | critical |113| Over a bucket cap, or placed before the bucket's earliest point, or in the first 10% | critical |114| Status unknown | warning |115| Anchor under 2 or over 6 words, or the destination's title as the anchor | warning |116| Company destination | warning (a person decides) |117| A new sentence written to hold a link in | warning until `voice-check` passes it |118 119| Verdict | Condition (first match wins) |120| --- | --- |121| `BLOCKED` | No page text, or no page list after asking |122| `NOT READY` | Critical findings remain after 2 rounds |123| `READY WITH NOTES` | Warnings only |124| `READY` | No findings |125 126Named stops: company-page links and uncategorised pages wait for the reader's call. No other stops.127 128## Loop129 1301. Run the check on the map.1312. Fix each critical finding: swap a dead destination for its final URL from the page list or drop the link, rewrite a generic anchor from the sentence's own words, move a link past its bucket's point, drop the extra links over a cap (keep the most specific one).1323. Check again. At most 2 rounds; then hand over with what is still open, labelled.133 134## Learn135 136Append a learning to the profile when:137 138- the reader reclassifies a URL pattern or approves a company link (a `fact`, applied at once);139- the reader rejects a link as off-topic (a `proposal` to raise the relevance bar for that page pair);140- a result comes back, such as a page that started ranking after links in were added (a `fact` with its source).141 142Example: `- 2026-10-24 | internal-linking | fact | /academy/ pages are content, not uncategorised | Why: reader classified them | Status: noted`143 144## Output145 146```147Verdict: <READY | READY WITH NOTES | NOT READY | BLOCKED> · Coverage: <complete | partial (what's missing)> · Check: <script | by hand> · Rounds: <n>148Pages indexed: <n> · linkable: <n> · excluded: <n> · uncategorised: <n> (listed for the reader)149 150Links out:151| # | Section | Sentence (short) | Anchor | Destination | Bucket | Position |152 153Links in:154| # | Source page | Where (sentence or "new sentence") | Anchor | Why |155 156Missing targets (pages that should exist): <list, or none>157Open: <warnings left, company links awaiting a yes, pages to classify>158Learnings applied: <list, or none>159```160 161Then the handoff block.162 163## Hand off164 165```handoff166skill: internal-linking167version: 1.0.0168verdict: READY WITH NOTES169coverage: partial (statuses not confirmed for 3 pages)170for: https://example.com/blog/attribution-software171outputs:172 links_out: 7173 links_in: 4174 new_sentences: 1175 status_unconfirmed: [https://example.com/blog/b2b-attribution-models]176next: [voice-check, meta-serp-copy]177open: [confirm 3 statuses, voice-check the new sentence]178```179 180## Failure modes181 182| Problem | Do this |183| --- | --- |184| The sitemap lists URLs that redirect | Index the final URL; never link the old one |185| Every page is under one folder, so patterns say little | Classify by title and page type; mark the index as by-hand |186| The draft has no place where a key target fits | Leave it out and say so; don't add a paragraph just to hold a link |187| The reader asks for the keyword as the anchor on every link to one page | Vary anchors with the sentence; one destination appears once per page |188| The page list is thousands of URLs | Index content pages in the page's cluster plus every product, pricing and conversion page |189| A source page for a link in belongs to another team (docs, help center) | List it, mark it for that team; help pages are excluded as destinations, not as sources |190 191## Influenced by192 193- SHAKEUP's content engine: link buckets with caps and placement points, the ban on title-as-anchor, and the test that an anchor should read incomplete without its sentence.194- Google's link guidance, which asks for descriptive anchor text and crawlable links: https://developers.google.com/search/docs/crawling-indexing/links-crawlable