Skip to content

Makes

Internal linking

Maps the internal links a page should give and get, with the anchor, the section and the position for each, from a crawl or a page list.

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 internal-linking.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
Link best practices
Needs
The page, as a draft or a live URL · Your site's pages, with title and status
Works with
Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md
Version
1.0.0 · Last checked · License MIT
Maintained by
Sabih AhmedOrganic visibility
SkillSEO and AI search

Internal linking

Example output

Map the links for a page
AnchorToCheck
which attribution modelModels postPass
click herePricingGeneric
partner appUncategorisedAsk first

Maps the internal links a page should give and get, with the anchor, the section and the position for each, from a crawl or a page list.

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

internal-linking/SKILL.md

In the folder

  • internal-linking/SKILL.md
  • internal-linking/scripts/link_map.py
---name: internal-linkingdescription: >-  Maps the internal links one B2B SaaS page should give and get: each destination, the anchor text, the section and  the position, plus the existing pages that should link to it and the phrase to link there. Classifies the site's  pages into link buckets from a crawl or a page list, checks the plan against caps, placement and anchor rules,  fixes what fails (at most 2 rounds) and returns READY, READY WITH NOTES, NOT READY or BLOCKED. Use it on a draft  before it ships or on a refreshed page. Not for choosing which cluster a page belongs to (use cluster-fit) or for  links to other sites.license: MITcompatibility: >-  Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads the sitemap and page statuses if  the agent can browse, otherwise a crawl export or a pasted page list. Python 3 is optional, for the bucket and plan  checks.metadata:  author: SHAKEUP  version: "1.0.0"  stage: make  plugin: seo-ai-search  homepage: https://www.shakeuphq.com/skills/internal-linking--- # Internal linking Gives a page the links a reader and a crawler need, and nothing that reads as filler or points at a dead end. ## Purpose - One job: produce the internal link map for one page, links out and links in, with anchors and positions.- Stage: make. It runs its own check, fixes and checks again, at most 2 rounds.- It owns links to pages on the reader's own site only. Links to other sites belong to the writer and `claim-check`.- It never links a URL it hasn't seen in the page list, and never invents a page. ## Use when / not | Situation | Use || --- | --- || A draft is close to final and needs its internal links | this skill || A page was refreshed and its links are stale | this skill, on the refreshed page || A new page just shipped and older pages should point to it | this skill, links in only || Deciding the page's cluster, pillar and link targets at the plan stage | `cluster-fit` (its targets feed this skill) || Checking whether 2 pages compete | `cannibalization-audit` | ## Inputs | Input | Required | Ways to provide, in order | If missing || --- | --- | --- | --- || 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 || 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 || Planned targets | no | the `cluster-fit` handoff (`links_out`, `links_in`); the `refresh-audit` handoff | found from the page list alone || Page performance | no | a connected Search Console; a Pages export | links in are chosen on relevance only; say so | ## Profile read From `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`. No profile: ask for the website, in one message. Say that `company-profile` saves this next time. ## Steps 1. **Apply learnings.** Read them first. A learning that reclassifies a URL pattern ("/academy/ is content") or changes a cap overrides the default. 2. **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:    | Bucket | URL patterns | Links per page | Placement |   | --- | --- | --- | --- |   | excluded | /privacy, /terms, /cookie, /legal, /help, /support, /faq, /kb, /status, /login, /account, /dashboard, /admin, /lp/, /landing/, tracking parameters | 0 | never |   | conversion | /demo, /contact, /trial, /get-started, /signup, /book | 1 | final 20%, as the page's one call to action |   | pricing | /pricing, /plans | 1 | after 70%, or in the closing call to action |   | product | /product, /features, /solutions, /platform, /integrations, /use-cases | 1 | after 30%, only where the section is about that product |   | resources | /case-studies, /customers, /reports, /research | 2 | after 10% |   | company | /about, /team, /careers, the homepage | 0 | only with a person's yes |   | content | /blog, /guides, /glossary, /learn, /compare, /vs | no cap | after 10%, where the concept is discussed |   | uncategorised | anything else | 0 | flag for the reader to classify |    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. 3. **Find links out.** With Python, write the index, the page's sections and any planned targets to JSON and run:    ```   python3 scripts/link_map.py --json links.json   ```    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. 4. **Pick the anchor** for each link out:    | Rule | Why |   | --- | --- |   | 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 |   | Never "click here", "learn more", "read more", "this article" | says nothing about the destination |   | Never the destination's full title | reads as a promotion, not a reference |   | Read alone, it should feel incomplete | a self-contained label is usually generic |   | Don't rewrite a sentence to fit an anchor; if no phrase fits, skip the link | a forced anchor reads worse than no link |   | A named product or feature the site has a page for links to that page | it ties the entity name to its page | 5. **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. 6. **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`. 7. **Write the map** in the output shape, then run the loop. ## Check and verdict The check runs on the map (`scripts/link_map.py` with the plan in the JSON, or each rule by eye; say which): | Finding | Severity || --- | --- || Destination not in the page list, or not 200 | critical || Excluded or uncategorised destination | critical || Generic anchor | critical || Duplicate destination, or one anchor to 2 destinations | critical || Over a bucket cap, or placed before the bucket's earliest point, or in the first 10% | critical || Status unknown | warning || Anchor under 2 or over 6 words, or the destination's title as the anchor | warning || Company destination | warning (a person decides) || A new sentence written to hold a link in | warning until `voice-check` passes it | | Verdict | Condition (first match wins) || --- | --- || `BLOCKED` | No page text, or no page list after asking || `NOT READY` | Critical findings remain after 2 rounds || `READY WITH NOTES` | Warnings only || `READY` | No findings | Named stops: company-page links and uncategorised pages wait for the reader's call. No other stops. ## Loop 1. Run the check on the map.2. 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).3. Check again. At most 2 rounds; then hand over with what is still open, labelled. ## Learn Append a learning to the profile when: - the reader reclassifies a URL pattern or approves a company link (a `fact`, applied at once);- the reader rejects a link as off-topic (a `proposal` to raise the relevance bar for that page pair);- a result comes back, such as a page that started ranking after links in were added (a `fact` with its source). Example: `- 2026-10-24 | internal-linking | fact | /academy/ pages are content, not uncategorised | Why: reader classified them | Status: noted` ## Output ```Verdict: <READY | READY WITH NOTES | NOT READY | BLOCKED> · Coverage: <complete | partial (what's missing)> · Check: <script | by hand> · Rounds: <n>Pages indexed: <n> · linkable: <n> · excluded: <n> · uncategorised: <n> (listed for the reader) Links out:| # | Section | Sentence (short) | Anchor | Destination | Bucket | Position | Links in:| # | Source page | Where (sentence or "new sentence") | Anchor | Why | Missing targets (pages that should exist): <list, or none>Open: <warnings left, company links awaiting a yes, pages to classify>Learnings applied: <list, or none>``` Then the handoff block. ## Hand off ```handoffskill: internal-linkingversion: 1.0.0verdict: READY WITH NOTEScoverage: partial (statuses not confirmed for 3 pages)for: https://example.com/blog/attribution-softwareoutputs:  links_out: 7  links_in: 4  new_sentences: 1  status_unconfirmed: [https://example.com/blog/b2b-attribution-models]next: [voice-check, meta-serp-copy]open: [confirm 3 statuses, voice-check the new sentence]``` ## Failure modes | Problem | Do this || --- | --- || The sitemap lists URLs that redirect | Index the final URL; never link the old one || Every page is under one folder, so patterns say little | Classify by title and page type; mark the index as by-hand || 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 || 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 || The page list is thousands of URLs | Index content pages in the page's cluster plus every product, pricing and conversion page || 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 | ## Influenced by - 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.- Google's link guidance, which asks for descriptive anchor text and crawlable links: https://developers.google.com/search/docs/crawling-indexing/links-crawlable

