Internal Linking Optimizer

Internal Linking Optimizer

Analyzes internal link structure, authority flow, orphan pages, anchor text, and topic clusters, then delivers a prioritized linking plan with source/target/anchor recommendations.

Quick Start

Start with one of these prompts, then finish with the standard handoff summary from Skill Contract.

Analyze internal linking structure for [domain/sitemap]
Find internal linking opportunities for [URL]
Create internal linking plan for topic cluster about [topic]
Suggest internal links for this new article: [content/URL]
Find orphan pages on [domain]
Optimize anchor text across the site

Skill Contract

Expected output: a scored diagnosis, prioritized repair plan, and a short handoff summary ready for memory/audits/.

• Reads: sitemap or page list, key page URLs, content categories, and article/URL to link from.
• Writes: a user-facing linking plan plus a reusable summary that can be stored under memory/audits/.
• Promotes: blocking defects, repeated weaknesses, fix priorities, and pending decisions to memory/open-loops.md.
• Done when: orphan pages are listed with a disposition; anchor distribution is checked against thresholds; a prioritized source/target/anchor plan and handoff summary are produced.
• Primary next skill: use the Next Best Skill below when the repair path is clear.

Handoff Summary

Emit the standard shape from skill-contract.md §Handoff Summary Format.

Data Sources

Uses ~~web crawler and ~~analytics when connected; otherwise asks user for sitemap, key page URLs, and content categories. See CONNECTORS.md and SECURITY.md §Scraping Boundaries.

Zero-dependency local helper (no tool needed): python3 scripts/connectors/crawl.py <url> | python3 scripts/connectors/linkgraph.py - computes orphans, click-depth, and internal PageRank from a live crawl. See scripts/connectors/README.md.

Instructions

Label every metric Measured (tool/export), User-provided, or Estimated (model inference); never present an estimate as measured; if a required metric is unavailable, mark it N/A — do not invent it.

When a user requests internal linking optimization:

