qmd

AI Community

Repo stars 39
Author repo awesome-omni-skill

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Fast local search for markdown files, notes, and docs using qmd CLI. Combines BM25 full-text search, vector semantic search, and…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Installation”, “Setup”, “When to Use”, “Default Behavior (important)”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name qmd directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Installation / Setup / When to Use” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / env-read; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: AI
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 88 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @diegosouzapw · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: macOS · Linux · Windows
Runtime requirements: Bun
Detected file/system behavior: Read-only
Write / modify
Env read
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview qmd.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# 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

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

## Setup

```bash
# 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

```bash
# 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 |

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Installation → Setup → When to Use → Default Behavior (important) → Search Commands → Search Mode Selection
terms    -> Always use --json flag · Local search engine for Markdown notes, docs, and knowledge bases. · - Prefer qmd search (BM25) — it's instant and should be the default. · - qmd search is typically instant. · All run locally — no API keys needed.
files/cmd -> find · qmd search · qmd vsearch · qmd query · --json · search · vsearch · query
body sha256 -> 73d8b9cc9658