How it thinks

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

What we built

Links are capped by bucket so a guide doesn't turn into a sales page, and the anchor must read incomplete without its sentence, which rules out labels like learn more. It only links pages it has seen return a live status.

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

    Sort your pages into buckets

    Content, product, pricing, demo, resources, company, excluded and uncategorised, by URL pattern. Legal, login and ad landing pages are never linked.

  2. 02

    Find the links out

    Its script matches each section against your page titles. A link is kept only when the page is about the concept in that sentence.

  3. 03

    Pick the anchor from the sentence

    2 to 6 words that name the concept. Never click here, never the full title of the page on the other side.

  4. 04

    Place each link

    Never in the intro, a heading or the first 10% of the page. One product, one pricing and one demo link, each in its own part of the page.

  5. 05

    Find the links in

    Up to 5 existing pages that should point here, with the sentence and the anchor for each.

  6. 06

    Check, fix, check again

    Dead pages, generic anchors, repeats and broken caps are fixed, at most twice, then handed over with anything still open.

What you need

  • Required

    The page, as a draft or a live URL

    A file your agent can read → The URL, if your agent can browse → Text you paste

  • Required

    Your site's pages, with title and status

    It reads your sitemap and checks each status if your agent can browse → A crawl export with status codes → A list you paste

  • Optional

    Planned link targets

    The handoff from cluster fit → The handoff from a refresh audit

  • Optional

    Page performance

    A connected Search Console → A Pages export

