Skylv Note Linking

Automatically creates bidirectional links between related notes

Security Scan

The skill's code and runtime instructions are coherent with its stated purpose (building links between notes); it runs locally, needs no external credentials, but it will read and can modify your note files (auto-insert links) and write a cache — review and back up your notes before use.

Purpose & Capability

Name/description (auto-discover links, build knowledge graph) match the included code and SKILL.md. The three JS files implement discovery, TF‑IDF/Jaccard/Levenshtein scoring, graph construction, queries and export — all align with the stated functionality. No unrelated dependencies, binaries, or external APIs are requested.

Instruction Scope

Instructions tell the agent to scan a notes directory (default ~/.qclaw/workspace) and produce links/graphs. The code does more than only read: export.js can modify source notes by appending `Related` sections for edges marked 'auto' (AUTO_LINK_THRESHOLD 0.85). SKILL.md documents auto-linking behavior, but users should be aware the skill will write into their files and create a cache file. Also a minor doc/code discrepancy: SKILL.md mentions cache in ~/.qclaw, while code uses a temp path (process.env.TEMP or /tmp).

Install Mechanism

No install spec (instruction-only skill with shipped code) — code is pure Node.js and runs locally with no downloads or external installers. This is low risk from an install mechanism perspective because nothing is fetched or extracted at install time.

Credentials

The skill requires no secrets or credentials. It reads common environment variables for defaults (HOME/USERPROFILE and TEMP) to build paths, which is expected. It does not attempt to access unrelated credentials or remote endpoints.

Persistence & Privilege

always:false and no agent-wide config modifications — good. However, the skill persists data: it writes a cache file in the temp directory and (unless you choose non-auto export) export.js will automatically modify note files by adding wikilinks for matches ≥ 0.85. This is an intentional behavior but is a privileges-like concern because it changes user data without an additional approval step.

Assessment

This skill appears to do what it says: it scans a notes directory, builds a local graph, and can suggest or automatically insert bidirectional links. Before installing or running it: 1) Back up your notes (it can modify files when it auto-links). 2) Run it on a copy or a small test folder first to confirm results. 3) Prefer suggestion mode (inspect outputs) before enabling automatic edits — you can inspect/modify export.js to change AUTO_LINK_THRESHOLD or disable the auto-write block. 4) Provide an explicit notesPath when invoking (don’t rely on defaults) and check the cache file location if you have policies about temp files. 5) Confirm there are no network calls in any local edits you plan to run (the shipped code is local-only). If you need stronger assurances, request a code review for the truncated portion of link_engine.js (the file was truncated in the provided package) and test behavior on non-critical notes.

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

Field	Type	Description
notesPath	string	Path to notes directory (default: ~/.qclaw/workspace/)
query	string	Optional: specific question about note relationships
depth	number	Link traversal depth (default: 2)
format	string	graph / list / markdown (default: markdown)

---

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

Confidence	Condition	Action
≥ 0.85	Strong semantic match	Auto-link (add [[wikilink]])
0.60–0.84	Probable match	Suggest with reason
0.40–0.59	Weak match	Flag as "possible"
< 0.40	Noise	Ignore

---

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)

Metric	Value
Current incumbent	slipbot (score: 1.021)
Top target score	3.5
Gap	3.43× improvement possible
Incumbent weakness	Keyword-only matching, no graph

---

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