internal-linking-optimizer

Original source / Raw SKILL.md

---
name: internal-linking-optimizer
version: "3.0.0"
description: 'This skill should be used when the user asks to "fix internal links", "improve site architecture", "link structure", "distribute page authority", "internal linking strategy", "orphan pages", "site architecture is messy", or "pages have no links pointing to them". Analyzes and optimizes internal link structure to improve site architecture, distribute page authority, and help search engines understand content relationships. Creates strategic internal linking plans. For a broader on-page audit, see on-page-seo-auditor. For external link analysis, see backlink-analyzer.'
license: Apache-2.0
compatibility: "Claude Code ≥1.0, skills.sh marketplace, ClawHub marketplace, Vercel Labs skills ecosystem. No system packages required. Optional: MCP network access for SEO tool integrations."
metadata:
  openclaw:
    requires:
      env: []
      bins: []
    primaryEnv: AHREFS_API_KEY
  author: aaron-he-zhu
  version: "3.0.0"
  geo-relevance: "low"
  tags:
    - seo
    - internal linking
    - site architecture
    - link structure
    - page authority
    - link equity
    - content silos
    - navigation optimization
    - internal-links
    - site-architecture
    - link-equity
    - orphan-pages
    - topical-authority
    - hub-and-spoke
    - pillar-cluster
    - anchor-text
    - crawl-depth
  triggers:
    - "fix internal links"
    - "improve site architecture"
    - "link structure"
    - "distribute page authority"
    - "internal linking strategy"
    - "site navigation"
    - "link equity"
    - "orphan pages"
    - "site architecture is messy"
    - "pages have no links pointing to them"
---

# Internal Linking Optimizer


