Internal Linking Optimizer

Internal Linking Optimizer

Analyze a site's internal link structure and provide actionable recommendations to improve SEO through strategic internal linking. Helps distribute authority, establish topical relevance, and improve crawlability.

When to use this skill

• Improving site architecture for SEO
• Distributing authority to important pages
• Fixing orphan pages with no internal links
• Creating topic cluster internal link strategies
• Optimizing anchor text for SEO
• Recovering pages that have lost rankings
• Planning internal links for new content

Prerequisites

Tiger Den (required)

Read REFERENCES.md from the plugin root and run the pre-flight check described there. Call list_marketing_references() to verify Tiger Den is reachable. If it fails or the tool is not found, STOP — do not continue. Follow the error handling in REFERENCES.md.

Instructions

1. Gather input

Ask the user to provide:

1. Key page URLs that need more internal links — specific pages to focus on 2. Content categories or topic clusters — how the site's content is organized (or should be) 3. Any existing link structure documentation — crawl exports, link maps, or notes on current architecture

The user may also provide a sitemap URL, a CSV of page URLs, or a manually curated list — but these are optional since Step 2 builds a verified URL inventory automatically.

2. Build verified URL inventory

Before analyzing link structure, build a complete inventory of real, verified URLs. This prevents suggesting broken links with incorrect path prefixes (e.g., missing /learn/ or /blog/).

Step 2a: Tiger Den content search

Use the key pages and topic clusters gathered in Step 1 as query terms. Search Tiger Den for all content related to the site's topics:

search_content(query: "{primary topic}")
search_content(query: "{topic variant 1}")
search_content(query: "{topic variant 2}")

Run 3-5 queries covering the site's core topic areas. Collect all returned URLs — these are verified marketing site links with correct path prefixes (/learn/, /blog/, /cloud/, etc.).

Step 2b: Sitemap fetch (secondary source)

Fetch and parse the site's sitemap to catch pages Tiger Den may not index:

fetch https://www.tigerdata.com/sitemap.xml

If the response is a <sitemapindex> (an index of child sitemaps rather than direct <url> entries), fetch each child <sitemap><loc> entry and collect all <loc> entries from those child sitemaps.

Parse all <loc> entries and merge with the Tiger Den results. The sitemap is the authoritative source for URL paths — if a slug appears in both sources, prefer the sitemap's URL format.

If the sitemap fetch fails or returns an error (404, timeout, malformed XML), proceed with Tiger Den results only and note the limitation in the output.

Step 2c: Merge and deduplicate

Combine Tiger Den results and sitemap entries into a single verified URL inventory. Deduplicate by slug (the path segment after the last /). Every URL in this inventory must:

• Be a full URL starting with https:// (never http://)
• Include the correct path prefix (/learn/, /blog/, /cloud/, /docs/, etc.)
• Use the https://www.tigerdata.com/ domain

This inventory is the only source for link suggestions in all subsequent steps. Do not suggest any URL that is not in this inventory.

3. Analyze current internal link structure

Map the current internal linking patterns across the provided pages. Only reference URLs from the verified inventory (Step 2).

## Internal Link Structure Analysis

### Overview

**Domain**: [domain]
**Total Pages Analyzed**: [X]
**Total Internal Links**: [X]
**Average Links per Page**: [X]

### Link Distribution

| Links per Page | Page Count | Percentage |
|----------------|------------|------------|
| 0 (Orphan) | [X] | [X]% |
| 1-5 | [X] | [X]% |
| 6-10 | [X] | [X]% |
| 11-20 | [X] | [X]% |
| 20+ | [X] | [X]% |

### Top Linked Pages

| Page | Internal Links | Authority | Notes |
|------|----------------|-----------|-------|
| [URL 1] | [X] | High | [notes] |
| [URL 2] | [X] | High | [notes] |
| [URL 3] | [X] | Medium | [notes] |

