dotfiles/pi/.pi/agent/skills/qmd/SKILL.md

name, description, license, compatibility, metadata, allowed-tools

name	description	license	compatibility	metadata	allowed-tools
qmd	Search markdown knowledge bases, notes, and documentation using the qmd CLI. Use when searching notes, finding documents, or looking up information in the knowledge base.	MIT	Requires qmd CLI. Install via `npm install -g @tobilu/qmd`.	author version tobi 2.0.0	Bash(qmd:*)

QMD - Quick Markdown Search

Local search engine for markdown content. Use via the qmd CLI (bash).

Status

!qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"

CLI Usage

qmd query "question"                        # Auto-expand + rerank (recommended)
qmd query $'lex: X\nvec: Y'                 # Structured query document
qmd query $'expand: question'              # Explicit expand
qmd search "keywords"                       # BM25 only (no LLM)
qmd get "path/to/file.md"                   # Retrieve a document by path
qmd get "#abc123"                           # Retrieve by docid
qmd get "path/to/file.md:100" -l 50         # Retrieve starting at line 100, 50 lines
qmd multi-get "journals/2026-*.md" -l 40    # Batch fetch by glob
qmd multi-get notes/foo.md,notes/bar.md     # Comma-separated list

Query Types

Type	Method	Input
lex	BM25	Keywords — exact terms, names, code
vec	Vector	Question — natural language
hyde	Vector	Answer — hypothetical result (50-100 words)

Writing Good Queries

lex (keyword)

• 2-5 terms, no filler words
• Exact phrase: "connection pool" (quoted)
• Exclude terms: performance -sports (minus prefix)
• Code identifiers work: handleError async

vec (semantic)

• Full natural language question
• Be specific: "how does the rate limiter handle burst traffic"

hyde (hypothetical document)

• Write 50-100 words of what the answer looks like
• Use the vocabulary you expect in the result

expand (auto-expand)

• Single-line query (implicit) or expand: question
• Lets a local LLM generate lex/vec/hyde variations
• Do not mix with other typed lines

Combining Types

Goal	Approach
Know exact terms	lex only
Don't know vocabulary	Single-line (implicit expand) or vec
Best recall	lex + vec
Complex topic	lex + vec + hyde

First query gets 2x weight — put your strongest signal first.

Lex Syntax

Syntax	Meaning	Example
term	Prefix match	perf matches "performance"
"phrase"	Exact phrase	"rate limiter"
-term	Exclude	performance -sports

Collection Filtering

qmd query --collections docs "question"
qmd query --collections docs,notes "question"

Omit to search all collections.