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]] | "...ensuring Varic holds..." |

---

PARTIAL MATCHES (display text needed):

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

---

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
"the Owl knows"	The Owl	`[[The Owl
"young Edric"	Edric Valdren	`[[Edric Valdren

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

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