qmd-search
This skill should be used to search the local Obsidian vault / markdown knowledge base by meaning, not just keywords, using the on-device qmd engine (BM25 + vector + LLM rerank). Trigger when the user asks to "search my vault/notes", "find notes about X", "what do my notes say about Y", "do I have anything on Z", "semantic search my knowledge base", or wants concept/cross-lingual retrieval over markdown. Fully local — nothing leaves the machine.
How do I install this agent skill?
npx skills add https://github.com/glebis/claude-skills --skill qmd-searchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides semantic and keyword search over a local markdown vault. It automatically downloads required AI models on first use (~318 MB) and processes file content, which presents a standard indirect prompt injection surface inherent to search and retrieval tools.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
qmd Search
Search a local markdown knowledge base semantically with qmd. Five
modes — BM25 keywords, vector similarity, hybrid (expansion + rerank), literal native-script grep,
and a fused find — all running on-device. The key advantage over Obsidian's built-in search: it
matches meaning, finds notes that share no words with the query, and works across languages
(e.g. a Russian query retrieves English notes).
When to use which mode
- hybrid (
query) — default. A real question or fuzzy intent ("how do I stop overengineering"). Best quality; first run downloads reranker/expansion models (~one-time slow). - vector (
vsearch) — fast concept lookup ("notes about embodied computing"). - BM25 (
search) — an exact keyword, name, or filename. Instant, no model. - grep (
-m grep) — literal fixed-string ripgrep over the .md files. The audit path for proper nouns, transliterations, exact phrases, Russian stems/inflections, and absence checks. Bypasses the index; matches only the exact script/spelling you type.
Bilingual / proper-name rule (do not skip)
This vault is bilingual (English/Russian). The embedding model is decent for concepts but weak for proper nouns / specific entities, and BM25 only matches the script you type. So:
Never conclude "it's not in the vault" after one English semantic query. For names, people, pets, places, foreign terms, or bilingual topics:
- Search semantically first (
query/vsearch). - Generate likely native-script spellings/stems and try them, e.g.
Ziggy → Зигги/Зиги,dog/pet → собак, пёс, щенок, питомц, животн. Use stems (собакcatchesсобака/собаку/собаки), not just the nominative. - Run a literal pass before concluding absence:
qmd-search.sh -m grep -n 20 "Зигги". - Use literal hits to disambiguate close names (e.g.
Зиггиthe pet vs.ЗигмундFreud). - If everything fails, say "I didn't find it with these queries: …" and list the terms tried —
not "it's not in the vault." Raise
-nto ~20 for absence checks.
Primary usage — the wrapper
Use the bundled wrapper; it suppresses qmd's stderr spinner, formats results as score path
(parsing qmd's JSON, so commas in filenames are safe), and makes a best-effort refusal to run
during an active qmd embed (which would return empty results — override with --force):
~/.claude/skills/qmd-search/scripts/qmd-search.sh [-m query|search|vsearch|grep|find] [-n N] [-c COLLECTION] [--snippet] [--min-score X] [--json] [--full] <query...>
Examples:
qmd-search.sh "what helps with anxiety" # hybrid (default)
qmd-search.sh -m vsearch -n 8 "behavioral health from photos"
qmd-search.sh -m search sensorium # BM25 keyword
qmd-search.sh -m grep -n 20 "Зигги" # literal native-spelling / absence check
qmd-search.sh -m find "Зигги собака" # fused: semantic + literal in one call
qmd-search.sh --snippet "agent orchestration" # rows + matching snippets
qmd-search.sh --min-score 0.5 "quarterly planning" # drop low-relevance hits
qmd-search.sh --json "agent orchestration" # structured output for further processing
After getting hits, read the top files directly (they are normal vault paths) or fetch slices with
qmd get "<path>:<line>" -l <N>.
Setup / indexing (only if qmd status shows the vault is not indexed)
qmd collection add ~/Brains/brain --name brain # index the vault
qmd context add qmd://brain "short description of the vault"
qmd embed # build vectors; re-run until status shows 0 pending
qmd cleanup # compact the index
Refresh after large edits: qmd update && qmd embed. Check health any time with qmd status.
Operational rules (do not skip)
- One embed at a time, and never search while embedding — both cause empty/garbage results.
The wrapper guards searches; for manual
qmdcalls, checkqmd statusfirst. - If embedding never reaches 0 pending, check disk space (
df -h) — a full disk fails writes silently. Seereferences/cli-reference.md→ "Operational gotchas". - Vector scores are modest (~0.4–0.6); judge by ranking, not the absolute number.
MCP (native tools) vs. the CLI wrapper
qmd ships an MCP server (qmd mcp, stdio) exposing tools query, get, multi_get, status.
If it's registered in the host (e.g. .mcp.json), prefer the native query tool for hybrid
search — it returns structured results with no spinner/JSON-parsing/exit-code quirks. Register with:
{ "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }
Use the wrapper (scripts/qmd-search.sh) when you need what MCP doesn't cover: BM25-only
(search), vector-only (vsearch), the literal/native-script grep pass, the fused find
mode, --snippet, or --min-score. The bilingual/proper-name rule above applies to both paths.
Quality / evals
evals/fixture.example.json + scripts/run-evals.sh run qmd bench to score search quality
(precision/recall/MRR per backend). Baseline and interpretation: evals/BASELINE.md. Re-run after
changing the wrapper, the index, or the embedding model; a drop vs. baseline is a regression.
Reference
Full command surface, query grammar (lex:/vec:/hyde:), output formats, models, and recovery
steps are in references/cli-reference.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/glebis/claude-skills/qmd-search">View qmd-search on skillZs</a>