Agent skill

qmd

Search markdown knowledge bases, notes, and documentation using QMD. Use when users ask to search notes, find documents, or look up information.

View SKILL.md on GitHub Repository

Stars 21,093

Forks 1,294

Install this agent skill to your Project

npx add-skill https://github.com/tobi/qmd/tree/main/skills/qmd

Metadata

Additional technical details for this skill

author: tobi
version: 2.0.0

SKILL.md

QMD - Quick Markdown Search

Local search engine for markdown content.

Status

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

MCP: `query`

json

{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}

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"
Include context: "in the payment service, how are refunds processed"

hyde (hypothetical document)

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

expand (auto-expand)

Use a single-line query (implicit) or expand: question on its own line
Lets the local LLM generate lex/vec/hyde variations
Do not mix expand: with other typed lines — it's either a standalone expand query or a full query document

Intent (Disambiguation)

When a query term is ambiguous, add intent to steer results:

json

{
  "searches": [
    { "type": "lex", "query": "performance" }
  ],
  "intent": "web page load times and Core Web Vitals"
}

Intent affects expansion, reranking, chunk selection, and snippet extraction. It does not search on its own — it's a steering signal that disambiguates queries like "performance" (web-perf vs team health vs fitness).

Combining Types

Goal	Approach
Know exact terms	`lex` only
Don't know vocabulary	Use a single-line query (implicit `expand:`) or `vec`
Best recall	`lex` + `vec`
Complex topic	`lex` + `vec` + `hyde`
Ambiguous query	Add `intent` to any combination above

First query gets 2x weight in fusion — put your best guess first.

Lex Query Syntax

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

Note: -term only works in lex queries, not vec/hyde.

Collection Filtering

json

{ "collections": ["docs"] }              // Single
{ "collections": ["docs", "notes"] }     // Multiple (OR)

Omit to search all collections.

Other MCP Tools

Tool	Use
`get`	Retrieve doc by path or `#docid`
`multi_get`	Retrieve multiple by glob/list
`status`	Collections and health

CLI

bash

qmd query "question"              # Auto-expand + rerank
qmd query $'lex: X\nvec: Y'       # Structured
qmd query $'expand: question'     # Explicit expand
qmd query --json --explain "q"    # Show score traces (RRF + rerank blend)
qmd search "keywords"             # BM25 only (no LLM)
qmd get "#abc123"                 # By docid
qmd multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
qmd multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order

HTTP API

bash

curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'

Setup

bash

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

Maintainer

tobi Core maintainer

Source details

Full Name: tobi/qmd
Branch: main
Path in repo: skills/qmd
License: MIT License

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

release

Manage releases for this project. Validates changelog, installs git hooks, and cuts releases. Use when user says "/release", "release 1.0.5", "cut a release", or asks about the release process. NOT auto-invoked by the model.

install-duckdb

imsa

Query the IMSA DuckDB dataset (output/imsa.duckdb). Includes schema guidance for seasons and laps plus formatting macros. Use for analytics, session lookups, and lap-level queries.

query

Run SQL queries against the attached DuckDB database or ad-hoc against files. Accepts raw SQL or natural language questions. Uses DuckDB Friendly SQL idioms.

attach-db

Attach a DuckDB database file for use with /duckdb-skills:query. Explores the schema (tables, columns, row counts) and writes a SQL state file so subsequent queries can restore this session automatically via duckdb -init.

read-file

Read and explore any data file (CSV, JSON, Parquet, Avro, Excel, spatial, …) locally or remotely (S3, HTTPS). Resolves the path automatically. Uses DuckDB with extension-based format detection — no magic extension needed.

Didn't find tool you were looking for?