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>

Fast, accurate keyword-based search. Best for specific terms or phrases.

Vector Search (semantic)

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

Semantic similarity search. Best for conceptual queries where exact words may vary.

Hybrid Search (both + reranking)

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

Combines both approaches with LLM reranking. Most thorough but often overkill.

How to Use

1. Check if collection exists: bash qmd collection list

2. Search the collection: ```bash

   For specific terms

   qmd search "api authentication" --collection notes

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

1. 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 <name> is specified, use that collection; otherwise default to checking available collections

Workflow

1. Parse arguments from $ARGUMENTS

2. Check if qmd is installed (which qmd)

3. If not installed, offer to guide setup

4. If searching:

   • List collections if none specified
   • Run appropriate search command
   • Present results to user with file paths

5. If user wants to read a specific result, use the Read tool on the file path