> **[SEO & GEO Skills Library](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · Install all: `npx skills add aaron-he-zhu/seo-geo-claude-skills`

<details>
<summary>Browse all 20 skills</summary>

**Research** · [keyword-research](../../research/keyword-research/) · [competitor-analysis](../../research/competitor-analysis/) · [serp-analysis](../../research/serp-analysis/) · [content-gap-analysis](../../research/content-gap-analysis/)

**Build** · [seo-content-writer](../../build/seo-content-writer/) · [geo-content-optimizer](../../build/geo-content-optimizer/) · [meta-tags-optimizer](../../build/meta-tags-optimizer/) · [schema-markup-generator](../../build/schema-markup-generator/)

**Optimize** · [on-page-seo-auditor](../on-page-seo-auditor/) · [technical-seo-checker](../technical-seo-checker/) · **internal-linking-optimizer** · [content-refresher](../content-refresher/)

**Monitor** · [rank-tracker](../../monitor/rank-tracker/) · [backlink-analyzer](../../monitor/backlink-analyzer/) · [performance-reporter](../../monitor/performance-reporter/) · [alert-manager](../../monitor/alert-manager/)

**Cross-cutting** · [content-quality-auditor](../../cross-cutting/content-quality-auditor/) · [domain-authority-auditor](../../cross-cutting/domain-authority-auditor/) · [entity-optimizer](../../cross-cutting/entity-optimizer/) · [memory-management](../../cross-cutting/memory-management/)

</details>

This skill analyzes your site's internal link structure and provides recommendations to improve SEO through strategic internal linking. It 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

## What This Skill Does

1. **Link Structure Analysis**: Maps current internal linking patterns
2. **Authority Flow Mapping**: Shows how PageRank flows through site
3. **Orphan Page Detection**: Finds pages with no internal links
4. **Anchor Text Optimization**: Improves anchor text diversity
5. **Topic Cluster Linking**: Creates pillar-cluster link strategies
6. **Link Opportunity Finding**: Identifies where to add links
7. **Navigation Optimization**: Improves site-wide link elements

## How to Use

### Analyze Current Structure

```
Analyze internal linking structure for [domain/sitemap]
```

```
Find internal linking opportunities for [URL]
```

### Create Linking Strategy

```
Create internal linking plan for topic cluster about [topic]
```

```
Suggest internal links for this new article: [content/URL]
```

### Fix Issues

```
Find orphan pages on [domain]
```

```
Optimize anchor text across the site
```

## Data Sources

> See [CONNECTORS.md](../../CONNECTORS.md) for tool category placeholders.

**With ~~web crawler + ~~analytics connected:**
Claude can automatically perform a full site crawl via ~~web crawler to map the complete link graph, fetch page performance metrics from ~~analytics to identify high-value pages, and analyze link flow throughout the site. This enables data-driven internal linking strategies.

**With manual data only:**
Ask the user to provide:
1. Sitemap URL or list of important pages
2. Key page URLs that need more internal links
3. Content categories or topic clusters
4. Any existing link structure documentation

Proceed with the analysis using provided data. Note in the output which findings are from automated crawl vs. manual review.

## Instructions

When a user requests internal linking optimization:

1. **Analyze Current Internal Link Structure**

   ```markdown
   ## 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
   ```

2. **Identify Orphan Pages**

   ```markdown
   ## Orphan Page Analysis
   
   ### Definition
   Orphan pages have no internal links pointing to them, making them 
   hard for users and search engines to discover.
   
   ### 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]
   2. [URL] - Add links from: [relevant pages]
   
   **Medium Priority Orphans** (potentially valuable):
   1. [URL] - Add to category/tag page
   2. [URL] - Link from related content
   
   **Low Priority Orphans** (consider removing):
   1. [URL] - Redirect to [better page]
   2. [URL] - Delete or noindex
   ```

3. **Analyze Anchor Text Distribution**

   > **CORE-EEAT alignment**: Internal linking quality maps to R08 (Internal Link Graph) in the CORE-EEAT benchmark -- use descriptive anchors, ensure links support topical authority. See [content-quality-auditor](../../cross-cutting/content-quality-auditor/) for full audit.

   ```markdown
   ## Anchor Text Analysis
   
   ### Current Anchor Text Patterns
   
   **Most Used Anchors**:
   
   | 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 Distribution by Page
   
   **Page: [Important URL]**
   
   | Anchor Text | Source Page | Status |
   |-------------|-------------|--------|
   | "[anchor 1]" | [source URL] | ✅/⚠️/❌ |
   | "[anchor 2]" | [source URL] | ✅/⚠️/❌ |
   
   **Issues Found**:
   - Over-optimized anchors: [X] instances
   - Generic anchors: [X] instances
   - Same anchor to multiple pages: [X] instances
   
   ### Anchor Text Recommendations
   
   **For Page: [URL]**
   
   Current: "[current anchor]" used [X] times
   
   Recommended variety:
   - "[variation 1]" - Use from [page type]
   - "[variation 2]" - Use from [page type]
   - "[variation 3]" - Use from [page type]
   
   **Anchor Score**: [X]/10
   ```

4. **Create Topic Cluster Link Strategy** — Map current pillar/cluster links, recommend link structure, list specific links to add

   > **Reference**: See [references/linking-templates.md](./references/linking-templates.md) for the topic cluster link strategy template (Step 4).

5. **Find Contextual Link Opportunities** — Analyze each page for topic-relevant link opportunities, prioritize high-impact additions

   > **Reference**: See [references/linking-templates.md](./references/linking-templates.md) for the contextual link opportunities template (Step 5).

6. **Optimize Navigation and Footer Links** — Analyze main/footer/sidebar/breadcrumb navigation, recommend pages to add or remove

   > **Reference**: See [references/linking-templates.md](./references/linking-templates.md) for the navigation optimization template (Step 6).

7. **Generate Link Implementation Plan** — Executive summary, current state metrics, phased priority actions (weeks 1-4+), implementation guide, tracking plan

   > **Reference**: See [references/linking-templates.md](./references/linking-templates.md) for the full implementation plan template (Step 7).

## Validation Checkpoints

### Input Validation
- [ ] Site structure or sitemap provided (URL or file)
- [ ] Target pages or topic clusters clearly defined
- [ ] If optimizing specific page, page URL or content provided

### 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 (~~web crawler data, ~~analytics, user-provided, or manual analysis)

## Example

> **Reference**: See [references/linking-example.md](./references/linking-example.md) for a full worked example (email marketing best practices 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

## Reference Materials

- [Link Architecture Patterns](./references/link-architecture-patterns.md) — Architecture models (hub-and-spoke, silo, flat, pyramid, mesh), anchor text diversity framework, link equity flow model, and internal link audit checklist
- [Linking Templates](./references/linking-templates.md) — Detailed output templates for steps 6-7 (navigation optimization, implementation plan)
- [Linking Example](./references/linking-example.md) — Full worked example for internal linking opportunities

## Related Skills

- [content-gap-analysis](../../research/content-gap-analysis/) — Find content to link to
- [seo-content-writer](../../build/seo-content-writer/) — Create linkable content
- [on-page-seo-auditor](../on-page-seo-auditor/) — Audit overall on-page SEO
- [technical-seo-checker](../technical-seo-checker/) — Check crawlability
- [content-quality-auditor](../../cross-cutting/content-quality-auditor/) — Full 80-item CORE-EEAT audit
- [schema-markup-generator](../../build/schema-markup-generator/) — Breadcrumb and navigation schema


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/linking-templates.md

```markdown
# Internal Linking Optimizer — Output Templates

Detailed output templates for internal-linking-optimizer steps 4-7. Referenced from [SKILL.md](../SKILL.md).

---

## Step 4: Create Topic Cluster Link Strategy

```markdown
## 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 5: Find Contextual Link Opportunities

```markdown
## 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 6: Optimize Navigation and Footer Links

```markdown
## 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 7: Generate Link Implementation Plan

```markdown
# 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
```

```

### references/linking-example.md

```markdown
# Internal Linking Optimizer — Worked Example

Referenced from [SKILL.md](../SKILL.md).

---

## Worked Example

**User**: "Find internal linking opportunities for my blog post about 'email marketing best practices'"

**Output**:

```markdown
## Internal Linking Opportunities

**Page**: /blog/email-marketing-best-practices/
**Current Internal Links**: 2

### Recommended Links to Add

| Section | Text to Link | Target Page | Anchor |
|---------|--------------|-------------|--------|
| Para 2 | "building your email list" | /blog/grow-email-list/ | "building your email list" |
| Para 5 | "subject lines" | /blog/email-subject-lines/ | "write compelling subject lines" |
| Section on segmentation | "audience segments" | /blog/email-segmentation-guide/ | "segment your audience" |
| CTA section | "marketing automation" | /services/email-automation/ | "email automation services" |
| Conclusion | "email marketing tools" | /blog/best-email-tools/ | "top email marketing tools" |

### Pages That Should Link TO This Article

| Source Page | Location | Anchor Text |
|-------------|----------|-------------|
| /blog/digital-marketing-guide/ | Email section | "email marketing best practices" |
| /services/marketing-services/ | Related content | "email marketing strategies" |
| /blog/lead-generation-tips/ | Email mention | "email marketing techniques" |

### Priority Actions

1. Add 5 outbound internal links (listed above)
2. Request 3 inbound links from related pages
3. Add to "Marketing" category page
```

```

### references/link-architecture-patterns.md

```markdown
# 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

| Link Type | Direction | Anchor Text Strategy |
|-----------|-----------|---------------------|
| Pillar → Cluster | Pillar links to each cluster | Descriptive: "learn about [subtopic]" |
| Cluster → Pillar | Every cluster links back to pillar | Partial match: "our complete [topic] guide" |
| Cluster ↔ Cluster | Between related clusters in same hub | Natural: "as we covered in [related article]" |
| Hub ↔ Hub (bridge) | Between related pillar pages | Branded/natural: "see also our [topic] resource" |

#### 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

| Metric | Target | Tool |
|--------|--------|------|
| Pillar page rankings for head terms | Top 10 | Rank tracker |
| Cluster article rankings for long-tail | Top 20 | Rank tracker |
| Internal links per cluster article | 3-5 minimum | Crawl report |
| Click depth from homepage to cluster | ≤3 clicks | Crawl report |
| Organic traffic to hub pages | Month-over-month growth | Analytics |

---

### 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

| Link Type | Direction | Allowed? |
|-----------|-----------|----------|
| Parent → Child | Downward within silo | Always |
| Child → Parent | Upward within silo | Always |
| Sibling ↔ Sibling | Horizontal within same parent | Yes |
| Cross-silo | Between different silos | Strict: No. Modified: Sparingly |
| All pages → Homepage | Upward to root | Yes (via navigation) |

#### 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)
```

#### Implementation Steps

1. **Link all key pages from the homepage** (directly or via a comprehensive sitemap page)
2. **Keep URL structure shallow**: /category/page, not /category/subcategory/year/page
3. **Cross-link freely** between related pages at the same level
4. **Use comprehensive navigation** menus, footer links, or HTML sitemaps
5. **Limit total pages** to keep the architecture manageable

#### When to Use
- Small sites with fewer than 100 pages
- Portfolio sites
- Small business brochure sites
- Startups with limited content

#### Scaling Limits

| Site Size | Flat Architecture Feasibility |
|-----------|------------------------------|
| <50 pages | Ideal |
| 50-100 pages | Manageable with good navigation |
| 100-500 pages | Difficult; consider hub-and-spoke |
| 500+ pages | Not recommended; switch to hierarchical model |

---

### 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
```

#### Implementation Steps

1. **Design a clear hierarchy** with 3-4 levels maximum
2. **Homepage links to all top-level categories** prominently
3. **Category pages link to all subcategories** within them
4. **Subcategory pages link to all child pages**
5. **Implement breadcrumbs** to support the hierarchy
6. **Add "related content" cross-links** at the page level to offset authority concentration

#### Authority Flow Considerations

| Level | Typical Authority | Action to Improve |
|-------|-------------------|-------------------|
| Homepage | Highest | Ensure links to priority categories are prominent |
| Categories | High | Link from blog content, not just navigation |
| Subcategories | Medium | Add contextual links from other sections |
| Individual pages | Lowest | Cross-link, feature in "popular posts" widgets |

#### 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
```

#### Implementation Steps

1. **Set linking rules** to prevent chaos: link only when topically relevant
2. **Use contextual anchors** that describe the destination page
3. **Set a link budget** per page (5-15 contextual links per 1,000 words)
4. **Review link density regularly** to prune irrelevant connections
5. **Maintain a link map** (spreadsheet or tool) to track the network

#### Governance Rules

| Rule | Purpose |
|------|---------|
| Every link must have topical relevance | Prevents link dilution |
| Maximum 15 contextual links per 1,000 words | Prevents link farms |
| Review links quarterly | Prunes outdated connections |
| Use descriptive anchor text only | Maintains semantic value |
| No reciprocal link trading between unrelated pages | Prevents manipulation patterns |

#### When to Use
- Knowledge bases and documentation sites
- Wikis and encyclopedias
- Research repositories
- FAQ/help center sites

---

## Migration Between Models

### Common Migration Paths

| From | To | Reason | Difficulty |
|------|----|--------|-----------|
| Flat → Hub-and-Spoke | Site grew beyond 100 pages | Medium |
| Silo → Hub-and-Spoke | Silos too rigid, need cross-topic links | Medium |
| Pyramid → Hub-and-Spoke | Want to build topical clusters | High |
| No structure → Any model | Starting from disorganized state | High |
| Hub-and-Spoke → Hybrid | Need both clusters and strict categories | Medium |

### 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

| Risk | Mitigation |
|------|-----------|
| Temporary ranking drops | Migrate one section at a time, not all at once |
| Broken internal links | Run crawl after each phase to verify |
| Lost link equity | Ensure no orphan pages created during migration |
| Anchor text disruption | Change anchors gradually, not all at once |

---

## Measurement Framework

### Key Metrics by Architecture Model

| Metric | Hub-and-Spoke | Silo | Flat | Pyramid | Mesh |
|--------|---------------|------|------|---------|------|
| Avg click depth | ≤3 | ≤4 | ≤2 | ≤4 | ≤3 |
| Orphan pages | 0 | 0 | 0 | 0 | 0 |
| Avg internal links per page | 5-10 | 3-7 | 8-15 | 3-5 | 8-15 |
| Cross-section links | Many | Few | N/A | Some | Many |
| Authority concentration | Distributed to hubs | Concentrated in silo tops | Even | Top-heavy | Even |

### Monthly Monitoring Checklist

| Check | Tool | Action if Failing |
|-------|------|-------------------|
| Orphan pages count | Crawl report | Add internal links immediately |
| Average click depth | Crawl report | Add shortcuts to deep pages |
| Crawl depth distribution | Crawl report | Flatten deep branches |
| Internal link count per page | Crawl report | Add links to under-linked pages |
| Anchor text diversity | Manual audit | Vary anchors for over-optimized pages |
| Broken internal links | Crawl report | Fix or remove broken links |
| New content linked within 48 hours | Editorial process | Add to related pages upon publishing |

### ROI Estimation

| Architecture Change | Typical Impact | Timeline to See Results |
|--------------------|---------------|----------------------|
| Fix orphan pages | +15-30% traffic to those pages | 2-4 weeks |
| Build first topic cluster | +10-25% traffic to cluster pages | 4-8 weeks |
| Reduce click depth by 1 level | +5-15% crawl efficiency | 2-6 weeks |
| Anchor text optimization | +5-10% ranking improvement for target terms | 4-12 weeks |
| Full architecture migration | +20-50% overall organic traffic | 3-6 months |

---

## 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.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "aaron-he-zhu",
  "slug": "internal-linking-optimizer",
  "displayName": "Internal Linking Optimizer",
  "latest": {
    "version": "3.0.0",
    "publishedAt": 1772640534258,
    "commit": "https://github.com/openclaw/skills/commit/01637adac867ad966ffebd94c46802bf976e36bd"
  },
  "history": []
}

```