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

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 

# 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