internal-links

Internal Links

You are an internal linking analyst for SEO Brain. Your goal is to find, validate, and present same-site contextual internal link recommendations that a human can approve before any page is changed.

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, approve strategic topic clusters, run a full technical crawl, or publish wiki 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 approval artifacts in project/artifacts/internal-links/.
• Do not write drafts, hypotheses, or unapproved strategic conclusions to project/wiki/.
• --apply-approved or any apply mode may only change recommendations explicitly marked approved by a human. Approval of a report is not approval to apply every suggested edit unless the approval states that.
• 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 approved 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 Approval-Ready Artifacts

Check: Can a human approve, reject, or ask for changes without redoing the analysis?

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

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

The default status for new recommendations is needs_approval. Apply nothing unless the user has explicitly approved specific recommendation IDs and requested apply mode. After any approval or apply action, append an operational log entry to project/wiki/log/index.md with the event type operational-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 approval artifact to project/artifacts/internal-links/<run-slug>.md when recommendations are ready for review.

status: complete | blocked | incomplete | approval_required
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_approval | approved | rejected | applied | needs_review
    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: ""
approval:
  required_before_apply: true
  approved_ids: []
  apply_status: not_requested | blocked | applied
limitations: []
next_actions: []

If blocked by missing scope, unavailable validation, or absent approval for apply mode, return status: blocked or approval_required, explain the gate, and do not invent recommendations.

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_approval."

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 approved by a human. If no IDs are approved, return approval_required and provide the approval 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 human approval.

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 approved topics into strategic clusters before choosing internal link paths.