SKILL.md — note-linking

Auto-discover hidden connections between your notes. Bidirectional links, knowledge graphs, and semantic link suggestions — without plugins.

What This Skill Does

Analyzes a directory of notes (markdown, txt, org, obsidian vault) and:

1. Extracts — reads all notes, splits by headings, extracts content blocks
2. Understands — detects entities (people, projects, topics, tools), infers relationships
3. Links — generates bidirectional link suggestions with confidence scores
4. Graphs — builds a knowledge graph showing how notes connect
5. Queries — traverse the graph: "show me all notes related to X", "who links to Y"

Unlike the incumbent slipbot (which does keyword matching), this skill uses semantic understanding — it knows that "LLM" relates to "language model" and "transformer architecture" even without exact keyword overlap.

When to Trigger

Trigger when user says:

• "link my notes"
• "find connections between notes"
• "build a knowledge graph from my notes"
• "what relates to X in my notes"
• "show me all notes about Y"
• "I have notes scattered, can you organize them"
• "bidirectional links"
• "backlinks"
• "how does A connect to B"

Input

Output

Markdown Format (default)

## Knowledge Graph

### Notes Analyzed: 47
### Total Links Found: 134
### Orphan Notes: 3 (unconnected)

## Top Hubs (most linked)
1. **AI_Agent_Architecture.md** — 18 connections
2. **Memory_System_Design.md** — 14 connections
3. **GitHub_Strategy.md** — 11 connections

## Link Suggestions
| From | To | Confidence | Reason |
|------|----|-----------|--------|
| EvoMap.md | Memory_System_Design.md | 0.94 | Shared topic: self-evolution |
| GitHub_Strategy.md | clawhub_publish.md | 0.91 | Project: SKY-lv repo family |
| AI_Agent_Architecture.md | hermes-agent-integration.md | 0.87 | Tool integration |

## Backlinks
### EvoMap.md (3 backlinks)
← Memory_System_Design.md (self-repair loop concept)
← skill-market-analyzer.md (GEP protocol reference)
← agent-builder.md (evolution pattern)

Graph Format

{
  "nodes": [{"id": "note-name", "connections": 18, "topics": [...]}],
  "edges": [{"from": "A", "to": "B", "weight": 0.94, "reason": "..."}]
}

Technical Approach

Architecture

notesPath/
├── link_engine.js     ← Core: read → extract → analyze → graph
├── graph_query.js     ← Traverse graph, answer questions
└── export.js         ← Export as Obsidian markdown, JSON, CSV

link_engine.js Core Logic

Phase 1: Index

• Recursively find all .md, .txt, .org files
• Parse frontmatter (YAML/toml headers)
• Split into content blocks (by heading or double newline)

Phase 2: Entity Extraction

• Named entities: people, organizations, tools (NER-lite regex)
• Topics: extract noun phrases, technical terms
• Keywords: TF-IDF top terms per note

Phase 3: Relationship Detection

Relationship Score = cosine_similarity(embedding_A, embedding_B)

Without external embedding APIs, use:

• Keyword overlap (Jaccard) weighted by TF-IDF
• Co-occurrence in same paragraph / section
• Structural links: same directory, similar filename, shared YAML tags
• Explicit mentions: [[wikilink]] or [note name] patterns

Phase 4: Graph Construction

const graph = {
  nodes: Map<noteId, {file, topics, keywords, blocks}>,
  edges: Map<noteId, Map<noteId, {score, reasons, type}>>
}

Phase 5: Query

• Find shortest path between two notes
• List N-degree neighbors
• Find bridges (notes that connect otherwise separate clusters)

Threshold Strategy

Implementation Notes

Pure Node.js (no external APIs)

For embedding-free similarity, use:

1. TF-IDF vectors per note (term frequency × inverse document frequency)
2. Jaccard similarity on keyword sets
3. Levenshtein distance on headings to catch near-matches
4. YAML tag intersection for structured vaults

Obsidian Compatibility

• Read existing [[wikilink]] syntax
• Write new links in Obsidian format
• Respect ![[embed]] and ![[callout]] patterns

Performance

• Index vault once, cache in ~/.qclaw/note-linking-graph.json
• Incremental update on file change (watch mode)
• Max file size: 1MB per note (skip binary/exec)

Real Data (2026-04-11 Market Analysis)

Skills That Compose Well With

• skylv-knowledge-graph — if you want full graph visualization
• skylv-file-versioning — version your note graph over time
• skylv-ai-prompt-optimizer — optimize your note-taking prompts

Usage

1. Install the skill
2. Configure as needed
3. Run with OpenClaw