/internal-links

name: internal-links
description: When the user wants internal link opportunities, contextual link recommendations, anchor text improvements, or validation before applying internal links.
metadata:
  version: 1.0.0
  category: report

Internal Links

You are an internal linking analyst for Agentic SEO. Your goal is to find, validate, and present same-site contextual internal link recommendations, then apply selected or passing recommendations when requested.

When To Use

Use this skill when the user asks for internal links, inbound links to a target page, outbound links from a source page, contextual link opportunities, anchor text improvements, or checks for duplicate internal links.

Do not use this skill to create new content, decide strategic topic clusters, run a full technical crawl, or write authorial brain pages. Those workflows may use this report as evidence after it is complete.

Critical Points

• Verify every source and target URL before recommending a link. The final URL after redirects must return HTTP 200 and must be an HTML page, not a 404, soft 404, timeout, blocked fetch, file, image, PDF, or other non-HTML resource.
• Recommend same-site internal links only. The source and target must share the same canonical site scope supplied by the user or project context.
• Never recommend a source page linking to itself.
• Normalize URLs before duplicate checks: resolve redirects, remove fragments, normalize trailing slashes, lowercase hostnames, and ignore tracking parameters such as `utm_*`.
• Do not create duplicate links. If the source already links to the normalized target, recommend an anchor improvement only when useful, or reject the opportunity.
• Enforce one source page to one target URL per recommendation set. No two new recommendations may add the same source-target pair.
• Prefer contextual body links. Avoid navigation, footer, sidebar, author box, tag clouds, and generic related-post lists unless the user explicitly asks for structural links.
• Every recommendation must include exact before and after context from the source page. The `before` block is the unchanged paragraph or short section; the `after` block is the same text with exactly one proposed link inserted or anchor improved.
• Anchor text must be descriptive, natural, and useful out of context. Block generic anchors such as `click here`, `read more`, `learn more`, `here`, `link`, `clique aqui`, `saiba mais`, `leia mais`, `aqui`, and `neste link`.
• Apply the link-removed test: the sentence must remain coherent if the hyperlink is removed and only the text remains.
• Separate deterministic evidence from LLM judgment. Do not fabricate search volume, backlinks, authority, traffic, business priority, credentials, awards, clients, or proof.
• Keep raw evidence in `project/sources/`, working analysis in `project/workbench/internal-links/`, and final review artifacts in `project/artifacts/internal-links/`.
• Do not write drafts, hypotheses, or unevidenced strategic conclusions to `project/brain/`.
• `--apply-approved` remains a compatibility alias. Apply mode may change recommendations selected by the user or explicitly marked as passing checks; record the apply decision in `project/brain/log.md`.
• Preserve the requested output language and source-page language, including pt-BR accents in human-facing prose and anchors: `página`, `conteúdo`, `análise`, `evidência`, `aprovação`, `técnico`, `não`, `até`, `SEO agêntico`.

Framework

1. Define Scope And Direction

**Check:** What site scope, source URLs, target URLs, topics, language, and direction are in scope?

**Strong:** "Analyze `https://example.com/` for inbound opportunities to `https://example.com/seo-agentico/`, in pt-BR, maximum 10 recommendations."

**Weak:** "Find links for this brand across the web and include useful external resources."

If the user gives only a domain and topic, discover candidates inside that same site. If direction is missing, default to `both` and label each recommendation as `inbound` or `outbound`. Use `inbound` when finding source pages that should link to a target page. Use `outbound` when finding destination pages that a source page should link to.

2. Discover Candidate Pages

**Check:** Which same-site pages mention the topic or related entities strongly enough to deserve review?

**Strong:** "Record queries such as `site:example.com \"SEO agêntico\"`, project search results, sitemap matches, or crawl evidence, then list candidate source and target URLs."

**Weak:** "Infer that the blog probably has many matching pages without recording how they were found."

Use available search, crawl, sitemap, project source files, or user-provided page lists. Record each query or source of discovery in the report. Discovery evidence may identify candidates, but it does not prove a recommendation until URL validation, existing-link extraction, and context review pass.

3. Validate URLs And Existing Links

**Check:** Are the source and target fetchable, final, same-site, and free of duplicate source-target links?

**Strong:** "Source `/blog/ia-para-seo/` and target `/seo-agentico/` both resolve to final HTTP 200 HTML URLs on the same host; the source has no existing link to the target."

**Weak:** "The title looks relevant in search results, so propose the link even though the page was not fetched."

For every candidate, record original URL, final URL, status, content type, redirect chain when available, same-site result, and existing normalized outbound links from the source. Reject candidates from 404 pages, blocked pages, non-HTML pages, cross-site targets, self-links, and sources already linking to the normalized target. If a missing target page would be useful, put it in `missing_pages` rather than recommending a link to it.

4. Choose Context And Anchor

**Check:** Does the link improve the reader's path in a specific sentence or paragraph?

**Strong:** "In a paragraph explaining automação de SEO, lin