Qmd
Index local markdown collections and run fast BM25 (or optional semantic) search so your agent can pull the right note or doc from your knowledge base.
Overview
qmd is an agent skill most often used in Build (also Idea research and Operate iterate) that indexes local markdown and retrieves documents via fast BM25 or optional semantic search.
Install
npx skills add https://github.com/levineam/qmd-skill --skill qmdWhat is this skill?
- Local hybrid search over markdown via global `qmd` CLI (Bun install)
- Default to `qmd search` (BM25) for instant keyword hits; `vsearch` only when keywords fail
- Avoid `qmd query` unless user accepts slow hybrid quality on cold starts
- Collection setup: `qmd collection add` with glob mask and optional `qmd context add`
- Explicit trigger phrases for “search my notes / docs / knowledge base”
- Requires Bun >= 1.0.0 per skill metadata
- Three search modes documented: search (BM25), vsearch, query (hybrid)
Adoption & trust: 907 installs on skills.sh; 692 GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your specs and notes are scattered across markdown folders and the agent cannot reliably find the right file without slow grep or guessing paths.
Who is it for?
Builders who keep product context in markdown git repos or Obsidian-style trees and want the agent to search those corpora offline.
Skip if: Teams that need enterprise-wide Confluence/Notion search, real-time collaborative editing search, or search over non-markdown binary assets without conversion.
When should I use this skill?
Use when searching notes, finding related content, or retrieving documents from indexed markdown collections (trigger: search my notes/docs/knowledge base).
What do I get? / Deliverables
Indexed collections return targeted markdown snippets through `qmd search` (or `vsearch`/`query` when appropriate) so answers cite your local knowledge base.
- Configured qmd collections with masks and optional context descriptions
- Ranked markdown search results from agent-invoked `qmd search` or `vsearch`
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Most builders attach qmd to markdown they maintain while building—canonical shelf is Build/docs because indexed collections are usually project notes, specs, and runbooks. Docs subphase fits retrieval over markdown knowledge bases the solo builder curates alongside the product, not a hosted SaaS search product.
Where it fits
Search indexed competitor writeups and audience notes before committing to a product direction.
Retrieve the latest architecture markdown from your `qmd://notes` collection while implementing a feature.
Look up prior incident runbooks in markdown when debugging production issues.
How it compares
Use instead of ripgrep-only exploration when you want persistent indexed collections and ranked retrieval across many markdown trees.
Common Questions / FAQ
Who is qmd for?
Solo and indie builders who maintain markdown notes or docs locally and want Claude Code, Cursor, or Codex agents to query those collections with the qmd CLI.
When should I use qmd?
Use it during Idea research to scan competitor notes, during Build/docs when pulling specs or ADRs, and during Operate/iterate when searching runbooks—especially when you say “search my notes” or “find related markdown.”
Is qmd safe to install?
Check the Security Audits panel on this Prism page; installation runs Bun global install from GitHub and the tool only reads paths you explicitly add as collections on your machine.
SKILL.md
READMESKILL.md - Qmd
# qmd - Quick Markdown Search Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. ## When to use (trigger phrases) - "search my notes / docs / knowledge base" - "find related notes" - "retrieve a markdown document from my collection" - "search local markdown files" ## Default behavior (important) - Prefer `qmd search` (BM25). It's typically instant and should be the default. - Use `qmd vsearch` only when keyword search fails and you need semantic similarity (can be very slow on a cold start). - Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes/timeouts. ## Prerequisites - Bun >= 1.0.0 - macOS: `brew install sqlite` (SQLite extensions) - Ensure PATH includes: `$HOME/.bun/bin` Install Bun (macOS): `brew install oven-sh/bun/bun` ## Install `bun install -g https://github.com/tobi/qmd` ## Setup ```bash qmd collection add /path/to/notes --name notes --mask "**/*.md" qmd context add qmd://notes "Description of this collection" # optional qmd embed # one-time to enable vector + hybrid search ``` ## What it indexes - Intended for Markdown collections (commonly `**/*.md`). - In our testing, "messy" Markdown is fine: chunking is content-based (roughly a few hundred tokens per chunk), not strict heading/structure based. - Not a replacement for code search; use code search tools for repositories/source trees. ## Search modes - `qmd search` (default): fast keyword match (BM25) - `qmd vsearch` (last resort): semantic similarity (vector). Often slow due to local LLM work before the vector lookup. - `qmd query` (generally skip): hybrid search + LLM reranking. Often slower than `vsearch` and may timeout. ## Performance notes - `qmd search` is typically instant. - `qmd vsearch` can be ~1 minute on some machines because query expansion may load a local model (e.g., Qwen3-1.7B) into memory per run; the vector lookup itself is usually fast. - `qmd query` adds LLM reranking on top of `vsearch`, so it can be even slower and less reliable for interactive use. - If you need repeated semantic searches, consider keeping the process/model warm (e.g., a long-lived qmd/MCP server mode if available in your setup) rather than invoking a cold-start LLM each time. ## Common commands ```bash qmd search "query" # default qmd vsearch "query" qmd query "query" qmd search "query" -c notes # Search specific collection qmd search "query" -n 10 # More results qmd search "query" --json # JSON output qmd search "query" --all --files --min-score 0.3 ``` ## Useful options - `-n <num>`: number of results - `-c, --collection <name>`: restrict to a collection - `--all --min-score <num>`: return all matches above a threshold - `--json` / `--files`: agent-friendly output formats - `--full`: return full document content ## Retrieve ```bash qmd get "path/to/file.md" # Full document qmd get "#docid" # By ID from search results qmd multi-get "journals/2025-05*.md" qmd multi-get "doc1.md, doc2.md, #abc123" --json ``` ## Maintenance ```bash qmd status # Index health qmd update # Re-index changed files qmd embed # Update embeddings ``` ## Keeping the index fresh Automate indexing so results stay current as you add/edit notes. - For keyword search (`qmd search`), `qmd update` is usually enough (fast). - If you rely on semantic/hybrid search (`vsearch`/`query`), you may also want `qmd emb