agentleFS
keuperakeupera/seo-skills/skills/internal-linking-architecture/SKILL.md

internal-linking-architecture

Skill0 starsChanged 2 months agoMITView on GitHub

Design and fix a site's internal link structure so authority flows to the pages that matter and every page is reachable. Use whenever the user asks about internal links, internal linking, site architecture, site structure, URL hierarchy, orphan pages, crawl depth, link equity, PageRank distribution, anchor text, breadcrumbs, pillar pages, topic clusters, hub and spoke, or navigation and menu structure. Also use when pages are indexed but not ranking, or when a site has grown past a few hundred pages without a plan.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before moving a single link, write down the ranked list of pages that matter.

    line 46
  2. Distinctive:

    The hub links down to every spoke: If it doesn't, the spoke isn't part of the cluster.

    line 70
  3. Distinctive:

    Not all links on a page carry equal weight, and the differences are practical rather than mystical.

    line 91
  4. Distinctive:

    Don't chase a PageRank number: No external tool has Google's internal values.

    line 117
  5. Distinctive:

    If there's no time for a full audit, this captures most of the value:

    line 121
  6. Very specific:

    Search the site for the terms those pages target: site:example.com "term".

    line 124
  7. Distinctive:

    Check the sitemap for URLs with zero inbound links and deal with them.

    line 126
  8. Distinctive:

    Add breadcrumbs if they're missing.

    line 127

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Internal Linking Architecture

Internal links are the only ranking lever you fully control. No outreach, no permission, no budget. They decide what a crawler finds, how important it concludes each page is, and what each page is about.

Most sites get this wrong in the same way: hundreds of links pointing at the homepage and the blog index, and three links pointing at the page that makes money.

The three jobs internal links do

  1. Discovery. A page nothing links to is a page that may never be crawled, whatever the sitemap says.
  2. Authority distribution. Link equity flows along internal links. Where you point it is a decision, whether or not you make it deliberately.
  3. Topical definition. The anchor text pointing at a page, and the pages that link to it, tell a search engine what the page is about. This is often stronger than the page's own copy.

Step 1: Map what exists

You cannot fix a structure you haven't seen. Build the actual link graph.

# Crawl the site and extract internal links per page
# (any crawler works; the point is the graph, not the tool)
curl -s https://example.com/sitemap.xml | grep -oP '(?<=<loc>)[^<]+' > urls.txt
while read -r u; do
  curl -s "$u" \
    | grep -oP '(?<=href=")(/[^"#?]*|https://example\.com/[^"#?]*)' \
    | sed "s|^|$u |"
done < urls.txt > links.tsv

# Inbound internal links per page, ascending: the bottom of this list is the problem
awk '{print $2}' links.tsv | sort | uniq -c | sort -n | head -40

Three numbers come out of that graph, and they're the whole diagnosis:

MetricHealthyProblem
Inbound internal links per important page10+0 to 2
Click depth from the homepage3 or fewer5+
Orphan pages (in sitemap, zero inbound links)0Any

Step 2: Decide where authority should go

Before moving a single link, write down the ranked list of pages that matter. Usually:

  1. Money pages — product, pricing, high-intent category and comparison pages
  2. Hub pages — the pillar page for each topic the site wants to own
  3. Supporting content — everything else

Then compare that ranking against the inbound-link counts from step 1. The mismatch is your work list. It's normal to find that the third most important page on a site has two internal links and the cookie policy has four hundred.

Step 3: Build hubs, not a pile

The structure that works is boring and it works everywhere.

Homepage
  └── Hub page: "Email deliverability"        ← targets the head term
        ├── Spoke: "What is SPF"              ← links up to hub, sideways to DKIM
        ├── Spoke: "What is DKIM"             ← links up to hub, sideways to SPF
        ├── Spoke: "How to fix a spam folder problem"
        └── Spoke: "Warming a new sending domain"

