# qmd

This skill wires an agent to qmd, a local search engine for markdown notes and docs. Index a folder once, then pull up matching files by keyword or meaning.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 953 installs · ★ 706
- Author: levineam
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/levineam/qmd-skill/tree/HEAD/SKILL.md
- Updated: 2026-02-25
- HTML: https://affpapa.org/en/nevibecode/skills/levineam-qmd

## What it does

qmd is a local search tool for markdown notes, docs and knowledge bases, and this skill teaches an agent how to drive it. You register a folder as a collection, run the indexer, and searches stay on your machine.

Keyword lookups go through `qmd search`, which is built on BM25 and usually returns right away. When keywords miss, `qmd vsearch` falls back to vector similarity — expect roughly a minute on a cold start, since a local model such as Qwen3-1.7B has to load first. The hybrid `qmd query` mode adds LLM reranking on top and the skill advises skipping it for interactive work: it runs longer and can time out. Agents get machine-readable output from `--json` and `--files`, and `qmd get` or `qmd multi-get` return whole documents.

Bun 1.0.0 or newer and the qmd binary are required, and `$HOME/.bun/bin` has to sit in `PATH` or the commands simply won't resolve. On macOS you also need `brew install sqlite` for the SQLite extensions. Vector and hybrid search stay off until you run `qmd embed` once, and you repeat it after edits. Models land in `~/.cache/qmd/models/`, which `XDG_CACHE_HOME` can move. Note the scope: this covers notes, not source trees — for code you want a code search tool.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add levineam/qmd-skill --skill qmd -a claude-code
```
```bash
npx skills add levineam/qmd-skill --skill levineam-qmd -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/levineam-qmd/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/levineam-qmd/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add levineam/qmd-skill --skill levineam-qmd -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/levineam-qmd/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add levineam/qmd-skill --skill levineam-qmd -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/levineam-qmd/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install levineam/qmd-skill levineam-qmd
```

2. **Manually: put the files in place**
- File: `.github/skills/levineam-qmd/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add levineam/qmd-skill --skill levineam-qmd -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/levineam/qmd-skill
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/levineam-qmd/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add levineam/qmd-skill --skill levineam-qmd -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/levineam/qmd-skill/tree/HEAD/SKILL.md

## When to use it
- locate a note from a half-remembered phrase
- surface related documents while working on something else
- pull the full text of a file straight from search results
- keep the markdown index current as notes change
- search local files without uploading them anywhere

## Example prompts
- Search my notes for anything about markdown indexing with qmd search
- Fetch the full document from those results using qmd get
- Refresh the notes index with qmd update

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

## Other versions with the same name
- [qmd · tobi](https://affpapa.org/en/nevibecode/skills/qmd.md) — 4100 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md