Agent skill
vault-index
Build, query, and traverse an Obsidian-style markdown vault as a knowledge graph. Use this skill whenever the user asks to index their vault, find related notes, search vault content, discover orphan or broken-link files, traverse connections between notes, do semantic search across the vault, or surface proactive suggestions about what to link next. Always load this skill when the words "vault", "knowledge graph", "vault-index", or "obsidian notes" appear in context.
Install this agent skill to your Project
npx add-skill https://github.com/akaihola/skills-akaihola/tree/main/vault-index
SKILL.md
vault-index skill
Tools for indexing an Obsidian-style markdown vault into a SQLite database and querying it as a knowledge graph.
Environment
Set VAULT_ROOT to the vault directory, or pass --vault PATH to every
command. The default falls back to VAULT_ROOT env var, then the current
working directory.
export VAULT_ROOT=~/my-knowledge # or pass --vault each time
Commands
All commands live in scripts/vault-index.py and are PEP 723 standalone
scripts (run with uv run or directly if uv is on PATH).
build – rebuild the index
Parse every .md file, extract wiki-links, frontmatter relationships, tags,
and (when enabled) chunk text for FTS5 / embeddings.
uv run vault-index/scripts/vault-index.py build
uv run vault-index/scripts/vault-index.py build --vault ~/my-knowledge
VAULT_ROOT=~/my-knowledge python vault-index/scripts/vault-index.py build
Run after any significant batch of vault edits, or hook it into a git post-commit.
traverse – graph traversal from a note
Walk outgoing and incoming edges from a starting file and print a tree.
uv run vault-index/scripts/vault-index.py traverse "Vault Knowledge Graph"
uv run vault-index/scripts/vault-index.py traverse "Second Brain" --depth 3
Use this when the user asks "what's related to X?" or wants to see how a note connects to the rest of the vault.
gaps – orphan and broken-link report
Find project files with no connections, broken wiki-links, and link distribution statistics.
uv run vault-index/scripts/vault-index.py gaps
Use for vault maintenance: after major edits, or when preparing a health report.
search – full-text and semantic search (Phase 2b)
uv run vault-index/scripts/vault-index.py search "semantic search" --mode fts
uv run vault-index/scripts/vault-index.py search "MCP tool discovery" --mode hybrid
uv run vault-index/scripts/vault-index.py search "pykoclaw" --entity
suggest – related note suggestions (Phase 3)
uv run vault-index/scripts/vault-index.py suggest "Vault Knowledge Graph"
Database
The index is stored in <vault>/.vault-index.db (SQLite). It is fully
disposable and rebuildable from the markdown source files. Add it to
.gitignore.
Core schema (Phase 2a)
| Table | Contents |
|---|---|
files |
One row per .md file – path, title, type, status, dates |
tags |
Frontmatter tags per file |
edges |
Wiki-links and typed frontmatter relationships |
Extended schema (Phase 2b+)
| Table | Contents |
|---|---|
content_chunks |
Heading-split chunks with heading path |
fts_chunks |
FTS5 virtual table for keyword search |
embeddings |
Per-chunk embedding vectors (sqlite-vec) |
entities |
Named entities (projects, tools, people, …) |
entity_mentions |
Where each entity is mentioned |
inline_relations |
Typed body-level relations (- depends_on [[X]]) |
Relationship vocabulary
Used in frontmatter fields and body-level inline relations:
| Relation | Meaning |
|---|---|
depends_on |
This note/project requires the target |
blocks |
This work prevents the target from progressing |
related |
Sibling topic (bidirectional) |
builds_on |
Extends or elaborates on the target |
similar_to |
Different angle on the same subject |
contradicts |
This note disagrees with the target |
Inline relation format (body text)
- depends_on [[pykoclaw plugin system]]
- related_to [[Agent Commons]]
- builds_on [[Second Brain]]
Agent behaviour guide
| User intent | Preferred tool |
|---|---|
| "what's related to X?" | traverse |
| fuzzy recall / "that note about Y" | search --mode hybrid |
| vault maintenance, orphans | gaps |
| after editing a file | suggest |
When the index may be stale (vault files newer than .vault-index.db), warn the
user and offer to rebuild before answering retrieval questions.
Development notes
- Tests live in
vault-index/tests/; run withuv run pytest vault-index/tests/ - The index is always rebuildable from markdown — never treat it as canonical
- Phase roadmap: 2a (structural, ✅) → 2b (FTS5 + embeddings) → 3 (MCP) → 4 (proactive)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
akaihola/skills-akaihola
youtube-to-markdown
Convert a YouTube video into clean, readable Markdown using its free auto-generated captions (no paid API needed). Use when the user asks to "convert YouTube video to markdown", "get transcript from YouTube URL", "summarise this video", or wants to turn YouTube subtitles/captions into readable text. Prefer this over youtube-transcription when the video already has auto-generated subtitles — it's free and faster. Accepts YouTube URLs.
akaihola/skills-akaihola
brave-search
Search the web using Brave Search API. Use when the user asks to "search the web", "look up current information", "find news about", "research a topic online", "check prices online", or needs up-to-date facts that may not be in the model's training data. Requires BRAVE_SEARCH_API_KEY. Supports structured web results (pages, FAQs, news, videos) and an optional AI summarizer.
akaihola/skills-akaihola
verkkokauppa
Search products on the Verkkokauppa.com Finnish webshop. This skill uses the Verkkokauppa search API directly, requiring no browser. Use when the user asks to "search Verkkokauppa", "find products on verkkokauppa.com", "verkkokauppa product search", "check Verkkokauppa prices", or mentions searching the Verkkokauppa store.
akaihola/skills-akaihola
clasohlson
Search products on the Clas Ohlson Finland webshop (clasohlson.com/fi/). This skill uses the Voyado Elevate (Apptus eSales) search API directly, requiring no browser. Use when the user asks to "search Clas Ohlson", "find products on clasohlson.com", "clas ohlson product search", "check Clas Ohlson prices", or mentions searching the Finnish Clas Ohlson store.
akaihola/skills-akaihola
bauhaus
Search products on the Bauhaus webshop (bauhaus.fi). This skill uses the Algolia search API with automatic key refresh. Use when the user asks to "search Bauhaus", "find products on bauhaus.fi", "bauhaus product search", "check Bauhaus prices", or mentions searching the Bauhaus store.
akaihola/skills-akaihola
library
Didn't find tool you were looking for?