qmd

Search local markdown notes and docs using BM25, vector, and hybrid retrieval modes.

1|Updated May 6, 2026
One-click install
npx skills add https://github.com/surfingalien/FinSurfing --skill qmd-surfingalien
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: qmd
Source: https://github.com/surfingalien/FinSurfing/tree/main/.claude/skills/qmd
Command: npx skills add https://github.com/surfingalien/FinSurfing --skill qmd-surfingalien

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Finding information across large collections of local markdown notes and documentation is slow and unreliable with basic file search, especially when you need semantic similarity or ranked relevance. ## Core Features & Use Cases - Fast Keyword Search: Run BM25-ranked searches across indexed markdown collections with score thresholds, result limits, and JSON output. - Semantic and Hybrid Search: Use vector search for conceptual similarity or hybrid mode with LLM reranking for the highest-quality results. - Document Retrieval: Fetch full documents by path, ID, or glob pattern, and maintain index health with status, update, and embed commands. - Use Case: You have a knowledge base of 2,000 markdown notes and need to find every note mentioning a specific project deadline — run a scoped BM25 search against your notes collection and retrieve the matching documents instantly. ## Quick Start Search my indexed markdown notes for "quarterly review deadlines" and show me the top five matching documents.

Frequently Asked Questions about qmd

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search my local markdown notes from the command line?

Use qmd search followed by your query to run a BM25 keyword search across indexed markdown collections. Add -c to restrict to one collection, -n to limit results, or --json for machine-readable output.

What is the difference between qmd search, vsearch, and query?

qmd search uses BM25 keyword matching and is typically instant. qmd vsearch adds semantic vector similarity but can take about a minute on cold start, while qmd query adds LLM reranking on top and is the slowest option.

How do I set up qmd for a new notes folder?

Install qmd with bun install -g from its GitHub repo, then run qmd collection add with your notes path and a **/*.md mask. Run qmd embed once to enable vector and hybrid search, and verify with qmd status.

Why are my new markdown files not appearing in qmd search results?

New or modified files are missing because the index has not been refreshed. Run qmd status to check index health, then qmd update to re-index changed files, or remove and re-add the collection for a full rebuild.

Why is qmd search slow or timing out on large vaults?

qmd query and vsearch are slow on large vaults because they load a local LLM for expansion and reranking. Use qmd search instead, limit results with -n, or scope the search to a single collection with -c.