linkify

Linkify Entity

Linkify: $ARGUMENTS

Overview

This skill scans an entity file and automatically wraps any mentions of existing entities in [[wikilink]] syntax. It's a focused tool that only adds links to entities that already exist—it does NOT create new entities.

Quick Start

# Linkify a specific entity
/linkify "Aldersgate"

# Preview changes without modifying
/linkify "Aldersgate" --dry-run

# Linkify by file path
/linkify Worlds/Eldermyr/Settlements/Aldersgate.md

BULK: Linkify all entities in a world

/linkify --world Eldermyr

BULK: Linkify only Characters in a world

/linkify --world Eldermyr --category Characters

BULK: Preview bulk changes

/linkify --world Eldermyr --dry-run

## Instructions

### Step 1: Parse Arguments

**Required:**
- Entity path or name

**Optional Flags:**
| Flag | Purpose | Default |
|------|---------|---------|
| `--dry-run` | Show what would be linked without making changes | false |
| `--all-worlds` | Search all worlds for entities, not just the source entity's world | false |
| `--case-sensitive` | Require exact case matching | false |
| `--world [name]` | **BULK MODE:** Process all entities in the specified world | - |
| `--category [type]` | With `--world`: only process entities in this category (Characters, Settlements, etc.) | all |

### Step 2: Locate Entity & Determine World

1. **If path provided** (contains `/` or `.md`):
   - Read the file directly
   - Extract world name from path: `Worlds/[World Name]/...`

2. **If name provided**:
   - Search `Worlds/` directories for matching entity
   - Try exact filename match first
   - Then fuzzy match on filename and YAML `name:` field
   - If multiple matches, list them and ask user to clarify

3. **If not found**:
   - List similar entities and ask for clarification

### Step 3: Build Entity Index

Create a complete index of existing entities:

1. **Scan all files** in `Worlds/[World Name]/` recursively (or all worlds if `--all-worlds`)
2. **For each entity file**, extract:
   - Filename (without .md extension) → primary name
   - YAML `name:` field → canonical name
   - YAML `aliases:` array → alternative names
3. **Build lookup dictionary** (case-insensitive by default):

{ "Lord Varic Valdren": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" }, "Varic": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" }, "The Merchant Lord": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" }, ... }

**Important:** Sort the lookup dictionary by name length (longest first) to ensure longer matches are found before shorter partial matches.

### Step 4: Identify Content to Scan

Read the source entity file and identify sections to scan:

**INCLUDE these sections:**
- Overview
- Geography
- History
- Demographics
- Government & Politics
- Economy
- Defense & Military
- Notable Locations
- Key Figures
- Secrets
- Plot Hooks
- Description
- Any custom content sections