### Under-Linked Important Pages

| Page | Current Links | Traffic | Recommended Links |
|------|---------------|---------|-------------------|
| [URL 1] | [X] | [X]/mo | [X]+ |
| [URL 2] | [X] | [X]/mo | [X]+ |

**Structure Score**: [X]/10

4. Identify orphan pages

Find pages with no internal links pointing to them.

## Orphan Page Analysis

### Orphan Pages Found: [X]

| Page | Traffic | Priority | Recommended Action |
|------|---------|----------|-------------------|
| [URL 1] | [X]/mo | High | Link from [pages] |
| [URL 2] | [X]/mo | Medium | Add to navigation |
| [URL 3] | 0 | Low | Consider deleting/redirecting |

### Fix Strategy

**High Priority Orphans** (have traffic/rankings):
1. [URL] - Add links from: [relevant pages]

**Medium Priority Orphans** (potentially valuable):
1. [URL] - Add to category/tag page

**Low Priority Orphans** (consider removing):
1. [URL] - Redirect to [better page]

5. Analyze anchor text distribution

Review anchor text patterns and flag issues (generic anchors, over-optimization, same anchor to multiple pages).

## Anchor Text Analysis

### Current Anchor Text Patterns

| Anchor Text | Count | Target Pages | Assessment |
|-------------|-------|--------------|------------|
| "click here" | [X] | [X] pages | Not descriptive |
| "read more" | [X] | [X] pages | Not descriptive |
| "[exact keyword]" | [X] | [page] | May be over-optimized |
| "[descriptive phrase]" | [X] | [page] | Good |

### Anchor Text Recommendations

For each flagged page, suggest 3-4 anchor text variations:
- Exact match (10-20% of anchors)
- Partial match (30-40%)
- Branded (10-20%)
- Natural (20-30%)

**Anchor Score**: [X]/10

6. Create topic cluster link strategy

Map current pillar/cluster links, recommend link structure, and list specific links to add.

Reference: See the linking templates for the topic cluster link strategy template.

7. Find contextual link opportunities

Analyze each page for topic-relevant link opportunities and prioritize high-impact additions. Every suggested link must exist in the verified URL inventory from Step 2.

Reference: See the linking templates for the contextual link opportunities template.

8. Optimize navigation and footer links

Analyze main/footer/sidebar/breadcrumb navigation and recommend pages to add or remove.

Reference: See the linking templates for the navigation optimization template.

9. Generate link implementation plan

Produce an executive summary, current state metrics, phased priority actions (weeks 1-4+), implementation guide, and tracking plan.

Reference: See the linking templates for the full implementation plan template.

Validation checkpoints

Input validation

• Tiger Den pre-flight check passed
• Target pages or topic clusters clearly defined
• If optimizing a specific page, page URL or content provided

URL verification (enforced across all steps)

• Every suggested URL must exist in the verified inventory built in Step 2
• All URLs must be full URLs starting with https:// — never http://, never relative paths
• All URLs must include the correct path prefix (/learn/, /blog/, /cloud/, /docs/, etc.)
• All internal URLs must use the https://www.tigerdata.com/ domain
• If a URL cannot be verified against Tiger Den or the sitemap, do not suggest it

Output validation

• Every recommendation cites specific data points (not generic advice)
• All link suggestions include source page, target page, and recommended anchor text
• Orphan page lists include URLs and recommended actions
• Source of each data point clearly stated (Tiger Den, sitemap, crawl data, or user-provided)

Reference docs

• Link Architecture Patterns — Architecture models (hub-and-spoke, silo, flat, pyramid, mesh), anchor text diversity framework, link equity flow model, and measurement frameworks
• Linking Templates — Output templates for steps 6-9 (topic clusters, contextual opportunities, navigation, implementation plan)
• Linking Example — Full worked example for internal linking opportunities

Tips for success

