Cross-Linker — Automated Wiki Cross-Referencing

You are weaving the wiki's knowledge graph tighter by finding and inserting missing

[[wikilinks]]

Follow the Retrieval Primitives table in

llm-wiki/SKILL.md

Read

Before You Start

1. Read

   .env

   to get

   OBSIDIAN_VAULT_PATH

2. Read

   index.md

   to get the full inventory of pages and their one-line descriptions
3. Skim

   log.md

   to see what was recently ingested (focus linking effort on new pages)

Step 1: Build the Page Registry

Glob all

.md

_archives/

.obsidian/

• Filename (without

  .md

  ) — this is the wikilink target
• Title from frontmatter
• Aliases from frontmatter (if any)
• Tags from frontmatter
• Category from frontmatter or directory inference
• One-line summary — first sentence or

  title

  field

Build a lookup table:

page_name → { path, title, aliases, tags, summary }

This is your "vocabulary" — every entry in this table is a valid wikilink target.

Step 2: Scan for Missing Links

For each page in the vault:

1. Read the full content

2. Extract existing wikilinks — find all

   [[...]]

   references already present

3. Search for unlinked mentions — check if the page's text contains any of these, without being wrapped in

   [[...]]

   :
   • Page filenames (e.g., the word "MyProject" appears but

     [[projects/my-project/my-project]]

     is missing)
   • Page titles from frontmatter
   • Aliases from frontmatter
   • Entity names, project names, concept names from the registry

4. Check for semantic connections — pages that share multiple tags or are in the same project directory but don't link to each other

Matching Rules

• Case-insensitive matching for names (e.g., "my-project" matches page

  MyProject

  )
• Diacritic-insensitive matching — normalize both the page name and the body text with Unicode NFKD (decompose accented characters to base + combining marks, strip combining marks) before comparing. This ensures body text "Muller" matches page

  [[entities/müller]]

  and vice versa.
• Skip self-references — a page shouldn't link to itself
• Skip common words — don't link "the", "and", generic terms. Only match on distinctive names
• Prefer the shortest unambiguous wikilink path — use

  [[page-name]]

  not

  [[full/path/to/page-name]]

  when the name is unique across the vault
• Don't link inside code blocks or frontmatter
• Don't double-link — if

  [[foo]]

  already appears on the page, don't add another

Step 3: Score and Rank Suggestions

Not every possible link is worth adding. Score each candidate using a composite signal, then tag it with a confidence label.

Scoring

#ai #agent

projects/my-project/

[[concepts/knowledge-graphs]]

concepts/

entities/

skills/

synthesis/

knowledge-graphs

Confidence labels

Tag each candidate with a confidence label based on its score:

Only act on EXTRACTED and INFERRED candidates. Include the confidence label in the Cross-Link Report so the user can review INFERRED links before trusting them.

Step 4: Apply Links

For each page with missing links:

4a: Inline linking (preferred)

Find the first natural mention of the term in the body text and wrap it in wikilinks:

Before:

This project uses knowledge graphs to connect entities.

After:

This project uses [[concepts/knowledge-graphs|knowledge graphs]] to connect entities.

Use the

[[path|display text]]

4b: Related section (fallback)

If the term isn't mentioned naturally in the body but the pages are semantically related (shared tags, same project), add a

## Related

## Related

- [[projects/my-project/my-project]] — Also uses AI agents for research automation
- [[concepts/knowledge-graphs]] — Core technique used in this project

If a

## Related

Step 5: Score Misc Page Affinity

After the main linking pass, update affinity scores for all pages in

misc/

promotion_status: misc

misc/

For each misc page:

1. Collect outgoing links — all

   [[wikilinks]]

   in the page body
2. Collect incoming links — grep the vault for

   [[misc/<slug>]]

   and

   [[<slug>]]

   references
3. For each linked page (both directions), check if it belongs to a project:
   • Lives under

     projects/<project-name>/

   • Has a

     project:

     frontmatter field matching a project name
4. Group by project name and sum:

   outgoing_links + incoming_links

5. Update the

   affinity

   frontmatter block on the misc page:

affinity:
  obsidian-wiki: 3
  another-project: 1

6. If any project's score ≥ 3: flag this page as a promotion candidate and record it for the report

Efficiency note: only read the full body of misc pages — other pages only need a frontmatter grep to determine their project membership.

Step 6: Report

Present a summary:

## Cross-Link Report

### Links Added: 23 across 12 pages

| Page | Links Added | Confidence | Type |
|---|---|---|---|
| `projects/my-project/my-project.md` | 3 | EXTRACTED | 2 inline, 1 related |
| `entities/jane-doe.md` | 5 | INFERRED | 3 inline, 2 related |
| ... | | | |

### Orphan Pages Remaining: 2
- `references/foo.md` — no incoming or outgoing links found
- `concepts/bar.md` — could not find related pages

### Misc Promotion Candidates: N
Pages in misc/ that have ≥ 3 connections to a single project — ready to be promoted:

| Page | Top Project | Score |
|---|---|---|
| `misc/web-martinfowler-articles-microservices.md` | `obsidian-wiki` | 4 |

To promote: move the page to `projects/<project-name>/references/` and update all backlinks.

### Pages Skipped: 3
- `index.md`, `log.md` — special files
- `_archives/*` — archived content

Step 7: Update Log and Hot Cache

Append to

log.md

- [TIMESTAMP] CROSS_LINK pages_scanned=N links_added=M pages_modified=P orphans_remaining=Q misc_affinity_updated=R promotion_candidates=S

hot.md

$OBSIDIAN_VAULT_PATH/hot.md

wiki-ingest

updated

Tips

• Run after every ingest. New pages are almost always poorly connected. This is the fix.
• Be conservative with inline links. Only link the first natural mention, not every occurrence.
• Don't touch pages in

  _archives/

  . Those are frozen snapshots.
• Respect existing structure. If a page carefully curates its links in a

  ## Key Concepts

  section, add to that section rather than creating a separate

  ## Related

  .
• Entity pages are link magnets. An entity like

  jane-doe

  should be linked from almost every project page. Prioritize these.