qmd
- Repo stars 39
- Author updated Live
- Author repo awesome-omni-skill
- Domain
- AI
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @diegosouzapw · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Bun
- Permissions
-
- Read-only
- Write / modify
- Env read
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: qmd
description: Fast local search for markdown files, notes, and docs using qmd CLI. Combines BM25 full-text sea…
category: ai
runtime: Bun
---
# qmd output preview
## PART A: Task fit
- Use case: Fast local search for markdown files, notes, and docs using qmd CLI. Combines BM25 full-text search, vector semantic search, and LLM reranking — all running locally. No API keys needed..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Installation / Setup / When to Use” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Fast local search for markdown files, notes, and docs using qmd CLI. Combines BM25 full-text search, vector semantic search, and LLM reranking — all running locally. No API keys needed.”.
- **02** When the source has headings, the agent prioritizes “Installation / Setup / When to Use” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, read environment variables; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, read environment variables; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/path`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, read environment variables.
Start with a small task and check whether the result follows “Installation / Setup / When to Use”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: qmd
description: Fast local search for markdown files, notes, and docs using qmd CLI. Combines BM25 full-text sea…
category: ai
source: diegosouzapw/awesome-omni-skill
---
# qmd
## When to use
- Fast local search for markdown files, notes, and docs using qmd CLI. Combines BM25 full-text search, vector semantic s…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Installation / Setup / When to Use” and keep inference separate from source facts.
- read files, write/modify files, read environment variables; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "qmd" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Installation / Setup / When to Use
rules -> SKILL.md triggers / order / output contract
runtime -> Bun | read files, write/modify files, read environment variables | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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
findto 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 vsearchonly when keyword search fails and you need semantic similarity. - Avoid
qmd queryunless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes. - Always use
--jsonflag 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 searchis typically instant.qmd vsearchcan take ~1 minute on first run (loads local LLM).qmd queryadds 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_HOMEenvironment variable.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review