feat: enhance SurfSense with new skills, blog section, and improve SEO metadata

- Added multiple new skills to skills-lock.json from the repository `aaron-he-zhu/seo-geo-claude-skills`. - Introduced `fuzzy-search` dependency in package.json for improved search functionality. - Updated pnpm-lock.yaml to include the new `fuzzy-search` package. - Enhanced SEO metadata across various pages, including canonical links and descriptions for better search visibility. - Improved layout and structure of several components, including the homepage and changelog, to enhance user experience.
2026-04-25 00:36:31 +02:00 · 2026-04-11 23:38:12 -07:00 · 2026-04-11 23:38:12 -07:00 · 7ea840dbb2
commit 7ea840dbb2
parent 61b3f0d7e3
120 changed files with 25729 additions and 352 deletions
--- a/.cursor/skills/internal-linking-optimizer/SKILL.md
+++ b/.cursor/skills/internal-linking-optimizer/SKILL.md
@ -0,0 +1,351 @@
+---
+name: internal-linking-optimizer
+description: 'Optimize internal links: site architecture, authority distribution, orphan pages, crawl depth analysis. 内链优化/站内架构'
+version: "6.0.0"
+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."
+homepage: "https://github.com/aaron-he-zhu/seo-geo-claude-skills"
+when_to_use: "Use when improving internal link structure, anchor text distribution, orphan pages, or site architecture."
+argument-hint: "<URL or sitemap>"
+metadata:
+  author: aaron-he-zhu
+  version: "6.0.0"
+  geo-relevance: "low"
+  tags:
+    - seo
+    - internal-linking
+    - site-architecture
+    - link-equity
+    - orphan-pages
+    - topical-authority
+    - crawl-depth
+    - 内链优化
+    - 内部リンク
+    - 내부링크
+    - enlaces-internos
+  triggers:
+    # EN-formal
+    - "fix internal links"
+    - "improve site architecture"
+    - "link structure"
+    - "distribute page authority"
+    - "internal linking strategy"
+    - "site navigation"
+    - "link equity"
+    # EN-casual
+    - "orphan pages"
+    - "site architecture is messy"
+    - "pages have no links pointing to them"
+    - "pages have no links"
+    - "site structure is messy"
+    # EN-question
+    - "how to improve internal linking"
+    - "how to fix orphan pages"
+    # ZH-pro
+    - "内链优化"
+    - "站内链接"
+    - "网站架构"
+    - "权重传递"
+    - "锚文本优化"
+    # ZH-casual
+    - "内链怎么做"
+    - "孤立页面"
+    - "网站结构乱"
+    # JA
+    - "内部リンク最適化"
+    - "サイト構造"
+    # KO
+    - "내부 링크 최적화"
+    - "사이트 구조"
+    # ES
+    - "enlaces internos"
+    - "arquitectura del sitio"
+    # PT
+    - "links internos"
+    # Misspellings
+    - "internal linkng"
+---
+
+# Internal Linking Optimizer
+
+
+> **[SEO & GEO Skills Library](https://github.com/aaron-he-zhu/seo-geo-claude-skills)** · 20 skills for SEO + GEO · [ClawHub](https://clawhub.ai/u/aaron-he-zhu) · [skills.sh](https://skills.sh/aaron-he-zhu/seo-geo-claude-skills)
+> **System Mode**: This optimization skill follows the shared [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md) and [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md).
+
+
+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.
+
+**System role**: Optimization layer skill. It turns weak pages, structures, and technical issues into prioritized repair work.
+
+## When This Must Trigger
+
+Use this when the conversation involves any of these situations — even if the user does not use SEO terminology:
+
+Use this whenever the task needs a diagnosis or repair plan that should feed directly into remediation work, not just a one-time opinion.
+
+- 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
+
+## Quick Start
+
+Start with one of these prompts. Finish with a short handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md).
+
+### 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
+```
+
+## Skill Contract
+
+**Expected output**: a scored diagnosis, prioritized repair plan, and a short handoff summary ready for `memory/audits/`.
+
+- **Reads**: the current page or site state, symptoms, prior audits, and current priorities from [CLAUDE.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CLAUDE.md) and the shared [State Model](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/state-model.md) when available.
+- **Writes**: a user-facing audit or optimization plan plus a reusable summary that can be stored under `memory/audits/`.
+- **Promotes**: blocking defects, repeated weaknesses, and fix priorities to `memory/open-loops.md` and `memory/decisions.md`.
+- **Next handoff**: use the `Next Best Skill` below when the repair path is clear.
+
+## Data Sources
+
+> **Note:** All integrations are optional. This skill works without any API keys — users provide data manually when no tools are connected.
+
+> See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/content-quality-auditor/SKILL.md) 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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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
+
+
+### Save Results
+
+After delivering audit or optimization findings to the user, ask:
+
+> "Save these results for future sessions?"
+
+If yes, write a dated summary to `memory/audits/internal-linking-optimizer/YYYY-MM-DD-<topic>.md` containing:
+- One-line verdict or headline finding
+- Top 3-5 actionable items
+- Open loops or blockers
+- Source data references
+
+If any veto-level issue was found (CORE-EEAT T04, C01, R10 or CITE T03, T05, T09), also append a one-liner to `memory/hot-cache.md` without asking.
+
+## Reference Materials
+
+- [Link Architecture Patterns](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-templates.md) — Detailed output templates for steps 6-7 (navigation optimization, implementation plan)
+- [Linking Example](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/references/linking-example.md) — Full worked example for internal linking opportunities
+
+## Next Best Skill
+
+- **Primary**: [on-page-seo-auditor](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/on-page-seo-auditor/SKILL.md) — verify that revised internal links support the page-level goals.
--- a/.cursor/skills/internal-linking-optimizer/references/link-architecture-patterns.md
+++ b/.cursor/skills/internal-linking-optimizer/references/link-architecture-patterns.md
@ -0,0 +1,362 @@
+# 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.
--- a/.cursor/skills/internal-linking-optimizer/references/linking-example.md
+++ b/.cursor/skills/internal-linking-optimizer/references/linking-example.md
@ -0,0 +1,42 @@
+# Internal Linking Optimizer — Worked Example
+
+Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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
+```
--- a/.cursor/skills/internal-linking-optimizer/references/linking-templates.md
+++ b/.cursor/skills/internal-linking-optimizer/references/linking-templates.md
@ -0,0 +1,219 @@
+# Internal Linking Optimizer — Output Templates
+
+Detailed output templates for internal-linking-optimizer steps 4-7. Referenced from [SKILL.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/optimize/internal-linking-optimizer/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
+```