qmd

name: qmd description: "Search local markdown knowledge bases, notes, docs, and wikis with QMD. Use when users ask to find notes, retrieve documents, inspect a wiki, answer from indexed markdown, or set up QMD access." license: MIT metadata: author: tobi version: "2.1.0" source: "https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md" compatibility: "Requires qmd CLI or MCP server. Install via `npm install -g @tobilu/qmd`." allowed-tools: "Bash(qmd:), mcpqmd"

QMD - Query Markdown Documents

How Search Works

QMD searches local markdown collections: notes, docs, wikis, transcripts, and project knowledge bases. Use it before web search when the answer may already be in indexed local files.

The workflow is always:

Search for candidate documents.
Retrieve the full source with qmd get or qmd multi-get.
Answer from retrieved text, citing paths or docids.

Fetch source documents before making factual claims, decisions, quotes, or nuanced summaries. Snippets are only leads.

Typical loop:

qmd search "merchant reality support interviews" -n 5
# leads: #abc123 concepts/customer-proximity.md; #def432 sources/merchant-call.md
qmd multi-get "#abc123,#def432" --md

For harder searches, use qmd query structured queries with intent:, lex:, vec:, and hyde: fields.

When reporting what you retrieved, a compact note is enough; paste whole files only when needed:

Retrieved:
- #abc123 concepts/customer-proximity.md
- #def432 sources/merchant-call.md

Pick The Right Search Mode

Use BM25 lexical search when you know exact words, titles, names, code symbols, or rare phrases:

qmd search "cockpit OKR Goodhart" -n 10
qmd search '"AI Before Headcount"' -c concepts -n 5

Use hybrid semantic search when the user describes an idea indirectly, uses different wording than the source, or needs conceptual recall:

qmd query "decision quality depends on surfacing assumptions and context" -n 10
qmd query --json --explain "metrics as cockpit instruments but not OKRs"

Use structured queries for hard searches. They combine exact anchors with semantic recall:

qmd query $'intent: Find the concept note about metrics as instruments without letting OKRs replace judgment.\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: A concept note says metrics are useful like cockpit instruments, but leaders should remain data-informed rather than metric-driven because OKRs and dashboards can Goodhart product judgment.'

Structured query fields:

intent: states what you are trying to find and what to avoid.
lex: uses exact terms, aliases, titles, and rare words.
vec: paraphrases the idea in natural language.
hyde: describes the document or answer that would satisfy the request.

If qmd query is slow or model/GPU setup fails, fall back to qmd search with better lexical terms.

Retrieve Sources

Search results include docids like #abc123 and qmd://... paths. Fetch them:

qmd get "#abc123"
qmd get qmd://concepts/ai-before-headcount.md --full
qmd multi-get "#abc123,#def432" --md
qmd multi-get 'concepts/{ai-before-headcount.md,data-informed-not-metric-driven.md}' --md
qmd multi-get 'sources/podcast-2025-*.md' -l 80

Use multi-get when comparing several hits or gathering context across pages. Use --full when the exact source matters.

Discover What Is Indexed

qmd collection list
qmd ls
qmd status

Add collection filters when broad searches drift into the wrong corpus:

qmd search "headcount autonomous agents" -c concepts -n 10
qmd query "merchant support product reality" -c concepts -c sources -n 10

Omit -c to search everything.

MCP Tool: `query`

When using the MCP server, prefer structured searches:

{
  "searches": [
    { "type": "lex", "query": "cockpit OKR Goodhart" },
    { "type": "vec", "query": "data informed not metric driven product judgment" },
    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
  ],
  "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
  "collections": ["concepts"],
  "limit": 10
}

Query types:

lex - BM25 keyword search. Best for exact terms, names, titles, and code.
vec - vector semantic search. Best for natural-language concepts.
hyde - vector search using a hypothetical answer/document passage.

Query Craft

Good QMD searches mix three things:

Title/alias anchors: exact page titles, named entities, phrases.
Semantic paraphrase: how a human would describe the idea.
Negative space: enough intent to avoid nearby-but-wrong concepts.

Examples:

# Exact-ish title lookup
qmd search '"arm the rebels" merchants tools big companies' -c concepts

# Semantic concept lookup
qmd query $'intent: Find the customer proximity concept, not generic customer delight.\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'

# Source lookup
qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10

Setup And Maintenance

Only mutate indexes when the user asked for setup or maintenance. Searching and retrieving are safe; collection/index mutation is an intentional maintenance step.

npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd update
qmd embed

Health and diagnostics:

qmd doctor
qmd status
qmd pull

qmd doctor checks config, model cache, device/GPU setup, vector fingerprints, and common environment overrides. If a model-backed command fails, run it before changing configuration.

MCP Setup

See references/mcp-setup.md for Claude Code, Claude Desktop, OpenClaw, and HTTP server configuration.

Rules

Fetch documents before making claims from search results.
Use BM25 when you know exact titles or terms; it is faster and often better.
Run qmd collection add, qmd update, and qmd embed only for setup or maintenance work requested by the user.
If qmd query, qmd vsearch, or reranking fails because local models/GPU are unavailable, use qmd search and stronger lexical/structured terms.
Add intent: for ambiguous user wording so the search targets the right domain.
Search concepts for synthesized wiki pages, sources for transcripts/raw source pages, and docs collections for code or project documentation.