| name | seo-internal-linking |
| description | Audit and improve a site's internal-linking topology and semantic HTML — map pillar/cluster structure, count and grade contextual in-body links and anchor text, surface orphan pages and nav-heavy templates, and propose specific source→target link insertions. Module M10. Feeds the Search SEO score. |
| allowed-tools | Read, Grep, Glob, WebFetch, Bash |
seo-internal-linking (M10)
Internal links distribute crawl priority and topical authority and tell search engines (and AI crawlers) how your pages relate. Reference: references/schema-tier1.md for the entity/@id linkage this topology should mirror; M6/seo-entity-linking owns external sameAs.
Audits
Working from the PageSnapshot (rendered_dom if present, else raw_html):
- Pillar/cluster topology: classify each URL (pillar hub vs. cluster page) and confirm clusters link up to their pillar and the pillar links down to its cluster — gaps break the hub-and-spoke model.
- Contextual in-body links: count links inside
<main>/<article> prose (target ~3-5 descriptive in-content links per page); flag pages with zero in-body internal links.
- Anchor-text descriptiveness: flag generic anchors ("click here", "read more", "learn more", bare URLs) and over-optimized exact-match repetition; anchors should describe the destination.
- Orphan pages: list URLs in the sitemap/crawl with no incoming internal links from other crawled pages.
- Nav-vs-in-content ratio: flag templates where boilerplate nav/footer links overwhelm contextual links, diluting per-page link signal.
- Semantic HTML: check for
<main>, <article>, <nav>, <header>, <footer>, one <h1>, and a logical heading order — semantic structure helps both parsers and accessibility.
Fixes
- PROPOSED (
fixable: proposed): concrete internal-link insertions — a specific source page, the target URL, the suggested anchor text, and the sentence/selector to attach it to — emitted as a unified diff for fix. These require per-item accept because auto-injecting body links can alter meaning, tone, or reading flow.
- ADVISORY (
fixable: advisory): wrapping content in semantic tags (<main>/<article>/<nav>) and heading-order corrections — described, never written by the tool, since they touch template structure.
- Never invent target URLs, anchor wording, or topology you cannot observe in the snapshot/crawl — ask the user or leave a clearly-marked TODO placeholder. (Severity for this module's findings: 3.)
Verification
node ${CLAUDE_SKILL_DIR}/../../scripts/link-graph.mjs --url <u> builds the internal link graph (verification.method: link_graph) and asserts in-body link counts, orphan status, anchor quality, and pillar/cluster edges.- The full topology/orphan check needs a site-wide crawl tier. When that crawl data is unavailable, status is
needs_api — never a false pass.
Findings
Emit findings per schema/finding.schema.json. Examples:
M10.contextual.too_few_inbody_links — fewer than ~3 contextual in-body links (status warn, severity 3, fixable: proposed, axis search, confidence directional).M10.anchor.generic_text — anchor reads "click here"/"read more" (status warn, severity 3, fixable: proposed, axis search, confidence directional).M10.orphan.no_incoming_links — page has no internal inlinks from the crawl (status fail, severity 3, fixable: advisory, axis search, confidence established).M10.semantic.missing_main — no <main>/<article> landmark around primary content (status warn, severity 3, fixable: advisory, axis search, confidence directional).
Each finding: evidence.observed quotes the page (the anchor text, the link count, the offending element); verification.reproduce is the runnable link-graph.mjs command above; expected_impact is banded + confidence-tagged (no naked percentages).
Honesty
- A fixed "3-5 links per page" is a usability/structure heuristic, not a ranking law — treat the count as directional and never cap a score on it alone.
- Exact-match anchor stuffing and "more links = more authority" are myths: relevance and editorial context matter more than raw count, and excess can look manipulative. Recommend links only where they genuinely help the reader.