**EXCLUDE these sections:**
- YAML frontmatter (between `---` markers)
- Image Prompts section and everything after it
- Connections section (already has wikilinks)
- Code blocks (between ``` markers)
- Existing wikilinks `[[...]]`
- Block quotes used for image prompts (lines starting with `>` after `**Prompt:**`)

### Step 5: Find Matches

For each entity name/alias in the index (longest first):

1. **Skip if entity is the source file itself** (don't self-link)

2. **Search for the name in content:**
   - Use word-boundary matching to avoid partial matches within words
   - Match: "Lord Varic Valdren" in "talked to Lord Varic Valdren about"
   - Skip: "Lord Varic Valdren" in "[[Lord Varic Valdren]]" (already linked)
   - Skip: "Stone" in "Aldric Stone" if "Aldric Stone" is a separate entity

3. **Record each match:**
   - Line number
   - Exact text matched
   - Canonical entity name (for the wikilink)
   - Surrounding context (5 words before/after)

4. **Handle partial name matches:**
   - If "Lord Varic Valdren" exists but text says "Lord Varic", offer to link as `[[Lord Varic Valdren|Lord Varic]]`
   - If "House Valdren" exists but text says "the Valdren house", consider display text

### Step 6: Present Findings

=== LINKIFY ANALYSIS: [Entity Name] ===

World: [World Name] Source: [path/to/entity.md] Entities Indexed: X

---

MATCHES FOUND: Y

#	Text Found	Line	Links To	Context
1	Lady Serana Valdren	121	[[Lady Serana Valdren]]	"...wife, manages court..."
2	High Confessor Maren	136	[[High Confessor Maren]]	"...supporters, seeking..."
3	Sister Elspeth	204	[[Sister Elspeth]]	"...Abbess of the..."
4	Lord Varic	117	[[Lord Varic Valdren	Lord Varic]]

---

PARTIAL MATCHES (display text needed):

#	Text Found	Line	Suggested Link
1	"the Owl"	123	[[The Owl
2	"young Edric"	117, 177	[[Edric Valdren

---

AMBIGUOUS (multiple possible matches):

#	Text Found	Line	Could Match
1	"Edric"	177	[[Edric Valdren]] or [[Prince Edric the Liberator]]

---

SUMMARY:

• Exact matches: X
• Partial matches: X
• Ambiguous: X
• Total changes: X

Options:

1. Apply all exact matches
2. Apply exact + partial matches
3. Review each individually
4. Dry run complete (--dry-run flag)

If `--dry-run` flag is set, show report and stop.

### Step 7: Apply Changes

For each approved match:

1. **Build replacement text:**
   - Exact match: `EntityName` → `[[EntityName]]`
   - Partial match: `PartialName` → `[[FullEntityName|PartialName]]`

2. **Apply using Edit tool:**
   - Process from bottom of file to top (so line numbers don't shift)
   - Use precise string replacement with surrounding context for uniqueness
   - Verify each replacement succeeded

3. **Handle duplicates:**
   - If the same entity is mentioned multiple times, link ALL occurrences
   - Exception: Don't link the same name twice in the same sentence

### Step 8: Validation

After applying changes:

1. Re-read the file
2. Verify all intended wikilinks are present
3. Check no content was accidentally corrupted
4. Verify wikilinks point to existing files

### Step 9: Summary Report

=== LINKIFY COMPLETE: [Entity Name] ===

Changes Applied: X

Links Added:

• [[Lady Serana Valdren]] (line 121)
• [[High Confessor Maren]] (line 136)
• [[Sister Elspeth]] (lines 204, 252)
• [[Lord Varic Valdren|Lord Varic]] (line 117)

Skipped (ambiguous):

• "Edric" (line 177) - multiple matches possible

---

File Updated: [path/to/entity.md]

Suggested Next Steps:

• Review ambiguous matches manually
• Run /audit-world to check bidirectional links
• Use /link-entities to add reciprocal connections

## Matching Rules

### Word Boundary Matching

Only match complete words/phrases:

| Text | Entity | Match? | Reason |
|------|--------|--------|--------|
| "spoke to Lord Varic Valdren about" | Lord Varic Valdren | Yes | Complete phrase |
| "the Valdren family" | House Valdren | No | "Valdren" alone, different entity |
| "visited Aldersgate" | Aldersgate | Yes | Complete word |
| "Aldersgates" | Aldersgate | No | Different word |
| "[[Lord Varic Valdren]]" | Lord Varic Valdren | No | Already linked |

### Partial Name Handling

When text contains a shorter form of an entity name:

| Text | Entity | Link Format |
|------|--------|-------------|
| "Lord Varic said" | Lord Varic Valdren | `[[Lord Varic Valdren|Lord Varic]]` |
| "the Owl knows" | The Owl | `[[The Owl|the Owl]]` |
| "young Edric" | Edric Valdren | `[[Edric Valdren|young Edric]]` |

### Case Handling

By default (case-insensitive):
- "lord varic valdren" matches "Lord Varic Valdren"
- Original case is preserved in display text

With `--case-sensitive`:
- Only exact case matches

### Exclusion Patterns

Never link:
- Text inside existing `[[wikilinks]]`
- Text in YAML frontmatter
- Text in code blocks
- Text in Image Prompts section
- The entity's own name (no self-linking)
- Text that's part of a markdown header (`# Name`)
- Text in the Connections section (manage links there separately)

## Bulk Processing Mode

When `--world` flag is provided, the skill processes multiple entities:

### Bulk Mode Workflow

1. **Scan world directory:**
   - List all `.md` files in `Worlds/[World Name]/`
   - If `--category` specified, only scan that folder (e.g., `Characters/`)
   - Exclude `World Overview.md` by default (use `--include-overview` to include)

2. **Build combined entity index:**
   - Same process as single-entity mode
   - Index is built once and reused for all files

3. **Process each entity:**
   - For each file, run Steps 4-7 (Find Matches → Apply Changes)
   - Track cumulative statistics

4. **Batch report:**

=== BULK LINKIFY COMPLETE: [World Name] ===

Files Processed: X Files Modified: Y Files Unchanged: Z

Total Links Added: N

By Category:

• Characters: X files, Y links
• Settlements: X files, Y links
• Organizations: X files, Y links ...

Skipped (ambiguous): N references across M files

Performance: X.X seconds total

### Bulk Mode Options

```bash
# Process entire world
/linkify --world Eldermyr

# Process only one category
/linkify --world Eldermyr --category Settlements

# Dry run to preview bulk changes
/linkify --world Eldermyr --dry-run

# Process multiple categories
/linkify --world Eldermyr --category Characters --category Organizations

Performance Notes

For large worlds (100+ entities), bulk mode:

• Builds the entity index once (faster than per-file)
• Processes files in parallel where possible
• Reports progress every 10 files
• For very large worlds (300+), consider using scripts/linkify_world.py instead

Examples

# Basic linkify
/linkify "Aldersgate"

# Preview what would be linked
/linkify "Aldersgate" --dry-run

# Linkify checking all worlds for entities
/linkify "Aldersgate" --all-worlds

# Linkify by path
/linkify Worlds/Eldermyr/Settlements/Aldersgate.md

# Case-sensitive matching
/linkify "Lord Varic Valdren" --case-sensitive

Integration with Other Skills

After /create-entity

Run /linkify on newly created entities to link any mentioned existing entities.

Before /audit-world

Run /linkify on key entities to add missing links before the audit.

With /link-entities

• /linkify adds wikilinks within entity content
• /link-entities manages the Connections section relationships
• Use together for comprehensive linking

With /populate-entity

• /linkify only links to EXISTING entities
• /populate-entity --links-only does the same thing
• /populate-entity (full) also CREATES missing entities
• Use /linkify when you just want to add links without creating anything

Error Handling

File not found:

Error: Could not find entity "[name]"
Similar entities in Worlds/:
- [similar1]
- [similar2]
Please specify the full path or exact name.

No matches found:

=== LINKIFY: [Entity Name] ===

No unlinked entity references found.

This file either:
- Already has all entities properly linked
- Contains no references to other known entities
- References entities that don't exist yet (use /populate-entity to create them)

Write permission error:

Error: Could not write to [path]
The dry-run showed X matches. Please check file permissions.