1. Analyze Current Structure — Capture domain, pages analyzed, total internal links, average links/page, link distribution, top linked pages, under-linked important pages, and a structure score /100 (start at 100; −10 per orphan page, −5 per important page deeper than 3 clicks, −5 per page with 0 inbound contextual links, −10 if avg links/page is outside the architecture model's target range in Link Architecture Patterns; floor 0). Flag crawl-depth and authority-flow problems. 2. Identify Orphan Pages — List pages with no inbound internal links. Prioritize high-value orphans with traffic/rankings, medium-potential pages that need category/tag links, and low-value pages to delete, noindex, or redirect. 3. Analyze Anchor Text Distribution — Check current anchor patterns, distribution by page, over-optimization, generic anchors, and CORE-EEAT R08 alignment. Anchor Score /10 and thresholds are defined in the Step 3 template.

Reference: references/linking-templates.md contains the Step 3 output template.

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

Reference: references/linking-templates.md contains the Step 4 template.

5. Find Contextual Link Opportunities — For each page, identify topic-relevant source/target/anchor opportunities and prioritize high-impact additions.

Reference: references/linking-templates.md contains the Step 5 template.

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

Reference: references/linking-templates.md contains the Step 6 template.

7. Generate Implementation Plan — Include executive summary, current-state metrics, phased priority actions, implementation guide, and tracking plan.

Reference: references/linking-templates.md contains the Step 7 template.

Decision Gates

Stop and ask the user when:

• A high-value orphan must be deleted, noindexed, or redirected and its traffic/ranking value is unknown — state what you see and ask: (1) keep and add links, (2) noindex, (3) 301-redirect to the nearest relevant page.

Continue silently (never stop for):

• Which architecture model to apply — infer it from site type and page count using Link Architecture Patterns, state the choice, and proceed.
• No crawler/analytics data — work from the provided sitemap or page list, label inferred metrics Estimated, and proceed.
• A low-value orphan with no traffic — recommend the default disposition (noindex or redirect) without stopping.

Example

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

Output: 5 high-value links with source paragraph, destination URL, recommended anchor text, and priority. Example targets might include list-building, subject-line, segmentation, automation, and tools pages.

Reference: See references/linking-example.md for the full worked example.

Tips for Success

• Prioritize relevance and user navigation over link volume.
• Use descriptive, varied anchors; avoid exact-match repetition.
• Link important pages from hubs, navigation, or strong contextual sources.
• Audit regularly as content grows.

Save Results

Ask to save results; if yes, write a dated summary to memory/audits/internal-linking-optimizer/YYYY-MM-DD-<topic>.md. Hand off veto-level risks to the auditor gate before any hot-cache marker.

Reference Materials

• Link Architecture Patterns — Architecture models, selection thresholds, migration safeguards, and measurement targets
• Linking Templates — Detailed output templates for steps 3-7
• Linking Example — Full worked example for internal linking opportunities

Next Best Skill

Primary: on-page-seo-auditor — verify that revised internal links support page-level goals.

Link Architecture Patterns

Architecture models, selection thresholds, migration safeguards, and measurement targets for internal linking optimization.

Model Selector

Link Rules by Model

Migration Between Models

Migration safety checklist

1. Audit current state: map existing internal links, orphan pages, click depth, and top linked pages. 2. Design target architecture: assign every important page to its new position. 3. Create a link-change plan: document each link to add, keep, move, or remove. 4. Implement in phases: start with highest-priority cluster/silo and avoid sitewide flips. 5. Preserve existing equity: do not remove valuable links without replacement. 6. Monitor rankings, crawl stats, traffic, and indexation for 4-8 weeks per phase. 7. Iterate only after measured impact is clear.

Monthly Monitoring

Hybrid: Hub-and-Spoke + Silo

Recommended for medium-large sites that need both taxonomy clarity and topical authority.

Homepage
  +-- Category Silo A
  |     +-- Hub A1 (pillar) <-> Cluster articles
  |     +-- Hub A2 (pillar) <-> Cluster articles
  +-- Category Silo B
  |     +-- Hub B1 (pillar) <-> Cluster articles
  +-- Cross-category bridge links only where user intent overlaps

Implementation priority:

1. Fix structural defects first: orphan pages, broken links, and excessive crawl depth. 2. Choose the primary architecture model. 3. Add cluster/silo cross-links where relevance is clear. 4. Optimize anchor text after structure is stable. 5. Monitor, then iterate.

Internal Linking Optimizer — Worked Example

Referenced from SKILL.md.

---

Worked Example

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

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

Internal Linking Optimizer Output Templates

Compact templates for internal-linking-optimizer steps 3-7. Keep thresholds intact when slimming: orphan pages target 0, over-optimized anchors target <10%, and exact-match anchors should stay at 10-20%.

Step 3: Anchor Text Analysis

## Anchor Text Analysis

CORE-EEAT alignment: R08 Internal Link Graph.

| Check | Finding | Risk | Action |
|-------|---------|------|--------|
| Most-used anchors | [anchor + count] | [generic/over-optimized/unclear] | [rewrite or diversify] |
| Target-page distribution | [URL + anchor mix] | [cannibalization or repetition] | [recommended variation set] |
| Generic anchors | [X instances] | Poor context | Replace with descriptive anchors |
| Same anchor to multiple pages | [anchor + targets] | Ambiguous relevance | Assign one primary target |

### Recommended Variations for [URL]
| Anchor type | Usage target | Examples |
|-------------|--------------|----------|
| Exact match | 10-20% | "[primary keyword]" |
| Partial match | 30-40% | "[keyword + modifier]" |
| Branded | 10-20% | "[Brand]'s guide to..." |
| Natural | 20-30% | "this checklist", "the full guide" |

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

Step 4: Topic Cluster Link Strategy

## Topic Cluster Internal Linking

**Cluster**: [Main topic]
**Pillar page**: [URL]
**Cluster articles**: [count]

### Required Link Pattern
| Link path | Requirement | Status |
|-----------|-------------|--------|
| Pillar -> cluster | Pillar links to every indexable cluster article | [pass/fail] |
| Cluster -> pillar | Every cluster article links back to pillar | [pass/fail] |
| Cluster -> cluster | Related articles cross-link where context helps users | [pass/fail] |

### Links to Add
| From page | To page | Anchor text | Location | Priority |
|-----------|---------|-------------|----------|----------|
| [URL] | [URL] | "[anchor]" | [section/paragraph] | [High/Med/Low] |

Step 5: Contextual Link Opportunities

## Contextual Link Opportunities

**Page**: [URL]
**Topic**: [topic]
**Current internal links**: [count]

| Source context | Target page | Anchor text | Reason | Priority |
|----------------|-------------|-------------|--------|----------|
| Paragraph mentions "[topic]" | [URL] | "[topic phrase]" | Topic match | [High/Med/Low] |
| Section covers "[subject]" | [URL] | "[anchor]" | Supports next step | [High/Med/Low] |

### Priority Addition
**From**: [source URL]
**To**: [target URL]
**Anchor**: "[anchor text]"
**Where**: [specific sentence/section]
**Why now**: [ranking, orphan fix, crawl depth, conversion path]

Step 6: Navigation and Footer Optimization

## Site-Wide Link Optimization

| Element | Current | Recommended | Reason |
|---------|---------|-------------|--------|
| Main nav | [links/status] | [change] | [priority page/user path] |
| Footer | [links/status] | [change] | [support/commercial path] |
| Sidebar | [status] | [change] | [context] |
| Breadcrumbs | [status] | [change] | [crawl path/user clarity] |

### Add, Demote, Remove
| Page | Action | Location | Reason |
|------|--------|----------|--------|
| [URL] | [add/demote/remove] | [nav/footer/sidebar] | [reason] |

Step 7: Implementation Plan

# Internal Linking Optimization Plan

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

## Summary
| 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]% |

## Phased Work
| Phase | Timing | Required actions |
|-------|--------|------------------|
| Critical fixes | Week 1 | Fix orphan pages; add high-value contextual links from authority pages. |
| Topic clusters | Weeks 2-3 | Ensure pillar -> cluster, cluster -> pillar, and useful cluster cross-links. |
| Optimization | Week 4+ | Diversify anchors, adjust nav/footer, and rebalance under-linked priority pages. |

## Tracking
- [ ] Rankings for target keywords
- [ ] Traffic to previously orphan pages
- [ ] Crawl stats in Search Console
- [ ] Internal link distribution changes
- [ ] Over-optimized anchors below 10%