1. Quality over quantity — add relevant links, not random ones 2. User-first thinking — links should help users navigate 3. Vary anchor text — avoid over-optimization 4. Link to important pages — distribute authority strategically 5. Regular audits — internal links need maintenance as content grows

Related skills

• seo-meta-optimizer — Optimize title tags and meta descriptions
• brand-voice-writer — Write on-brand content that includes strategic internal links
• content-reviewer — Review content quality including link structure

Attribution

Based on aaron-he-zhu/seo-geo-claude-skills internal-linking-optimizer, adapted for the TigerData marketing skills plugin.

Link Architecture Patterns

Detailed architecture models with implementation guides, migration strategies, and measurement frameworks for internal linking optimization.

Architecture Model Deep Dives

1. Hub-and-Spoke (Topic Cluster) Model

Overview

The hub-and-spoke model organizes content around central "pillar" pages (hubs) that link to and from related "cluster" articles (spokes). This is the most widely recommended architecture for content-driven sites targeting topical authority.

Structure Diagram

                    ┌──────────────┐
                    │   Homepage   │
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
     ┌──────▼──────┐ ┌────▼────┐  ┌──────▼──────┐
     │  Hub A      │ │  Hub B  │  │  Hub C      │
     │ (Pillar)    │ │(Pillar) │  │ (Pillar)    │
     └──┬───┬───┬──┘ └────┬────┘  └──┬───┬───┬──┘
        │   │   │         │          │   │   │
       A1  A2  A3       B1  B2     C1  C2  C3
        └───┼───┘               └───┼───┘
         cross-links             cross-links

Implementation Steps

1. Identify 3-7 core topics that define your business expertise 2. Create pillar pages (2,000-5,000 words) that broadly cover each core topic 3. Map cluster articles (800-2,000 words) that dive deep into subtopics 4. Implement bidirectional links: every cluster article links to its pillar, every pillar links to all its clusters 5. Add cross-links between related cluster articles within the same hub 6. Add bridge links between hubs where subtopics overlap

Link Rules

When to Use

• Content marketing sites and blogs
• SaaS companies building topical authority
• Publishers covering defined topic areas
• Any site with 50-500 content pages

Measurement

---

2. Silo Structure

Overview

The silo model creates strict vertical hierarchies where content is organized into isolated "silos" (categories). Links flow vertically within a silo but rarely cross between silos. This concentrates topical relevance within each silo.

Structure Diagram

                    ┌──────────────┐
                    │   Homepage   │
                    └──────┬───────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼─────┐     ┌────▼─────┐     ┌────▼─────┐
    │  Silo A  │     │  Silo B  │     │  Silo C  │
    │ Category │     │ Category │     │ Category │
    └────┬─────┘     └────┬─────┘     └────┬─────┘
         │                │                │
    ┌────▼─────┐     ┌────▼─────┐     ┌────▼─────┐
    │ Sub-cat  │     │ Sub-cat  │     │ Sub-cat  │
    └────┬─────┘     └────┬─────┘     └────┬─────┘
         │                │                │
    ┌────▼────┐      ┌────▼────┐      ┌────▼────┐
    │  Pages  │      │  Pages  │      │  Pages  │
    └─────────┘      └─────────┘      └─────────┘

    No horizontal links between silos (strict model)

Implementation Steps

1. Define 5-15 top-level categories (silos) based on your product/service taxonomy 2. Create category landing pages with overview content and links to subcategories 3. Build subcategory pages linking down to individual product/content pages 4. Enforce vertical linking: pages link up to their parent and down to their children 5. Use breadcrumbs to reinforce the hierarchy visually and structurally 6. Limit cross-silo links to only the most relevant connections (strict model) or allow them strategically (modified model)

Link Rules

When to Use

• Large e-commerce sites (100+ product categories)
• Directory sites with clear taxonomy
• Sites where categories are truly distinct topics
• Enterprises with separate business lines

Limitations

