QMD Markdown Search

Search and retrieve markdown documents from local knowledge bases using qmd. Supports BM25 keyword search, vector semantic search, and hybrid search with LLM...

Security Scan

The skill's instructions look like a straight qmd CLI helper, but the package metadata and SKILL.md disagree about required installs and likely needed API keys, so the bundle is internally inconsistent and needs clarification before trusting it.

Purpose & Capability

The SKILL.md clearly requires the qmd CLI (installation via `bun install -g https://github.com/tobi/qmd`) and describes indexing local markdown; however the skill metadata lists no required binaries or install steps. That mismatch (skill claiming no requirements while instructing installation of a CLI) is unexpected. Also the included _meta.json content (different ownerId/slug/version) doesn't match the registry metadata, which is another inconsistency.

Instruction Scope

Instructions are mostly limited to running qmd commands and indexing local markdown (which matches the stated purpose). However the SKILL.md requires generating embeddings and using an LLM for `query`/re-ranking but does not declare any environment variables or credentials for embedding/LLM providers. This omission creates ambiguity about what secrets or external services the tool will call when you run it.

Install Mechanism

This is an instruction-only skill (no code files), so no install spec in the registry—but the SKILL.md tells users/agent to run `bun install -g https://github.com/tobi/qmd`, which downloads and globally installs code from a GitHub repo via bun. That is a direct repository install (no checksum or pinned release), and it assumes bun is present; both are moderate risk and should be documented or replaced with a stable release mechanism.

Credentials

The skill declares no required environment variables, yet its workflow (embedding generation and LLM re-ranking) commonly requires provider API keys (e.g., OpenAI or other embedding/model credentials). The absence of declared env vars is disproportionate to the described functionality and leaves unanswered where embeddings/LLM calls will go and which secrets are needed.

Persistence & Privilege

The skill does not request always:true and does not declare config paths or other persistent privileges. It mentions qmd's optional MCP server (which would expose local endpoints), but running that server is an action of the qmd tool, not this skill's metadata—still, users should be aware that enabling the MCP server exposes services on the local machine.

What to consider before installing

This appears to be a useful helper for the qmd CLI, but there are several inconsistencies you should resolve before installing: 1) SKILL.md expects you to install qmd via bun, but the skill metadata doesn't list any required binaries—confirm whether you need bun and qmd and whether you trust that GitHub repo. 2) The instructions mention generating embeddings and LLM-based queries but declare no API keys—ask which model/embedding provider qmd will use and whether you must supply credentials (e.g., OPENAI_API_KEY). 3) The included _meta.json values differ from the registry metadata (owner/slug/version); request clarification from the publisher. If you proceed, prefer installing qmd from a pinned release tag or official distribution, audit the qmd repo if possible, and be cautious about running the optional MCP server (it exposes a local API that could be reachable by other local processes).

QMD - Local Markdown Search

Search and retrieve documents from locally indexed markdown knowledge bases.

Installation

bun install -g https://github.com/tobi/qmd

Setup

# Add a collection
qmd collection add ~/notes --name notes --mask "**/*.md"

# Generate embeddings (required for vsearch/query)
qmd embed

Usage Rules

Always use --json flag for structured output when invoking qmd commands.

Search Commands

search (BM25 keyword search - fast)

qmd search "authentication flow" --json
qmd search "error handling" --json -n 10
qmd search "config" --json -c notes

vsearch (vector semantic search)

qmd vsearch "how does login work" --json
qmd vsearch "authentication best practices" --json -n 20

query (hybrid with LLM re-ranking - best quality)

qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5

Search Options

Option	Description
-n NUM	Number of results (default: 5, or 20 with --json)
-c, --collection NAME	Restrict to specific collection
--min-score NUM	Minimum score threshold
--full	Return complete document content in results
--all	Return all matches

Retrieval Commands

get (single document)

qmd get docs/guide.md --json
qmd get "#a1b2c3" --json
qmd get notes/meeting.md:50 -l 100 --json

multi-get (multiple documents)

qmd multi-get "docs/*.md" --json
qmd multi-get "api.md, guide.md, #abc123" --json
qmd multi-get "notes/**/*.md" --json --max-bytes 20480

Maintenance Commands

qmd update              # Re-index changed files
qmd status              # Check index health
qmd collection list     # List all collections

Search Mode Selection

Mode	Speed	Quality	Best For
search	Fast	Good	Exact keywords, known terms
vsearch	Medium	Better	Conceptual queries, synonyms
query	Slow	Best	Complex questions, uncertain terms

Performance note: vsearch and query have ~1 minute cold start latency for vector initialization. Prefer search for interactive use.

MCP Server

qmd can run as an MCP server for direct integration:

qmd mcp

Exposes tools: qmd_search, qmd_vsearch, qmd_query, qmd_get, qmd_multi_get, qmd_status