linking-notes

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 content/*.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" content/*.md

By Tag Overlap:

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

By Key Terms:

# Search for key concepts
grep -l "specific concept" content/*.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" content/*.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