• Overly strict silos can trap link equity in one branch
• Cross-topic content becomes difficult to place
• Users may need to navigate up and over to find related content
• Modified silo (allowing some cross-links) often works better in practice

---

3. Flat Architecture

Overview

A flat architecture keeps all pages within 2-3 clicks of the homepage. There is minimal hierarchy; instead, pages are broadly interlinked. This maximizes crawlability and distributes link equity evenly.

Structure Diagram

              ┌──────────┐
              │ Homepage │
              └────┬─────┘
                   │
    ┌──────────────┼──────────────┐
    │    │    │    │    │    │    │
   P1   P2   P3   P4   P5   P6   P7
    └────┼────┼────┼────┼────┼────┘
         └────┴────┴────┘
         (cross-linked freely)

When to Use

• Small sites with fewer than 100 pages
• Portfolio sites
• Small business brochure sites
• Startups with limited content

Scaling Limits

---

4. Pyramid Architecture

Overview

The pyramid model mirrors traditional website hierarchies: a single homepage at the top, branching into categories, subcategories, and finally individual pages. Authority flows from top to bottom, concentrating at higher levels.

Structure Diagram

Level 0:              Homepage
                      /      \
Level 1:        Category A    Category B
                /    \          /    \
Level 2:    Sub A1   Sub A2  Sub B1  Sub B2
            / \      / \      / \     / \
Level 3:  P1  P2   P3  P4   P5  P6  P7  P8

Authority Flow Considerations

When to Use

• News and media sites
• Large blogs (500+ posts)
• Corporate sites with many divisions
• Government/educational sites

---

5. Mesh/Matrix Architecture

Overview

The mesh model allows free-form linking between any related pages, regardless of hierarchy. Every page can link to any other relevant page. This creates a dense web of connections, similar to Wikipedia's link structure.

Structure Diagram

    P1 ←──→ P2 ←──→ P3
    ↕  ╲    ↕    ╱  ↕
    P4 ←──→ P5 ←──→ P6
    ↕  ╱    ↕    ╲  ↕
    P7 ←──→ P8 ←──→ P9

Governance Rules

When to Use

• Knowledge bases and documentation sites
• Wikis and encyclopedias
• Research repositories
• FAQ/help center sites

---

Migration Between Models

Common Migration Paths

Migration Steps (General)

1. Audit current state: Map all existing internal links using a crawler 2. Design target architecture: Choose model, map pages to their new positions 3. Create a link change plan: Document every link addition, removal, and anchor text change 4. Implement in phases: Start with highest-priority cluster/silo, then expand 5. Preserve existing equity: Do not remove links that pass significant value without replacement 6. Monitor impact: Track rankings and traffic for 4-8 weeks after each phase 7. Iterate: Adjust the plan based on measured results

Migration Risk Mitigation

---

Measurement Framework

Key Metrics by Architecture Model

Monthly Monitoring Checklist

ROI Estimation

---

Hybrid Architecture Strategies

Most real-world sites combine elements from multiple models. Common hybrid patterns:

Hub-and-Spoke + Silo (Recommended for Medium-Large Sites)

Homepage
  ├── Category Silo A
  │     ├── Hub A1 (pillar) ←→ Cluster articles
  │     └── Hub A2 (pillar) ←→ Cluster articles
  ├── Category Silo B
  │     ├── Hub B1 (pillar) ←→ Cluster articles
  │     └── Hub B2 (pillar) ←→ Cluster articles
  └── Cross-category bridge links (A1 ↔ B2 where relevant)

• Silos provide category organization for navigation and URL structure
• Hubs within each silo build topical authority for specific keyword clusters
• Bridge links connect related content across silos where user intent overlaps

Implementation Priority Order

1. Fix structural issues first (orphan pages, broken links) 2. Implement primary architecture model 3. Add cross-linking strategy 4. Optimize anchor text 5. Monitor and iterate

