linking-notes

name	linking-notes
description	Discover and add wiki-links between notes. Use when asked to "find connections", "link this note", "what should I link to", or "connect my notes".
allowed-tools	Read, Glob, Grep

Discovering Wiki-Link Connections

This skill helps find meaningful connections between notes in the knowledge base.

Workflow

1. Identify the Target Note

If a specific note is mentioned, read it first:

# List all content to find the note
ls src/content/notes/notes/*.md

Extract from the target note:

• Title
• Tags
• Key concepts/terms
• Existing wiki-links

2. Search for Related Content

By Title Mentions:

# Search for the note's title in other files
grep -l "note title" src/content/notes/notes/*.md

By Tag Overlap:

# Find notes sharing the same tags
grep -l "tags:.*tag-name" src/content/notes/notes/*.md

By Key Terms:

# Search for key concepts
grep -l "specific concept" src/content/notes/notes/*.md

3. Evaluate Connection Strength

Aim for connection, not perfection. Every note benefits from 2-3 meaningful links. An orphan note is harder to discover than an over-connected one.

✅ Link when:

• Same author or creator
• Explicitly references or cites the other work
• Directly builds on or responds to the other content
• Covers the same core topic (e.g., two notes about "habit formation")
• Part of the same series or project
• Should be grouped together in a Map Note (MOC)
• Offers a contrasting perspective on the same idea
• Applies theory from one note to practice in another

❌ Avoid linking when:

• Only a vague thematic overlap (e.g., "both mention AI")
• The connection requires multiple hops of reasoning
• You haven't read the target note and can't explain the relationship

Every link needs context. Don't just link - explain WHY the connection exists in 1 sentence.

4. Present Suggestions

For each suggested link, provide:

1. The slug to link: [[slug-name]]
2. Brief justification (1 sentence)
3. Where in the note it would fit (if applicable)

Output Format

## Suggested Wiki-Links for [Note Title]

### Strong Connections

- [[related-note-1]] - Same author, discusses related concepts
- [[related-note-2]] - Directly cited in this content

### Potential Connections (Review Needed)

- [[maybe-related]] - Shares "testing" tag, similar topic

Map Notes for Clustering

If you find a group of 3+ notes with strong thematic connections, consider suggesting a Map Note (MOC) instead of individual links:

# Check existing maps
grep -l "type: map" src/content/notes/notes/*.md

Map notes (type: map) create visual clusters on the graph - notes linked from the map are pulled together. This is useful for:

• Learning paths (e.g., "Vue 3 Development Guide")
• Topic clusters (e.g., "Leadership Principles")
• Curated collections (e.g., "AI Agents Roadmap")

Quality Checklist

Before suggesting links:

• Read the target note thoroughly
• Verified each suggestion has a strong, direct connection
• Excluded vague thematic overlaps
• Checked that suggested notes actually exist
• Provided clear justification for each link
• Considered whether a Map Note would better organize related content