# How Internal-Links-Map.md Integrates with the Internal Linker Agent for Strategic Linking

> Discover how internal-links-map.md integrates with the Internal Linker agent to create strategic internal links. Streamline your linking workflows for better SEO.

- Repository: [Craig/seomachine](https://github.com/TheCraigHewitt/seomachine)
- Tags: how-to-guide
- Published: 2026-03-12

---

**The [`internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/internal-links-map.md) file acts as the curated catalog of priority URLs and anchor text strategies, while the Internal Linker agent consumes this map via the `@context` reference to generate context-aware internal link recommendations during content creation and optimization workflows.**

Strategic internal linking requires both comprehensive site knowledge and contextual intelligence to place the right links in the right content. In the TheCraigHewitt/seomachine repository, this challenge is solved through a tight integration between the [`context/internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/context/internal-links-map.md) data file and the Claude-powered Internal Linker agent. This architecture separates the "what to link" (the map) from the "how to link strategically" (the agent), enabling automated yet nuanced internal link placement.

## The Two-Component Architecture

The integration relies on two distinct files working in tandem:

| Component | File Path | Purpose |
|-----------|-----------|---------|
| **Link Map** | [`context/internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/context/internal-links-map.md) | A human-maintained catalog containing URLs, ideal linking contexts ("When to Link"), and suggested anchor text examples. |
| **Agent Logic** | [`.claude/agents/internal-linker.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/agents/internal-linker.md) | The instruction set that defines linking strategy, placement rules, and explicitly references the map file using `@context/internal-links-map.md`. |

This separation allows content strategists to update link priorities by editing the markdown map, while the agent automatically adapts its recommendations without requiring logic changes.

## Step-by-Step Integration Workflow

### Step 1: Agent Initialization and Map Loading

When the Internal Linker agent is invoked—either during a `/write` or `/optimize` command—it first loads the reference material defined in its configuration. The agent definition explicitly instructs:

```markdown
#### Reference Material Review

- Check @context/internal-links-map.md for priority linking targets
- Identify which Castos pages align with article topics:
  - **Pillar content**
  - **Related blog posts**
  - **Product pages**
  - **Resource pages**
  - **How‑to guides**

```

*Lines 33‑36 from the agent file illustrate the direct reference*【2†L33-L36】. The `@context` shortcut automatically loads the contents of [`internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/internal-links-map.md) into the agent's context window.

### Step 2: Priority-Based Link Targeting

Once loaded, the map provides hierarchical signals that the agent uses to rank link opportunities:

- **Pillar content** → Highest priority (link from cluster articles to establish topical authority)
- **Top-performing blog posts** → Medium priority (support related topics and distribute equity)
- **Resource or comparison pages** → Low-to-medium priority (used only when the article mentions specific use-cases)

The map groups pages by type (homepage, product pages, pillar posts) and supplies *When to Link* descriptors that the agent evaluates against the draft's subject matter.

### Step 3: Context Matching and Concept Extraction

During the **Content Context Mapping** phase, the agent scans the generated draft to extract key concepts and entities. It then matches these against the *When to Link* descriptors from the map. For example, if the draft mentions "pricing plans," the map entry for the **Pricing Page** (URL `https://[yoursite.com]/pricing`) contains a matching descriptor, triggering a link recommendation for that specific context.

### Step 4: Anchor Text Optimization

The *Anchor Text Examples* field in the map provides ready-made, SEO-friendly anchor phrases. The agent applies **Anchor Text Optimization** rules—ensuring text is descriptive, natural, and varied—to select or adapt the best phrase for the current sentence【2†L78-L86】. This prevents over-optimization while maintaining keyword relevance.

### Step 5: Structured Recommendation Output

The agent returns a structured recommendation block that the orchestration commands consume:

```markdown
#### Recommended Internal Links

**Link 1 – High Priority**  
- **Link To**: Pricing Page – https://[yoursite.com]/pricing  
- **Page Type**: Product  
- **Placement**: After the sentence “Our flexible pricing plans start at $…”.  
- **Anchor Text**: “pricing plans”  
- **Why**: Gives readers a direct path to purchase information, distributes link equity to a high‑value conversion page.  

**Link 2 – Medium Priority**  
- **Link To**: “Podcast Hosting Guide” – https://[yoursite.com]/blog/podcast-hosting-guide  
- **Page Type**: Pillar  
- **Placement**: End of the “Choosing a host” paragraph.  
- **Anchor Text**: “choosing the right podcast hosting platform”  
- **Why**: Strengthens the pillar‑cluster relationship.

```

*The structure mirrors the output template defined in the agent file*【2†L48-L66】. This output is then processed by the `/write` or `/optimize` commands to physically insert the links into the markdown article.

## Implementation Examples

### Triggering the Integration via Write Commands

The linking process is triggered automatically when creating content:

```bash

# User runs the write command

/claude .claude/commands/write.md "How to launch a podcast in 2024"

# Internally:

# 1️⃣ Draft is generated.

# 2️⃣ Internal‑Linker agent loads @context/internal-links-map.md.

# 3️⃣ Agent scans the draft, matches “pricing” → suggests link to Pricing Page.

# 4️⃣ Agent returns a recommendation block (Link 1 … Link 5).

# 5️⃣ The draft is updated with the recommended internal links.

```

This seamless integration ensures that every new article automatically incorporates strategic internal links based on the latest site architecture defined in the map.

## Key Files and Their Roles

| File | Role in the Integration |
|------|------------------------|
| **[`context/internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/context/internal-links-map.md)** | The authoritative source of truth containing URLs, linking contexts, and anchor text examples that the agent consults for every recommendation. |
| **[`.claude/agents/internal-linker.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/agents/internal-linker.md)** | Defines the linking strategy, quantity limits, placement rules (e.g., "first link within first 200 words"), and the explicit reference to the map file. |
| **[`.claude/commands/write.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/commands/write.md)** | Orchestrates the content creation flow; after generating the initial draft, it invokes the Internal Linker agent to embed strategic links before finalizing output. |
| **[`.claude/commands/optimize.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/commands/optimize.md)** | Runs the Internal Linker on existing drafts to refresh or improve internal linking based on the current state of the map. |

## Summary

- **[`internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/internal-links-map.md)** serves as the static knowledge base of priority pages and anchor strategies for the SEO Machine workflow.
- The **Internal Linker agent** dynamically consumes this map via the `@context/internal-links-map.md` reference to make contextual linking decisions.
- The integration follows a five-step pipeline: map loading, priority ranking, context matching, anchor optimization, and structured output generation.
- **[`.claude/commands/write.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/commands/write.md)** and **[`.claude/commands/optimize.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/commands/optimize.md)** act as the orchestration layer that triggers the agent during content operations.
- This architecture enables non-technical users to influence automated linking strategy simply by updating a markdown file.

## Frequently Asked Questions

### What is the purpose of internal-links-map.md in SEO Machine?

The [`internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/internal-links-map.md) file serves as the central repository of linking intelligence for the site. It contains categorized lists of important URLs (pillar pages, product pages, resources), descriptions of when each should be linked, and suggested anchor text examples. This file transforms the agent from a generic link suggester into a domain-specific SEO strategist that understands your specific site architecture and business priorities.

### How does the Internal Linker agent prioritize which links to suggest?

The agent uses a hierarchy defined in the map file and reinforced by the agent's logic. **Pillar content** receives highest priority for linking from cluster articles, **top-performing blog posts** get medium priority for related topic support, and **resource pages** are suggested only when specific use-cases are mentioned. The agent evaluates the draft's content against the "When to Link" descriptors in the map to determine relevance before applying these priority weights.

### Can I customize the internal link suggestions for different content types?

Yes, customization occurs primarily through editing the [`context/internal-links-map.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/context/internal-links-map.md) file. By adjusting the "When to Link" contexts, adding new URLs, or modifying the "Anchor Text Examples," you directly influence the agent's recommendations without changing code. For more advanced customization, you can modify the agent definition in [`.claude/agents/internal-linker.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/agents/internal-linker.md) to adjust quantity limits, placement rules, or priority logic.

### How does the write command trigger the internal linking process?

When you execute `/claude .claude/commands/write.md`, the command first generates the article draft. It then invokes the Internal Linker agent, which automatically loads the `@context/internal-links-map.md` file as reference material【2†L33-L36】. The agent analyzes the draft, generates link recommendations following the output template【2†L48-L66】, and returns these to the command, which inserts the links into the final markdown before presenting the completed article.