# Qmd

> |

- **Type:** Skill
- **Install:** `agentstack add skill-changeflowhq-skills-qmd`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [changeflowhq](https://agentstack.voostack.com/s/changeflowhq)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [changeflowhq](https://github.com/changeflowhq)
- **Source:** https://github.com/changeflowhq/skills/tree/master/skills/qmd

## Install

```sh
agentstack add skill-changeflowhq-skills-qmd
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# qmd - Local Search for Knowledge Bases

Search indexed markdown collections using keyword, semantic, or hybrid search.

## When to Use

- Searching project documentation or knowledge bases
- Finding related files before making changes
- Discovering context across many markdown files
- Answering questions that span multiple documents

## Quick Start

```bash
# Keyword search (fast, BM25)
qmd search "your query" --json -n 10

# Find related files
qmd search "topic" --files -n 20

# Semantic search (requires embeddings)
qmd vsearch "conceptual question" -n 10

# Hybrid search with reranking (best quality, slower)
qmd query "natural language question" --json -n 10

# Get full document content
qmd get "path/to/file.md" --full
```

## Search Modes

| Mode | Command | Speed | Best For |
|------|---------|-------|----------|
| Keyword (BM25) | `qmd search` | Fast | Exact terms, known keywords |
| Semantic | `qmd vsearch` | Medium | Conceptual queries, synonyms |
| Hybrid | `qmd query` | Slow | Complex questions needing both |
| File list | `qmd search --files` | Fast | Finding all related files |

## Workflows

### Before answering a question
```bash
qmd search "relevant keywords" --json -n 10
```
Review results, then read specific files for full context.

### After making changes (update cascade)
```bash
qmd search "topic you changed" --files -n 20
```
Review all related files and update any that reference the changed topic.

### Writing content that needs project context
```bash
qmd search "positioning voice tone" --json -n 10
qmd search "topic for content" --json -n 10
```

## Index Management

```bash
# Update text index (fast, ~1 sec)
qmd update

# Update embeddings (slow, ~3-4 min)
qmd embed

# Check index health
qmd status

# List collections
qmd collection list
```

## Setup & Troubleshooting

If qmd is not installed or broken, run the doctor script:

```bash
bash ~/.claude/skills/qmd/scripts/doctor.sh
```

For full installation and automation setup, see [setup/README.md](setup/README.md).

For the complete command reference, see [references/commands.md](references/commands.md).

## Tips

- Results below score 0.3 are noise - ignore them
- `qmd search` (BM25) is good enough for day-to-day use
- Only use `vsearch` when keywords don't match concepts
- After changes, always run `--files` query to catch ripple effects
- Combine with Read tool: qmd finds files, Read gets full content

## Self-Learning

Read [LEARNED.md](LEARNED.md) before using this skill. It contains hard-won lessons about what works and what doesn't.

**Update LEARNED.md when you discover:**
- A query that returned bad results and what worked instead
- Search mode choice that was wrong (e.g. `search` missed something `vsearch` found)
- Index issues (stale embeddings, missing files, broken binary)
- Installation or automation gotchas
- CLAUDE.md patterns that worked or failed for enforcing context-first behavior

**Consolidation (keep LEARNED.md under 50 lines):**
Before adding a new entry, check the file length. If it's over 50 lines:
1. Merge duplicate/overlapping entries into single proven patterns
2. Remove entries older than 3 months that haven't been reinforced
3. Drop one-off observations that never recurred
4. Move detailed historical context to `LEARNED-archive.md` if worth preserving
5. Keep only entries that would change behavior - if it's obvious, cut it

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [changeflowhq](https://github.com/changeflowhq)
- **Source:** [changeflowhq/skills](https://github.com/changeflowhq/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-changeflowhq-skills-qmd
- Seller: https://agentstack.voostack.com/s/changeflowhq
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.