QMD Search Skill

Search markdown knowledge bases efficiently using qmd, a local indexing tool that uses BM25 + vector embeddings to return only relevant snippets instead of full files.

Why Use This

• 96% token reduction - Returns relevant snippets instead of reading entire files
• Instant results - Pre-indexed content means fast searches
• Local & private - All indexing and search happens locally
• Hybrid search - BM25 for keyword matching, vector search for semantic similarity

Commands

Search (BM25 keyword matching)

qmd search "your query" --collection <name>

Vector Search (semantic)

qmd vsearch "your query" --collection <name>

Hybrid Search (both + reranking)

qmd hybrid "your query" --collection <name>

How to Use

• Check if collection exists:

qmd collection list

• Search the collection:

# For specific terms
   qmd search "api authentication" --collection notes

   # For conceptual queries
   qmd vsearch "how to handle errors gracefully" --collection notes

• Read results: qmd returns relevant snippets with file paths and context

Setup (if qmd not installed)

# Install qmd
bun install -g https://github.com/tobi/qmd

# Add a collection (e.g., Obsidian vault)
qmd collection add ~/path/to/vault --name notes

# Generate embeddings for vector search
qmd embed --collection notes

Invocation Examples

/qmd api authentication          # BM25 search for "api authentication"
/qmd how to handle errors --semantic   # Vector search for conceptual query
/qmd --setup                     # Guide through initial setup

Best Practices

• Use BM25 search (qmd search) for specific terms, names, or technical keywords
• Use vector search (qmd vsearch) when looking for concepts where wording may vary
• Avoid hybrid search unless you need maximum recall - it's slower
• Re-run qmd embed after adding significant new content to keep vectors current

Handling Arguments

• $ARGUMENTS contains the full search query
• If --semantic flag is present, use qmd vsearch instead of qmd search
• If --setup flag is present, guide user through installation and collection setup
• If --collection is specified, use that collection; otherwise default to checking available collections

Workflow

• Parse arguments from $ARGUMENTS
• Check if qmd is installed (which qmd)
• If not installed, offer to guide setup
• If searching:
• List collections if none specified
• Run appropriate search command
• Present results to user with file paths
• If user wants to read a specific result, use the Read tool on the file path