Qmd

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

Security Scan

The skill's instructions match its stated purpose (search local markdown with the qmd tool) but it asks the agent to install and run an external npm package and to modify agent/daemon configuration files (e.g., OpenClaw/Claude MCP settings), which is more intrusive than the skill metadata indicates.

Purpose & Capability

The SKILL.md consistently documents using the qmd CLI / MCP server to search markdown collections, which aligns with the skill name and description. However, the registry metadata declares no required binaries or install steps while the instructions clearly expect a qmd CLI (npm package @tobilu/qmd) and optionally running an MCP server — a minor mismatch between metadata and runtime expectations.

Instruction Scope

Runtime instructions instruct the agent/user to add local directories as collections (e.g., qmd collection add ~/notes) which requires reading local files (expected for a search tool). More importantly, the references explicitly show edits to client config files (~/.claude/settings.json, ~/Library/... , ~/.openclaw/openclaw.json) to register an MCP server. That involves modifying other agent/application configuration and enabling a local HTTP daemon (qmd mcp --http), which increases the skill's scope beyond simple search.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but SKILL.md recommends installing via npm install -g @tobilu/qmd. Installing a third-party npm package globally is a common but potentially risky action — the package and its provenance should be verified before installing. No direct download URLs or obfuscated installs are present.

Credentials

The skill does not request environment variables, credentials, or config paths in the registry metadata. The instructions do reference user-local paths (home directories) when adding collections and show how to configure MCP servers, but they do not ask for unrelated credentials or secrets.

Persistence & Privilege

The skill does not request always:true, but the docs recommend registering qmd as an MCP server in the agent/client configuration (e.g., ~/.openclaw/openclaw.json). That is a change to the agent's configuration/behavior and effectively grants persistent integration (and potentially autonomous access to local files via the qmd daemon). Users should be aware this modifies agent settings beyond the skill's own isolated files.

What to consider before installing

This skill appears to do what it says (search local markdown) but you should be cautious before installing or enabling it: 1) Verify the npm package (@tobilu/qmd) and its source code/reputation before running npm install -g; prefer reviewing the package on npm/GitHub or installing in a sandbox/container. 2) Be aware qmd will read whatever directories you add as collections — only add directories you trust and avoid system or secrets-containing paths. 3) The references suggest adding qmd as an MCP server in agent configs (e.g., ~/.openclaw/openclaw.json); back up those config files before modifying them and understand that this grants the tool persistent integration with your agent. 4) If you will run qmd mcp --http (daemon), consider firewall/port controls (default 8181) and whether you want a local HTTP endpoint. 5) If you need lower risk, keep the skill instruction-only (do not modify agent config) and run qmd manually in a controlled environment. If you want this skill, validate the package and its behavior first; the metadata omission of the expected qmd binary is a small inconsistency but not necessarily malicious.

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

{
  "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:

{
  "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

{ "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

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

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

Setup

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