Use only when the user explicitly says "qmd" to search local markdown collections (Obsidian vaults, docs folders, QMD collections). Do not use for web search or generic repo code search.
Two modes in one skill -- operational QMD retrieval and semantic query engineering, routed automatically based on what you need.
Load references/ROUTER.md to determine which sub-skill handles this request.
Searching local markdown collections requires two distinct competencies that get conflated:
When these live in one flat skill, the agent loads everything regardless of whether the task is "find my note about X" (operational) or "why is semantic recall poor on this query" (engineering). You end up:
The QMD meta-skill provides two distinct modes with a shared entry point:
Query -- QMD CLI operations: health checks, collection scoping, retrieval mode selection, evidence discipline, command cheatsheet, and MCP setup. This is what runs for most user requests.
Semantic -- Query pattern engineering: expansion, decomposition, contextual rewriting, HyDE, metadata filtering, multi-hop retrieval, and result aggregation. This activates when the challenge is crafting better queries rather than running QMD commands.
The router dispatches automatically. Most requests go to Query. When the user asks about query patterns, poor recall, or semantic search strategy, Semantic activates instead.
| Component | Path | Purpose |
|---|---|---|
| Skill router | references/ROUTER.md | Dispatch table mapping intent to sub-skill |
| Query skill | references/Query/MetaSkill.md | QMD CLI operations, default playbook, examples |
| Query: retrieval workflow | references/Query/references/retrieval-workflow.md | Health checks, collection scoping, mode choice, evidence discipline |
| Query: query patterns | references/Query/references/query-patterns.md | Query documents, intent: / lex: / vec: / hyde:, weighting |
| Query: command cheatsheet | references/Query/references/command-cheatsheet.md | High-value flags, command patterns, setup, indexing, maintenance |
| Query: MCP setup | references/Query/references/mcp-setup.md | MCP tool names, transport, Claude Code/Desktop integration |
| Semantic skill | references/Semantic/MetaSkill.md | Semantic query pattern engineering |
| Semantic: patterns | references/Semantic/references/semantic-patterns.md | Detailed examples for all 9 query patterns |
Summary:
| Trigger | What Happens |
|---|---|
| "qmd find my note about X" | Routes to Query -- runs default playbook |
| "qmd search collection Y for Z" | Routes to Query -- scoped collection search |
| "qmd what collections do I have" | Routes to Query -- health and scope check |
| "qmd update my indexes" | Routes to Query -- maintenance via command cheatsheet |
| "qmd set up MCP" | Routes to Query -- MCP setup reference |
| "qmd why is recall poor on this query" | Routes to Semantic -- diagnose and improve query |
| "qmd help me craft a better search" | Routes to Semantic -- query pattern engineering |
| "qmd use HyDE for this vague question" | Routes to Semantic -- HyDE pattern |
| "qmd decompose this complex question" | Routes to Semantic -- query decomposition pattern |
User: qmd find my note about local markdown retrieval being better than grep
AI:
Running QMD default playbook...
1. qmd update && qmd embed && qmd status
2. Identified collection: vault_obsidian
3. qmd query "local markdown retrieval better than grep for AI agents" -c vault_obsidian -n 10
4. Reopened top hit with qmd get "#abc123"
5. Returned: qmd://vault_obsidian/notes/qmd-vs-grep.md
User: qmd my search for "performance" returns irrelevant sports articles
AI:
Loading Semantic sub-skill...
Pattern: Intent disambiguation + Query expansion
- Add intent: "C++ runtime optimization, not sports"
- Use lex: "C++ performance" optimization -sports -athlete
- Use vec: how to optimize C++ program performance
Result: Relevant hits only, sports articles excluded.
No configuration beyond QMD CLI installation. Collections are managed via qmd collection add.