This order ensures each phase builds on a solid foundation rather than optimizing details on a broken structure.

Internal Linking Optimizer — Worked Example

Referenced from SKILL.md.

---

Worked Example

User: "Find internal linking opportunities for our article about PostgreSQL index performance monitoring"

Output:

## Internal Linking Opportunities

**Page**: https://www.tigerdata.com/learn/how-to-monitor-and-optimize-postgresql-index-performance
**Current Internal Links**: 2
**Verified URL inventory**: 47 URLs from Tiger Den + sitemap

### Recommended Links to Add

| Section | Text to Link | Target Page | Anchor |
|---------|--------------|-------------|--------|
| Para 2 | "query performance" | https://www.tigerdata.com/learn/postgresql-query-optimization-guide | "PostgreSQL query optimization" |
| Para 5 | "database indexes" | https://www.tigerdata.com/learn/postgresql-performance-tuning-optimizing-database-indexes | "optimizing database indexes" |
| Section on monitoring | "continuous aggregates" | https://www.tigerdata.com/docs/use-timescale/continuous-aggregates | "continuous aggregates" |
| CTA section | "time-series data" | https://www.tigerdata.com/learn/what-is-a-time-series-database | "time-series database" |
| Conclusion | "Tiger Data cloud" | https://www.tigerdata.com/cloud | "managed PostgreSQL in the cloud" |

### Pages That Should Link TO This Article

| Source Page | Location | Anchor Text |
|-------------|----------|-------------|
| https://www.tigerdata.com/learn/postgresql-performance-tuning-optimizing-database-indexes | Index monitoring section | "monitor and optimize index performance" |
| https://www.tigerdata.com/blog/postgresql-tips-for-better-performance | Related reading | "PostgreSQL index monitoring best practices" |
| https://www.tigerdata.com/learn/postgresql-query-optimization-guide | Index section | "index performance monitoring techniques" |

### Priority Actions

1. Add 5 outbound internal links (listed above — all verified against Tiger Den + sitemap)
2. Request 3 inbound links from related pages
3. Verify all links resolve correctly before publishing

Internal Linking Optimizer — Output Templates

Detailed output templates for internal-linking-optimizer steps 6-9. Referenced from SKILL.md.

---

Step 6: Create Topic Cluster Link Strategy

## Topic Cluster Internal Linking

### Cluster: [Main Topic]

**Pillar Page**: [URL]
**Cluster Articles**: [X]

### Current Link Map

[Pillar Page] ├── [Cluster Article 1] ←→ [linked?] ├── [Cluster Article 2] ←→ [linked?] ├── [Cluster Article 3] ←→ [linked?] └── [Cluster Article 4] ←→ [linked?]

### Recommended Link Structure

[Pillar Page] ├── Links TO all cluster articles ✅ │ ├── [Cluster Article 1] │ ├── Link TO pillar ✅ │ └── Link TO related cluster articles │ ├── [Cluster Article 2] │ ├── Link TO pillar ✅ │ └── Link TO related cluster articles │ └── [etc.]

### Links to Add

| From Page | To Page | Anchor Text | Location |
|-----------|---------|-------------|----------|
| [URL 1] | [URL 2] | "[anchor]" | [paragraph/section] |
| [URL 2] | [URL 3] | "[anchor]" | [paragraph/section] |
| [Pillar] | [Cluster 1] | "[anchor]" | [section] |

---

Step 7: Find Contextual Link Opportunities

## Contextual Link Opportunities

### Link Opportunity Analysis

For each page, find relevant pages to link to based on:
- Topic relevance
- Keyword overlap
- User journey logic
- Authority distribution needs

### Opportunities Found

**Page: [URL 1]**
**Topic**: [topic]
**Current internal links**: [X]

