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:

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:

Partial Name Handling

When text contains a shorter form of an entity name:

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:

   code

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