AgentSkillsCN

qmd

本地混合搜索功能，适用于 Markdown 笔记与文档。在阅读文件之前先进行搜索，仅读取相关部分，从而在探索型任务中节省高达 90% 的 Token 使用量。

SKILL.md
--- frontmatter
name: qmd
description: Local hybrid search for markdown notes and docs. Use BEFORE reading files to save tokens - search first, read only what's relevant. Provides 90% token savings on exploration tasks.

qmd - Quick Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Use this to find relevant files BEFORE reading them to dramatically reduce token usage.

When to Use (IMPORTANT)

ALWAYS prefer qmd search over reading files directly when:

  • •Exploring a codebase or documentation
  • •Looking for specific functionality or concepts
  • •Finding related files to a topic
  • •Answering questions about the codebase

Token savings: Instead of reading 5 files (5000+ tokens), search first (50 tokens) and read only the relevant sections (200 tokens).

Search Priority (follow this order)

  1. •qmd search "query" - Fast BM25 keyword search. Use this first, it's instant.
  2. •qmd vsearch "query" - Semantic similarity. Use only if keyword search fails.
  3. •qmd query "query" - Hybrid + reranking. Avoid unless user explicitly requests highest quality.

Common Commands

bash
# Fast keyword search (DEFAULT - use this first)
qmd search "authentication" -n 10

# Search specific collection
qmd search "api routes" -c my-project

# Get file paths only (for deciding what to read)
qmd search "database schema" --files

# JSON output for parsing
qmd search "error handling" --json

# Semantic search (slower, use as fallback)
qmd vsearch "how does the login flow work"

Retrieve Documents

bash
# Get specific file
qmd get "path/to/file.md"

# Get by document ID from search results
qmd get "#docid"

# Get multiple files
qmd multi-get "docs/*.md" --json

Workflow Example

Bad (token expensive):

code
1. Read src/auth/login.ts (800 tokens)
2. Read src/auth/session.ts (600 tokens)
3. Read src/auth/middleware.ts (500 tokens)
4. Read src/auth/types.ts (400 tokens)
-> Found answer in middleware.ts
Total: 2300 tokens

Good (token efficient):

code
1. qmd search "authentication middleware" --files (response: 50 tokens)
   -> Returns: src/auth/middleware.ts:45-62
2. Read only the relevant section (150 tokens)
Total: 200 tokens (90% savings!)

Tips for Claude

  • •Search before reading: Always try qmd search first
  • •Use --files flag: Get paths without content to decide what to read
  • •Be specific: More specific queries = better results
  • •Check collections: Use qmd status to see indexed collections
  • •Combine with cartographer: CODEBASE_MAP.md gives structure, qmd gives content

Maintenance

bash
qmd status          # Check index health and collections
qmd update          # Re-index changed files (fast)
qmd embed           # Update vector embeddings (slower)