home / skills / openclaw / skills / qmd-local-search

qmd-local-search skill

safe

This skill enables fast local markdown search with BM25 and vector reranking, helping you locate files, code, and docs offline.

npx playbooks add skill openclaw/skills --skill qmd-local-search

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.1 KB

---
name: qmd
description: Fast local search for markdown files, notes, and docs using qmd CLI. Use instead of `find` for file discovery. Combines BM25 full-text search, vector semantic search, and LLM reranking—all running locally. Use when searching for files, finding code, locating documentation, or discovering content in indexed collections.
---

# qmd — Fast Local Markdown Search

## When to Use

- **Finding files** — use instead of `find` across large directories (avoids hangs)
- **Searching notes/docs** — semantic or keyword search in indexed collections
- **Code discovery** — find implementations, configs, or patterns
- **Context gathering** — pull relevant snippets before answering questions

## Quick Reference

### Search (most common)

```bash
# Keyword search (BM25)
qmd search "alpaca API" -c projects

# Semantic search (understands meaning)
qmd vsearch "how to implement stop loss"

# Combined search with reranking (best quality)
qmd query "trading rules for breakouts"

# File paths only (fast discovery)
qmd search "config" --files -c kell

# Full document content
qmd search "pattern detection" --full --line-numbers
```

### Collections

```bash
# List collections
qmd collection list

# Add new collection
qmd collection add /path/to/folder --name myproject --mask "*.md,*.py"

# Re-index after changes
qmd update
```

### Get Files

```bash
# Get full file
qmd get myproject/README.md

# Get specific lines
qmd get myproject/config.py:50 -l 30

# Get multiple files by glob
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

## Tips

1. **Always use collections** (`-c name`) to scope searches
2. **Run `qmd update`** after adding new files
3. **Use `qmd embed`** to enable vector search (one-time, takes a few minutes)
4. **Prefer `qmd search --files`** over `find` for large directories

## Models (auto-downloaded)

- Embedding: embeddinggemma-300M
- Reranking: qwen3-reranker-0.6b
- Generation: Qwen3-0.6B

All run locally — no API keys needed.

Overview

This skill provides fast local search across markdown files, notes, code, and documentation using the qmd CLI. It replaces slow filesystem scans like find by combining BM25 keyword search, vector semantic search, and local LLM reranking for high-quality results. Everything runs locally—no external APIs or keys required.

How this skill works

qmd indexes specified folders into named collections and builds both text and vector embeddings. Searches can run as keyword (BM25), semantic (vector) or a combined query that reranks results with a small local LLM. Results can be returned as file paths, snippets, full documents, or structured JSON.

When to use it

Discover files quickly across large directories instead of using find
Search notes or documentation with semantic understanding
Locate code snippets, configs, or implementations inside projects
Gather contextual excerpts before answering or composing content
Index and query personal knowledge collections or project docs

Best practices

Scope searches with collections (-c) to improve relevance and speed
Run qmd update after adding or changing files to keep the index current
Enable embeddings once (qmd embed) to use vector semantic search
Prefer --files for fast path-only discovery when you only need locations
Use combined query (qmd query) when you want the highest-quality ranked results

Example use cases

Find every README or config file related to a feature across multiple repos using qmd search --files
Search a notes collection for conceptually similar items with qmd vsearch
Retrieve exact code lines or regions with qmd get path:line -l N
Re-index a project after commits to refresh searchable content with qmd update
Produce JSON-formatted search results for integration into other tools using --json

FAQ

Do I need an API key or internet access to use qmd?

No. All models and searches run locally; qmd auto-downloads required models and does not require external API keys.

How do I keep search results up to date after editing files?

Run qmd update to re-index changed files and ensure new content is searchable.

Which search mode should I pick: search, vsearch, or query?

Use search (BM25) for fast keyword matches, vsearch for semantic similarity, and query (combined + rerank) when you want best-quality answers.