Agent-Skills.md

Agent Skills: Vault Search Skill

Semantic search and Dataview-style queries across the Obsidian vault. Use when searching for notes by meaning, finding related content, querying frontmatter metadata, or answering questions about vault contents. Trigger phrases include "search vault", "find notes about", "what do I have on", "related notes", "list tasks", "show positions".

UncategorizedID: Roasbeef/obsidian-claude-code/vault-search
12211

Skill Files

Browse the full folder contents for vault-search.

Download Skill

Loading file tree…

skills/vault-search/SKILL.md

Skill Metadata

Name
vault-search
Description
Semantic search and Dataview-style queries across the Obsidian vault. Use when searching for notes by meaning, finding related content, querying frontmatter metadata, or answering questions about vault contents. Trigger phrases include "search vault", "find notes about", "what do I have on", "related notes", "list tasks", "show positions".

Vault Search Skill

Provides semantic search and SQL queries over the Obsidian vault using sqlite-vec for vector storage and ChromaDB's embedding function.

Python Environment

Interpreter: /Users/roasbeef/vault/.claude/venv/bin/python

Required packages:

  • sqlite-vec (vector search extension)
  • chromadb (embedding function only)

Database Location

Path: /Users/roasbeef/vault/.claude/vault_search/vault.db

Contains:

  • notes table: frontmatter metadata for all markdown files
  • vec_chunks table: vector embeddings for semantic search

Available Scripts

search.py - Semantic Search

Find notes by meaning using vector similarity.

# Basic semantic search
python scripts/search.py --query "options trading strategies" --n-results 5

# Filter by folder
python scripts/search.py --query "earnings analysis" --folder "investing"

# Filter by metadata
python scripts/search.py --query "task automation" --where "status='open'"

# Combined: semantic + metadata
python scripts/search.py --query "portfolio risk" --where "folder LIKE 'investing%' AND status='open'"

Arguments:

  • --query (required): Search query text
  • --n-results: Number of results (default: 5)
  • --folder: Filter by folder prefix
  • --where: SQL WHERE clause for metadata filtering
  • --db-path: Database path (default: .claude/vault_search/vault.db)

Output:

  • Human-readable results with snippets
  • JSON block for programmatic use

dataview.py - SQL Queries (Dataview Replacement)

Query frontmatter metadata using SQL.

# Open tasks due this week
python scripts/dataview.py --sql "SELECT path, due, priority FROM notes
                                   WHERE status = 'open'
                                   AND due < date('now', '+7 days')
                                   ORDER BY due"

# Tasks by folder
python scripts/dataview.py --sql "SELECT path, status, priority FROM notes
                                   WHERE folder LIKE 'TaskNotes%'
                                   AND status != 'done'"

# Investing positions
python scripts/dataview.py --sql "SELECT path, ticker, strategy, expiry FROM notes
                                   WHERE folder LIKE 'investing/Portfolio/Positions%'"

# Query by tags (using json_each)
python scripts/dataview.py --sql "SELECT DISTINCT n.path, n.title
                                   FROM notes n, json_each(n.tags) t
                                   WHERE t.value = 'automation'"

Arguments:

  • --sql (required): SQL query to execute
  • --db-path: Database path (default: .claude/vault_search/vault.db)
  • --format: Output format: "table" or "json" (default: table)

Available columns:

  • path, folder, filename, title, modified
  • Frontmatter: status, priority, due, scheduled, tags, projects, contexts
  • Investing: ticker, strategy, expiry

index.py - Build/Rebuild Index

Rebuild the search index from vault files.

# Full rebuild
python scripts/index.py --vault-path /Users/roasbeef/vault --rebuild

# Incremental update (default)
python scripts/index.py --vault-path /Users/roasbeef/vault

# Show statistics
python scripts/index.py --stats

Arguments:

  • --vault-path: Path to vault root (default: /Users/roasbeef/vault)
  • --db-path: Database path (default: .claude/vault_search/vault.db)
  • --rebuild: Force full rebuild
  • --stats: Show index statistics

When to Use This Skill

Use semantic search (search.py) when:

  • User asks to "find notes about X"
  • User wants "related notes" to a topic
  • Answering questions about vault contents
  • Exploring a topic across the vault

Use dataview queries (dataview.py) when:

  • User asks to "list tasks" or "show open tasks"
  • Filtering by specific metadata (status, due date, tags)
  • Aggregating or counting notes
  • Building dashboards or summaries

Use combined queries when:

  • "Find notes about X that are also open tasks"
  • "Show investing notes related to Y"

Example Usage

Find Related Notes

User: "What notes do I have about HTLC routing?"
→ python scripts/search.py --query "HTLC routing payment channels" --n-results 5

List Open Tasks

User: "Show my open high-priority tasks"
→ python scripts/dataview.py --sql "SELECT path, due FROM notes
                                     WHERE status='open' AND priority='high'
                                     ORDER BY due"

Combined Search

User: "Find investing notes about semiconductor supply chain"
→ python scripts/search.py --query "semiconductor supply chain"
                           --folder "investing"
                           --n-results 10

Rebuilding the Index

Use the /vault-index command to rebuild the index when:

  • Many files have changed
  • Search results seem stale
  • After bulk imports

Technical Details

  • Embeddings: ChromaDB DefaultEmbeddingFunction (ONNX MiniLM, 384 dims)
  • Storage: sqlite-vec virtual tables
  • Chunking: Split by markdown headings (v1)
  • Excluded folders: .obsidian, .smart-env, .claude, assets, Templates