Qmd (1)

**Judgement:** Qmd is a strong, purpose-built tool for agent-accessible search over local Markdown notes and docs, with robust keyword search and optional semantic/hybrid modes. It’s a good fit when the user already has (or is willing to set up) a qmd index for their files and wants the agent to leverage their personal knowledge base. **Recommended scenarios** - Use **qmd search** by default whenever the user asks to **“search my notes/docs/knowledge base”**, **“find related notes”**, or **“search local markdown files”**. - Use **collection filters** (e.g., `-c notes`) when the user mentions a specific notebook, workspace, or collection. - Use **qmd get / multi-get** when the user wants a **specific document** by name, path, or ID from prior search results. - Reserve **qmd vsearch** for cases where keyword search fails but semantic similarity is clearly needed and the user can tolerate a noticeable delay. - Avoid **qmd query** unless the user explicitly requests the **highest-quality hybrid results** and understands it may be slow or prone to timeouts. **Key benefits** - Fast, local BM25 search for Markdown content, usually instant and well-suited to interactive agent use. - Reasonable semantic/hybrid options (vsearch/query) for more nuanced matches when exact keywords are not enough. - Direct document retrieval capabilities that let the agent ingest longer references from the user’s own files. - Local-only indexing and GGUF models, which generally keeps user data on their machine. **Risks & limitations** - **Environment setup required:** Needs Bun, SQLite extensions (on macOS), and qmd installed; missing prerequisites will cause skill failures. - **Index dependency:** The tool is only useful if the user has added collections (`qmd collection add`) and keeps them updated (`qmd update`, optionally `qmd embed`). Stale or missing indexes will yield incomplete or confusing results. - **Performance pitfalls:** - `qmd search` is fast, but `qmd vsearch` may take ~1 minute on a cold start (local model loading) and `qmd query` can be even slower. - Long-running semantic/hybrid calls risk timeouts in interactive agent sessions. - **Scope limitations:** Designed for **Markdown documents**, not for full code search; using it on large source trees is likely suboptimal. - **Privacy handling:** While data stays local, the agent may pull sensitive content into its context and reasoning. Agents should avoid over-fetching and only retrieve what’s relevant to the user’s request. **Overall:** Use this skill when the user explicitly wants the agent to work with their local Markdown-based notes/docs and they have (or will set up) qmd collections. Default to fast keyword search, escalate to semantic search only when necessary, and treat hybrid query as an advanced, high-latency option.