The rules that make it work:

  • Every spoke links up to its hub, with anchor text close to the hub's target term.
  • The hub links down to every spoke. If it doesn't, the spoke isn't part of the cluster.
  • Spokes link sideways to genuinely related spokes. Two or three, not all of them.
  • Clusters don't cross-link promiscuously. A link from the email cluster into the billing cluster should have a reason.

Topic selection for the hubs is a separate job. See topical-authority-map.

Step 4: Anchor text

Anchor text is the single strongest on-page signal for what the target page is about, and it's mostly wasted.

DoDon't
"our guide to canonical tags""click here", "read more", "this post"
Vary it naturally across linksUse identical exact-match anchors 200 times
Describe the destinationDescribe the current sentence
Keep it in the flow of a sentenceBolt on a "Related:" block and stop

Exact-match anchors are fine in moderation and start looking manipulative at volume. The natural pattern is a mix: the exact term sometimes, a partial phrase often, and the page title or a descriptive phrase the rest of the time.

Step 5: Placement

Not all links on a page carry equal weight, and the differences are practical rather than mystical.

  • In-content links are worth more than boilerplate links. A link in the third paragraph of a relevant article beats the same link in the footer.
  • Sitewide footer link menus dilute. Two hundred footer links spread authority thinly and tell a crawler nothing about relevance. Keep the footer for navigation people actually use.
  • Navigation is a statement of priority. What's in the main nav is what the site says matters. Treat menu slots as expensive.
  • Breadcrumbs are cheap and effective. They create a consistent upward path, reduce click depth and produce a better SERP display with BreadcrumbList markup.
  • The first link to a URL on a page is the one that counts for anchor text in most implementations. Don't waste it on a logo or a nav item.

Step 6: Fix the specific failures

Orphan pages. For each one, either find three relevant pages that should link to it, or accept that nothing wants to link to it and remove or merge it. Orphans are usually a symptom that the page shouldn't exist.

Deep pages. Anything more than three clicks from the homepage needs a hub, a category page or a genuinely useful index that shortens the path. Pagination is the usual culprit; /blog/page/47 buries everything on it.

Redirect chains in internal links. Internal links should point at the final URL. Pointing at a redirect works but wastes crawl budget and is trivially fixable with find-and-replace.

Links to noindexed pages. Wasteful. Authority flows in and stops.

Nofollow on internal links. Almost never correct. It doesn't sculpt PageRank; it discards it.

Don't do these

  • Don't add a "Related posts" widget and call it done. Automated related-post blocks generate links with no anchor text control and weak relevance. They're better than nothing and much worse than deliberate in-content links.
  • Don't link every occurrence of a term. One link per destination per page is enough.
  • Don't build a link scheme between your own sites and treat it as internal linking. That's a link scheme.
  • Don't restructure URLs to fix linking. Changing URLs means redirects, and redirects mean risk. Fix the links, keep the URLs. If a migration is genuinely needed, see redirect-migration-plan.
  • Don't chase a PageRank number. No external tool has Google's internal values. Use inbound link counts and click depth, which you can measure.

A 30-minute version

If there's no time for a full audit, this captures most of the value:

  1. List the five pages that matter commercially.
  2. Search the site for the terms those pages target: site:example.com "term".
  3. On each page that comes back, add one in-content link to the target with descriptive anchor text.
  4. Check the sitemap for URLs with zero inbound links and deal with them.
  5. Add breadcrumbs if they're missing.

Where the data comes from

Click depth, orphan detection and the internal link graph come from crawling the site, which the script above does adequately for a few thousand pages. Search Console's Links report shows Google's own view of internal link counts, free, and it's worth comparing against your crawl. Where they disagree, Google's view is the one that ranks.

For sites large enough that this needs re-running rather than doing once, Keupera includes site audits with internal link and crawl depth reporting, over MCP alongside the keyword and content data, so the link graph and the priority list can be compared without exporting anything.

Related skills

topical-authority-map, technical-seo-audit, redirect-migration-plan, keyword-cannibalization, ecommerce-seo, programmatic-seo

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.