QMD Search

Search markdown knowledge bases efficiently using qmd. Use this when searching Obsidian vaults or markdown collections to find relevant content with minimal token usage.

Security Scan

The skill is an instruction-only wrapper for the local qmd tool and its requirements and instructions are coherent with its stated purpose of searching local Markdown collections.

Purpose & Capability

The name/description match the instructions: everything is about using the local 'qmd' tool to search markdown collections. Minor note: the skill does not declare 'qmd' as a required binary up front, but the runtime instructions explicitly check for and install it if missing — this is reasonable for an instruction-only skill.

Instruction Scope

Instructions stay within scope (list collections, run qmd search/vsearch/hybrid, present snippets and file paths). They direct the agent to use a 'Read' tool on returned file paths to show content — this is expected for a search/read workflow but does grant the agent the ability to read local files, so users should be aware the agent will access files you point it at.

Install Mechanism

No install spec in the registry (lowest-risk). SKILL.md includes suggested manual install commands (bun install -g https://github.com/tobi/qmd), which are reasonable guidance for users; the skill itself does not auto-download or execute installers.

Credentials

No environment variables, credentials, or config paths are requested. The skill's needs are proportional to its functionality.

Persistence & Privilege

always is false and the skill does not request persistent/system-wide changes or elevated privileges. It does not modify other skills or global configs.

Assessment

This skill is a local-search helper for the qmd tool and looks coherent. Before installing/using it: (1) Be prepared that the agent may read local Markdown files and file paths it returns — avoid enabling it on folders containing sensitive data. (2) If you choose to install qmd, verify the GitHub repo (https://github.com/tobi/qmd) yourself before running the provided bun install command. (3) The skill will prompt to run qmd commands and to use a Read tool to show file contents; only allow those actions if you trust the environment and the files it will access.

QMD Search Skill

Search markdown knowledge bases efficiently using qmd, a local indexing tool that uses BM25 + vector embeddings to return only relevant snippets instead of full files.

Why Use This

• 96% token reduction - Returns relevant snippets instead of reading entire files
• Instant results - Pre-indexed content means fast searches
• Local & private - All indexing and search happens locally
• Hybrid search - BM25 for keyword matching, vector search for semantic similarity

Commands

Search (BM25 keyword matching)

qmd search "your query" --collection <name>

Fast, accurate keyword-based search. Best for specific terms or phrases.

Vector Search (semantic)

qmd vsearch "your query" --collection <name>

Semantic similarity search. Best for conceptual queries where exact words may vary.

Hybrid Search (both + reranking)

qmd hybrid "your query" --collection <name>

Combines both approaches with LLM reranking. Most thorough but often overkill.

How to Use

1. Check if collection exists:

   qmd collection list
   

2. Search the collection:

   # For specific terms
   qmd search "api authentication" --collection notes
   
   # For conceptual queries
   qmd vsearch "how to handle errors gracefully" --collection notes
   

3. Read results: qmd returns relevant snippets with file paths and context

Setup (if qmd not installed)

# Install qmd
bun install -g https://github.com/tobi/qmd

# Add a collection (e.g., Obsidian vault)
qmd collection add ~/path/to/vault --name notes

# Generate embeddings for vector search
qmd embed --collection notes

Invocation Examples

/qmd api authentication          # BM25 search for "api authentication"
/qmd how to handle errors --semantic   # Vector search for conceptual query
/qmd --setup                     # Guide through initial setup

Best Practices

• Use BM25 search (qmd search) for specific terms, names, or technical keywords
• Use vector search (qmd vsearch) when looking for concepts where wording may vary
• Avoid hybrid search unless you need maximum recall - it's slower
• Re-run qmd embed after adding significant new content to keep vectors current

Handling Arguments

• $ARGUMENTS contains the full search query
• If --semantic flag is present, use qmd vsearch instead of qmd search
• If --setup flag is present, guide user through installation and collection setup
• If --collection <name> is specified, use that collection; otherwise default to checking available collections

Workflow

1. Parse arguments from $ARGUMENTS
2. Check if qmd is installed (which qmd)
3. If not installed, offer to guide setup
4. If searching:
   • List collections if none specified
   • Run appropriate search command
   • Present results to user with file paths
5. If user wants to read a specific result, use the Read tool on the file path