| Opportunity | Target Page | Anchor Text | Why Link |
|-------------|-------------|-------------|----------|
| Paragraph 2 mentions "[topic]" | [URL] | "[topic phrase]" | Topic match |
| Section on "[subject]" | [URL] | "[anchor]" | Related guide |
| CTA at end | [URL] | "[anchor]" | User journey |

**Page: [URL 2]**
[Continue for each page...]

### Priority Link Additions

**High Impact Links** (add these first):

1. **From**: [Source URL]
   **To**: [Target URL]
   **Anchor**: "[anchor text]"
   **Why**: [reason - e.g., "Target page needs authority boost"]
   **Where to add**: [specific location in content]

2. **From**: [Source URL]
   **To**: [Target URL]
   [etc.]

---

Step 8: Optimize Navigation and Footer Links

## Site-Wide Link Optimization

### Current Navigation Analysis

**Main Navigation**:
- Links present: [list]
- Missing important pages: [list]
- Too many links: [Yes/No]

**Footer Navigation**:
- Links present: [list]
- SEO value: [assessment]

### Navigation Recommendations

| Element | Current | Recommended | Reason |
|---------|---------|-------------|--------|
| Main nav | [X] links | [Y] links | [reason] |
| Footer | [X] links | [Y] links | [reason] |
| Sidebar | [status] | [recommendation] | [reason] |
| Breadcrumbs | [status] | [recommendation] | [reason] |

### Pages to Add to Navigation

1. [Page] - Add to [location] because [reason]
2. [Page] - Add to [location] because [reason]

### Pages to Remove from Navigation

1. [Page] - Move to [footer/remove] because [reason]

---

Step 9: Generate Link Implementation Plan

# Internal Linking Optimization Plan

**Site**: [domain]
**Analysis Date**: [date]

## Executive Summary

- Total link opportunities found: [X]
- Orphan pages to fix: [X]
- Estimated traffic impact: [+X%]
- Priority actions: [X]

## Current State

| Metric | Current | Target | Gap |
|--------|---------|--------|-----|
| Avg links per page | [X] | [X] | [X] |
| Orphan pages | [X] | 0 | [X] |
| Over-optimized anchors | [X]% | <10% | [X]% |
| Topic cluster coverage | [X]% | 100% | [X]% |

## Priority Actions

### Phase 1: Critical Fixes (Week 1)

**Fix Orphan Pages**:
- [ ] [URL] - Add links from [X] pages
- [ ] [URL] - Add links from [X] pages

**High-Value Link Additions**:
- [ ] Link [Page A] to [Page B] with "[anchor]"
- [ ] Link [Page A] to [Page C] with "[anchor]"

### Phase 2: Topic Clusters (Week 2-3)

**Cluster 1: [Topic]**
- [ ] Ensure pillar links to all [X] cluster articles
- [ ] Add [X] cross-links between cluster articles

**Cluster 2: [Topic]**
- [ ] [Tasks]

### Phase 3: Optimization (Week 4+)

**Anchor Text Diversity**:
- [ ] Vary anchors for [Page] - currently [X]% exact match
- [ ] [Additional tasks]

**Navigation Updates**:
- [ ] Add [Page] to main navigation
- [ ] Update footer links

## Implementation Guide

### Adding Internal Links

Best practices:
1. Add links contextually within content
2. Use descriptive anchor text (not "click here")
3. Link to relevant, helpful pages
4. Aim for 3-10 internal links per 1,000 words
5. Vary anchor text for the same target

### Anchor Text Guidelines

| Type | Example | Usage |
|------|---------|-------|
| Exact match | "keyword research" | 10-20% |
| Partial match | "tips for keyword research" | 30-40% |
| Branded | "Brand's guide to..." | 10-20% |
| Natural | "this article", "learn more" | 20-30% |

## Tracking Success

Monitor these metrics weekly:
- [ ] Rankings for target keywords
- [ ] Traffic to previously orphan pages
- [ ] Crawl stats in search console
- [ ] Internal link distribution changes