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

# 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, link the existing phrase `SEO agêntico` to the checked guide because it clarifies the concept for readers."

**Weak:** "Append `Leia mais: SEO agêntico` at the end of the article because the keyword matches."

Choose the smallest exact block that gives enough context, usually one paragraph or list item. Use existing wording when possible. If changing wording is necessary for a natural anchor, keep the edit minimal and preserve spelling, punctuation, capitalization, and diacritics from the source language.

### 5. Score Judgment Separately From Checks
**Check:** Which parts are deterministic, and which parts are editorial judgment?

**Strong:** "Checks passed: both URLs are 200 HTML, same-site, no existing target link. Judgment: semantic fit is high because the paragraph introduces the concept that the target explains."

**Weak:** "This is high priority because it will increase rankings."

Use LLM judgment only for semantic fit, reader value, anchor naturalness, best paragraph, and whether a missing page is worth creating. Mark low-confidence matches as `needs-review`. Do not promise traffic, rankings, authority transfer, or conversion impact.

### 6. Produce Review-Ready Artifacts
**Check:** Can the user or agent accept, reject, apply, or revise recommendations without redoing the analysis?

**Strong:** "Write a machine-readable report and a human-readable review table showing source URL, target URL, edit location, exact before, exact after, anchor, checks, and decision status."

**Weak:** "Return a list of source and target pairs with no context or validation."

The default status for new recommendations is `needs_review`. Apply nothing unless apply mode is requested and the recommendation IDs or apply policy are clear. After any review or apply action, append an entry to `project/brain/log.md` with `type: decision`.

## Output Format

Write the machine-readable report to `project/workbench/internal-links/<run-slug>.yaml` unless the user asks for an inline preview first. Write the review artifact to `project/artifacts/internal-links/<run-slug>.md` when recommendations are ready for review.

```yaml
status: complete | blocked | incomplete
mode: report | apply-approved
site_scope:
  input: ""
  canonical_host: ""
  same_site_rule: ""
direction: inbound | outbound | both
language: ""
generated_at: ""
provider:
  discovery_methods: []
  notes: ""
queries:
  - query: ""
    purpose: ""
    result_count: null
verified_urls:
  - original_url: ""
    final_url: ""
    status: 200
    content_type: "text/html"
    same_site: true
    role: source | target
recommendations:
  - id: "il-001"
    status: needs_review | selected | rejected | applied
    direction: inbound | outbound
    source_url: ""
    source_final_url: ""
    target_url: ""
    target_final_url: ""
    location:
      heading: ""
      selector_or_section: ""
    anchor_text: ""
    before: ""
    after: ""
    reason: ""
    deterministic_checks:
      source_status_200: true
      target_status_200: true
      source_html: true
      target_html: true
      same_site: true
      not_self_link: true
      no_existing_source_target_link: true
      no_duplicate_recommendation: true
      non_generic_anchor: true
      exact_before_after_context: true
    judgment:
      semantic_fit: high | medium | low
      reader_value: high | medium | low
      confidence: high | medium | low
    evidence_refs:
      - ""
blocked_candidates:
  - source_url: ""
    target_url: ""
    reason: "404 | non_html | cross_site | self_link | already_links_to_target | duplicate | weak_context | generic_anchor | fetch_failed"
missing_pages:
  - suggested_url_or_topic: ""
    reason: ""
decision:
  required_before_apply: false
  selected_ids: []
  apply_status: not_requested | blocked | applied
limitations: []
next_actions: []
```

If blocked by missing scope, unavailable validation, or unclear apply scope, return `status: blocked`, explain the gate, and do not invent recommendations.

### Default delivery

Follow the shared `page-report` contract and the module skeleton at `templates/analyses/internal-links/report-skeleton.md`. The module-specific source artifact is the normalized internal-link YAML under `audits/internal-links-<run-slug>/report.yaml` or `workbench/internal-links/`; the Companion page is `project/analyses/internal-links/<run-slug>/report.md`. Present recommendations as readable source/target/anchor decisions with friendly validation names and exact `before`/`after` snippets in natural language; never paste raw crawl JSON or object arrays into the visual report body.

## Examples

### Example: Valid Inbound Recommendation
Input: "Find internal links to `/seo-agentico/` on `example.com`. Preserve pt-BR."

Output: "Validate `/seo-agentico/` and candidate source pages as final HTTP 200 HTML same-site URLs. Recommend `/blog/ia-para-seo/` only if it does not already link to the target. Use an exact `before` paragraph containing `SEO agêntico`, an `after` paragraph with that phrase linked, keep the accent, and mark the recommendation `needs_review`."

### Example: Duplicate Existing Link
Input: "`/blog/ferramentas-seo/` already links to `/seo-agentico/`. Add another contextual link."

Output: "Reject the duplicate insertion. If the existing anchor is generic and the context supports improvement, propose an anchor improvement with exact before and after blocks; otherwise add the candidate to `blocked_candidates` with reason `already_links_to_target`."

### Example: Apply Gate
Input: "Apply the internal links."

Output: "Apply only recommendation IDs explicitly selected or recommendations that pass the requested apply policy. If the scope is unclear, return `blocked` and provide the review table instead of changing files."

### Example: Weak Execution
Input: "Find internal links for SEO agêntico."

Output: "Suggest several blog URLs based on keyword similarity, include a 404 source page, strip the anchor to `SEO agentico`, and apply the edits immediately." This is weak because it skips URL 200 validation, includes an invalid page, removes pt-BR accents, and bypasses apply-scope checks.

## Related Skills

- `seo-analysis`: use when the primary task is SERP evidence, competitor comparison, or target-page gap interpretation before link planning.
- `content-seo`: use when the user wants a content brief, content draft, or page rewrite rather than link recommendations.
- `technical-seo`: use when the primary task is crawling, rendering, indexability, redirects, or page health.
- `topic-cluster`: use when the user wants to organize evidence-backed topics into strategic clusters before choosing internal link paths.