opencode-skills-collection 4.0.63 → 4.0.65

package/bundled-skills/seo-aeo-internal-linking/SKILL.md

@@ -1,90 +1,251 @@
 ---
 name: seo-aeo-internal-linking
-description: "Maps internal link opportunities between pages with anchor text, placement instructions, orphan page detection, and cannibalization checks. Activate when the user wants to build an internal linking strategy or find link opportunities."
+description: "Maps internal link opportunities between pages with relevant anchor text, placement instructions, orphan-page detection, and cannibalisation checks."
 risk: safe
 source: community
 date_added: "2026-04-01"
 ---
 
-# SEO-AEO Internal Linking
+# Internal Linking Skill
 
-## Overview
+## Description
+Activate this skill when the user wants to build, audit, or optimise
+the internal link structure across a set of pages or a full site.
+Trigger phrases include: "internal linking strategy", "find internal
+link opportunities", "link these pages together", "internal link map",
+"suggest anchor text", "fix orphan pages", "internal links for
+[page or topic]", "link equity distribution".
 
-Analyses a set of pages and produces a prioritised list of internal link opportunities with exact anchor text, a context sentence showing where each link should appear, orphan page detection, anchor text cannibalization warnings, and a link equity map showing how authority flows across the content.
+---
+
+## Input Format
+```json
+{
+  "pages": [
+    {
+      "title": "string — page or post title",
+      "url": "string — URL if published, leave blank if not yet live",
+      "primary_keyword": "string — the keyword this page targets",
+      "page_type": "pillar | cluster-article | landing-page |
+                    blog-post | product-page",
+      "content_summary": "string — 1-2 sentences describing the page"
+    }
+  ],
+  "focus_page": "string — title of the page you most want to
+                  boost with incoming links",
+  "cluster_context": "string — optional, paste content cluster
+                       output to inform link map",
+  "product_pages": ["string — product, signup, pricing, or demo pages that should receive relevant CTAs"],
+  "audit_findings": "string — optional orphan, cannibalization, or priority findings"
+}
+```
+
+For a foundational content system, ensure every article has a contextual path to a relevant product, signup, pricing, demo, or next-step page. Do not add the same CTA or exact-match anchor mechanically to every article; match the destination to the reader’s intent.
+
+---
+
+## Link Type Definitions
+
+This skill recognises four distinct link types.
+Every suggestion must be labelled with one:
+
+| Link Type               | Direction                          | SEO Purpose                                 |
+|-------------------------|------------------------------------|---------------------------------------------|
+| Pillar → Cluster        | Pillar page links to cluster post  | Distributes authority downward              |
+| Cluster → Pillar        | Cluster post links back to pillar  | Consolidates authority upward — highest priority |
+| Cluster → Cluster       | Cluster post links to related post | Builds semantic depth across the topic      |
+| Contextual Boost        | Any page → focus page              | Concentrates link equity on target page     |
+
+**Rule:** Every cluster article must have at least one
+Cluster → Pillar link. No exceptions.
+
+---
+
+## Anchor Text Rules
+
+Anchor text is critical. Follow these rules on every suggestion:
+
+| Rule                                     | Limit                              |
+|------------------------------------------|------------------------------------|
+| Exact match anchor (keyword as-is)       | Max 1 per target page across site  |
+| Partial match anchor (keyword + words)   | Max 2 per target page across site  |
+| Branded anchor (site or product name)    | Unlimited                          |
+| Generic anchor ("click here", "read more")| Never use — flag as error          |
+| Naked URL as anchor                      | Avoid unless no alternative        |
+
+If the skill detects the same exact-match anchor being used
+more than once for the same target page, flag it as a
+**Cannibalization Risk** in the output.
+
+---
+
+## Output Structure
+
+The skill must always produce output in this exact format:
+```markdown
+# Internal Linking Report
+
+## Summary
+
+| Metric                          | Value      |
+|---------------------------------|------------|
+| Total Pages Analysed            | [n]        |
+| Total Link Opportunities Found  | [n]        |
+| Orphan Pages Detected           | [n]        |
+| Cannibalization Risks           | [n]        |
+| Focus Page Incoming Links       | [n]        |
+| Pages Exceeding Link Limit      | [n]        |
+
+---
+
+## Orphan Page Alert
+
+Pages with no incoming internal links — these are invisible
+to search engines and must be linked immediately:
+
+| Page Title                  | URL                  | Fix                              |
+|-----------------------------|----------------------|----------------------------------|
+| [title]                     | [url or "unpublished"]| Link from [suggested source page]|
+
+---
 
-Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).
+## Link Opportunities
 
-## When to Use This Skill
+Listed in priority order — highest impact first.
 
-- Use when building internal links between a new pillar page and its cluster articles
-- Use when auditing an existing site for orphan pages
-- Use after content-cluster generates a topic map
-- Use when you need anchor text suggestions with placement context
+---
+
+### 🔴 High Priority — Do These First
+
+**Link [n]**
+| Field              | Value                                             |
+|--------------------|---------------------------------------------------|
+| Link Type          | [Cluster → Pillar / Pillar → Cluster / etc]       |
+| Source Page        | [title]                                           |
+| Target Page        | [title]                                           |
+| Anchor Text        | [suggested anchor text]                           |
+| Anchor Type        | Partial match / Exact match / Branded             |
+| Placement          | [Where in the source page — intro / body / CTA]   |
+| Context Sentence   | "[Write the sentence the anchor should appear in, |
+|                    |  with anchor text in brackets like [this]]"       |
+| Impact             | [Why this link matters for SEO or AEO]            |
+
+---
+
+**Link [n]**
+[same format]
+
+---
 
-## How It Works
+### 🟡 Medium Priority — Do These Second
 
-### Step 1: Detect Orphan Pages
-Flag any page with zero incoming internal links. These are invisible to search engines and must be linked immediately.
+**Link [n]**
+[same format]
 
-### Step 2: Build Semantic Overlap Matrix
-Match pages by primary keyword similarity and content summary to identify natural linking opportunities.
+---
+
+### 🟢 Low Priority — Polish Round
 
-### Step 3: Assign Link Types
-Every suggestion gets one of four labels:
-- **Cluster → Pillar** — highest priority, consolidates authority upward
-- **Pillar → Cluster** — distributes authority downward
-- **Cluster → Cluster** — builds semantic depth
-- **Contextual Boost** — concentrates equity on a focus page
+**Link [n]**
+[same format]
 
-### Step 4: Write Context Sentences
-For every link opportunity, write the sentence the anchor text should appear in — naturally placed, not forced.
+---
 
-### Step 5: Check Anchor Text
-Flag any exact-match anchor used more than once for the same target page as a cannibalization risk. Never use generic anchors like "click here".
+## Cannibalization Risks
 
-## Examples
+Anchor text conflicts that could confuse search engines:
 
-### Example: Link Opportunity Output
-🔴 High Priority — Link 1
-Type: Cluster → Pillar
-Source: "How to Build a Budget That Actually Works"
-Target: "The Complete Guide to Automated Budgeting"
-Anchor: "automated budgeting guide"
-Context: "For a full breakdown of every method available,
-see our [automated budgeting guide]."
-Impact: Consolidates topical authority on pillar page.
-Orphan Alert:
-"PennyWise Pricing Page" has no incoming links.
-Fix: Add link from comparison table in Article 2.
+| Anchor Text Used    | Used On              | Points To            | Fix                        |
+|---------------------|----------------------|----------------------|----------------------------|
+| [anchor]            | [source page title]  | [target page title]  | [alternative anchor text]  |
 
-## Best Practices
+If none detected: ✅ No cannibalization risks found.
 
-- ✅ **Do:** Every cluster article must have at least one Cluster → Pillar link
-- ✅ **Do:** Write a context sentence for every suggestion — anchor text needs natural placement
-- ✅ **Do:** Fix orphan pages before adding any new links
-- ❌ **Don't:** Use the same exact-match anchor for the same target page more than once
-- ❌ **Don't:** Use "click here", "read more", or "learn more" as anchor text — ever
-- ❌ **Don't:** Add more than 100 outgoing internal links on any single page
+---
 
-## Common Pitfalls
+## Link Equity Map
 
-- **Problem:** All cluster articles link to the pillar but not to each other
-  **Solution:** Add Cluster → Cluster links between semantically related articles to build depth.
+Visual representation of how authority flows across the content:
 
-- **Problem:** Same anchor text used across multiple pages for the same target
-  **Solution:** Use partial match and branded anchors for subsequent links after the first exact-match use.
+[Focus Page / Pillar: {page title}]
+    ↑ receives links from:
+    ├── [Cluster Article 1] — anchor: [text]
+    ├── [Cluster Article 2] — anchor: [text]
+    └── [Cluster Article 3] — anchor: [text]
 
-## Related Skills
+    ↓ sends links to:
+    ├── [Cluster Article 1] — anchor: [text]
+    └── [Cluster Article 2] — anchor: [text]
+
+Cross-links between cluster articles:
+    [Article 1] ↔ [Article 3] — anchor: [text]
+    [Article 2] → [Article 4] — anchor: [text]
+
+---
 
-- `@seo-aeo-content-cluster` — generates the cluster map this skill links together
-- `@seo-aeo-schema-generator` — uses link map output for BreadcrumbList schema
+## Links Per Page Check
 
-## Additional Resources
+| Page Title          | Incoming Links | Outgoing Links | Status                          |
+|---------------------|----------------|----------------|---------------------------------|
+| [title]             | [n]            | [n]            | ✅ Healthy / ⚠️ Too many outgoing|
 
-- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
-- [Full Internal Linking SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/internal-linking/SKILL.md)
+**Rule:** No page should have more than 100 outgoing internal links.
+**Rule:** Focus page should have the highest incoming link count.
+
+---
+
+## Action Checklist
+
+- [ ] All orphan pages have been linked
+- [ ] Every cluster article has a Cluster → Pillar link
+- [ ] No exact-match anchor used more than once per target
+- [ ] No generic anchors ("click here", "read more") present
+- [ ] Focus page has the highest incoming link count
+- [ ] No page exceeds 100 outgoing internal links
+- [ ] Cannibalization risks resolved
+```
+
+---
+
+## Execution Steps
+
+1. Read `cluster_context` if provided — use it to understand
+   the pillar/cluster relationships before mapping any links
+2. Index all pages by `page_type` — pillar pages should receive
+   the most incoming links by default
+3. Run orphan detection — flag any page with zero incoming
+   links from other pages in the input set
+4. Build semantic overlap matrix — match pages by
+   `primary_keyword` similarity and `content_summary`
+   to identify natural linking opportunities
+5. Assign each opportunity a link type from the
+   Link Type Definitions table
+6. Write a context sentence for every suggestion —
+   the sentence should flow naturally and make the anchor
+   text feel editorially placed, not forced
+7. Check anchor text across all suggestions — flag any
+   exact-match anchor used more than once for the same
+   target page as a Cannibalization Risk
+8. Sort all opportunities into High, Medium, and Low
+   priority tiers based on link type and focus page impact
+9. Build the Link Equity Map showing authority flow
+10. Run the Links Per Page check — flag any page
+    exceeding 100 outgoing links
+11. Check product-page paths separately — confirm each
+    foundational article has at least one relevant conversion route
+12. Verify the map against the actual page inventory and links. If the project already provides a semantic-link helper, use it as a supplementary check; otherwise complete the checks manually and record the evidence used.
+
+---
+
+## Connected Skills
+- Receives output from: `seo-aeo-content-cluster`,
+  `seo-aeo-content-quality-auditor`
+- Feeds output to: `seo-aeo-schema-generator`
+
+## When to Use
+
+Use when mapping links between existing pages, identifying orphaned content, or improving conversion paths from informational pages.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Recommendations depend on the completeness and accuracy of the supplied page inventory and cannot replace a live crawl.