What it can return

  • READY

    Every link passes the checks.

  • READY WITH NOTES

    Only warnings remain, such as a status nobody confirmed or a company page waiting for your yes.

  • NOT READY

    A critical problem is still there after 2 rounds of fixes.

  • BLOCKED

    There's no page text or no page list.

Where it stops for you

  • Before linking an about, team or careers page
  • When a page fits no bucket and needs you to classify it

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 247-word draft comparing attribution tools, checked against a crawl of 12 pages.

Verdict

READY

Coverage: complete

Check: script

Rounds: 1

SectionAnchorDestinationBucketPosition
What attribution software doeswhich attribution model/blog/b2b-attribution-modelsContent34%
What attribution software doesself-reported attribution/blog/self-reported-attributionContent41%
How to compare toolspipeline by channel report/blog/pipeline-by-channel-reportContent68%
How to compare toolspipeline attribution/product/pipeline-attributionProduct72%
Pricingour own plans/pricingPricing85%
Next stepbook a demo/demoDemo95%
Links in

the pillar /guides/b2b-attribution, at its section on choosing a tool, and the models post, at its line on comparing vendors.

Left out

a 404 post on paid social, the privacy and about pages, and a partner page that fits no bucket. It's listed for you to classify.

The handoff block the next skill reads
skill: internal-linking
version: 1.0.0
verdict: READY
coverage: complete
for: /blog/attribution-software-compared
outputs:
  links_out: 6
  links_in: 2
next: [meta-serp-copy]
open: [classify /partners/crm-app]

What good looks like

  • Every destination is on your page list with a live status
  • Anchors name the concept in 2 to 6 words
  • No link in the intro, a heading or the first 10% of the page
  • One product, pricing and demo link at most, each in its place
  • Links in come with the exact sentence to link on the other page

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 a crawl?

It needs a page list with titles. Status codes make it safe. Without them, every link is marked unconfirmed and the result carries notes.

Why only one pricing and one demo link?

A guide earns trust by answering the question. One clear next step at the end works. Several sales links in the body read as a pitch and bury the links that help.

Will it add sentences to my pages?

Only for links in, when a page that should point here never mentions the concept. The new sentence is marked for a voice check before it ships.

What does the script do?

It sorts your pages into buckets, suggests targets for each section and checks the plan against the caps, placement and anchor rules. Without Python, the skill applies the same rules itself and says so.