How do I install the Qmd skill?

Run npx skillmds@latest add diegosouzapw/qmd in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

SkillMD's automated safety review verdict for this skill is CAUTION. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only, makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Qmd?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

diegosouzapw (@diegosouzapw) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Qmd by diegosouzapw — Agent Skill

Name: Qmd
Rating: 4.2 (5 reviews)
Author: diegosouzapw

File contents

qmd - Local Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. Use instead of find for file discovery across large directories.

Installation

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

Setup

# Add a collection
qmd collection add /path/to/your/notes --name notes --mask "**/*.md"

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

# List your collections
qmd collection list

When to Use

"search my notes / docs / knowledge base"
"find related notes"
"find files matching [pattern]" — use instead of find to avoid hangs on large directories
"what did we decide about X?"

Default Behavior (important)

Prefer qmd search (BM25) — it's instant and should be the default.
Use qmd vsearch only when keyword search fails and you need semantic similarity.
Avoid qmd query unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes.
Always use --json flag for structured output when invoking from an agent.

Search Commands

# Fast keyword search (default)
qmd search "authentication flow" --json
qmd search "config" --json -c notes

# Semantic search (slower, for conceptual queries)
qmd vsearch "how does login work" --json
qmd vsearch "best practices for error handling" --json -n 20

# Combined with reranking (best quality, slowest)
qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5

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

Search Options

Option	Description
`-n NUM`	Number of results (default: 5, 20 with --json)
`-c, --collection`	Scope to specific collection
`--min-score NUM`	Minimum score threshold
`--full`	Return complete document content
`--json`	Structured JSON output (agent-friendly)
`--files`	File paths only (fast discovery)
`--all`	Return all matches

Retrieve Documents

# Get full file
qmd get docs/guide.md --json

# Get by document hash ID
qmd get "#a1b2c3" --json

# Get specific lines
qmd get notes/meeting.md:50 -l 30 --json

# Get multiple files by glob
qmd multi-get "docs/*.md" --json
qmd multi-get "*.yaml" -l 50 --max-bytes 10240

Output Formats

--files — paths + scores (for file discovery)
--json — structured with snippets
--md — markdown formatted
-n 10 — limit results

Maintenance

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

Keeping Index Fresh

# Hourly incremental updates (BM25):
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update

# Optional: nightly embedding refresh:
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed

MCP Server

qmd can run as an MCP server for direct agent integration:

qmd mcp

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

Performance

qmd search is typically instant.
qmd vsearch can take ~1 minute on first run (loads local LLM).
qmd query adds LLM reranking — can be slow, avoid for interactive use.

Models (auto-downloaded)

All run locally — no API keys needed.

Embedding: embeddinggemma-300M
Reranking: qwen3-reranker-0.6b
Generation: Qwen3-0.6B
Cache location: ~/.cache/qmd/models/
Override with XDG_CACHE_HOME environment variable.

---name: qmddescription: Indexes and searches local Markdown notes and docs with BM25 keyword search, vector semantic search, and local LLM reranking, all running offline without API keys.---# qmd - Local Markdown SearchLocal search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. Use instead of `find` for file discovery across large directories.## Installation```bashbun install -g https://github.com/tobi/qmd```## Setup```bash# Add a collectionqmd collection add /path/to/your/notes --name notes --mask "**/*.md"# Generate embeddings (required for vsearch/query)qmd embed# List your collectionsqmd collection list```## When to Use- "search my notes / docs / knowledge base"- "find related notes"- "find files matching [pattern]" — use instead of `find` to avoid hangs on large directories- "what did we decide about X?"## Default Behavior (important)- Prefer `qmd search` (BM25) — it's instant and should be the default.- Use `qmd vsearch` only when keyword search fails and you need semantic similarity.- Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes.- **Always use `--json` flag** for structured output when invoking from an agent.## Search Commands```bash# Fast keyword search (default)qmd search "authentication flow" --jsonqmd search "config" --json -c notes# Semantic search (slower, for conceptual queries)qmd vsearch "how does login work" --jsonqmd vsearch "best practices for error handling" --json -n 20# Combined with reranking (best quality, slowest)qmd query "implementing user auth" --jsonqmd query "deployment process" --json --min-score 0.5```### 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 |### Search Options| Option | Description ||--------|-------------|| `-n NUM` | Number of results (default: 5, 20 with --json) || `-c, --collection` | Scope to specific collection || `--min-score NUM` | Minimum score threshold || `--full` | Return complete document content || `--json` | Structured JSON output (agent-friendly) || `--files` | File paths only (fast discovery) || `--all` | Return all matches |## Retrieve Documents```bash# Get full fileqmd get docs/guide.md --json# Get by document hash IDqmd get "#a1b2c3" --json# Get specific linesqmd get notes/meeting.md:50 -l 30 --json# Get multiple files by globqmd multi-get "docs/*.md" --jsonqmd multi-get "*.yaml" -l 50 --max-bytes 10240```## Output Formats- `--files` — paths + scores (for file discovery)- `--json` — structured with snippets- `--md` — markdown formatted- `-n 10` — limit results## Maintenance```bashqmd update # Re-index changed filesqmd status # Check index healthqmd collection list # List all collections```## Keeping Index Fresh```bash# Hourly incremental updates (BM25):0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update# Optional: nightly embedding refresh:0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed```## MCP Serverqmd can run as an MCP server for direct agent integration:```bashqmd mcp```Exposes tools: `qmd_search`, `qmd_vsearch`, `qmd_query`, `qmd_get`, `qmd_multi_get`, `qmd_status`## Performance- `qmd search` is typically instant.- `qmd vsearch` can take ~1 minute on first run (loads local LLM).- `qmd query` adds LLM reranking — can be slow, avoid for interactive use.## Models (auto-downloaded)All run locally — no API keys needed.- Embedding: embeddinggemma-300M- Reranking: qwen3-reranker-0.6b- Generation: Qwen3-0.6B- Cache location: `~/.cache/qmd/models/`- Override with `XDG_CACHE_HOME` environment variable.

Frequently asked questions

Qmd