qmd-search
Skill150 starsChanged 8 days agoMITView on GitHub
OPTIONAL, DORMANT semantic-search layer over the wiki, powered by qmd (local hybrid BM25 + vector + rerank). Use only when the wiki has outgrown index.md AND the user has installed + enabled qmd. The agent auto-detects qmd; if it is absent or disabled this skill does nothing and the normal index.md → grep search runs unchanged. Provides confidence-aware semantic retrieval as the query/output fallback, with a freshness gate before every qmd search. Refreshes only when needed. Retrieval only — never writes wiki pages or decides confidence. Trigger: /qmd-search <query>, or internally as the query/output semantic fallback.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- HurricaHjz/SecondSelfword for word, first seen Oct 20, 2026
- tkolleh/skillstheir own version, first seen Aug 17, 2026
- glebis/claude-skillstheir own version, first seen Jul 1, 2026
- JAVICHILEON/claude---Skillstheir own version, first seen Jul 1, 2026
Other versions4 projects use a version of this.
Word for word · 1
- HurricaHjz/SecondSelf★ 150100% same
Edited · 0
None found.
Wrote their own version · 3
- glebis/claude-skills★ 414same name
- tkolleh/skills★ 1same name
- JAVICHILEON/claude---Skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Use qmd only if all three hold.
- Very specific: line 28
Check installation and .qmd-off before invoking any qmd command, including qmd status.
- Very specific: line 55
The turn-end refresh is retired: No write operation, ingest completion or turn end starts qmd update or qmd embed.
- Distinctive: line 73
Nothing resident: Every qmd invocation — by the agent or by the pre-search gate — is a
- Distinctive: line 77
Dormant by default: Do nothing unless detection passes.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
qmd-search — optional semantic search over the wiki (dormant until qmd is installed)
What this is
A thin, dormant adapter to qmd. It does not replace index.md (the curated, read-first catalogue); it is the
semantic fallback query/output reach for when the catalogue under-covers a question, and the
freshness gate that catches up qmd's embeddings before a search. qmd retrieves; the wiki governs
(compile, cross-link, confidence, conflicts).
Activation — capability detection (the opt-in is installation)
Use qmd only if all three hold; otherwise use the default search:
command -v qmdsucceeds (qmd installed), AND- an index exists for this vault (
qmd statuslists indexed collections), AND - there is no
.qmd-offmarker in the vault root — create that file to force qmd off without uninstalling; its absence means active (installing qmd + building an index is the opt-in).
Check installation and .qmd-off before invoking any qmd command, including qmd status. If detection fails, use index.md → grep; never prompt a non-adopter to install anything. The pre-search gate also checks installation and the marker and explains a plain-route result in one line.
When to invoke (opt-in — never on every search)
qmd search is not a default step. Invoke it only when:
- the user explicitly asks (
/qmd-search, "search semantically", "use qmd"), or - the agent judges the cheap path insufficient —
index.md+grepunder-cover the question (it needs semantic recall, or the corpus is too large to scan reliably).
Otherwise answer from index.md → grep and do not call qmd — a qmd query reads passages into the
agent's context (real tokens), so it must earn that cost. Writes leave the semantic index alone; when a qmd search is warranted, the freshness gate below catches up first.
Search (only when active)
Before every qmd search, qmd vsearch or qmd query, run the gate in the next section and inspect its exit code. Repeat this after an earlier search in the same session. Only exit 0 permits the qmd search; any other result takes the plain route and retains the gate's explanation.
- CLI shell-out by default (no daemon):
qmd query "<question>" --json --files --min-score <t> -n <k>over thewikicollection. The CLI inherits the shell environment, sidestepping the MCP-spawnHOME/db-path pitfall (qmd issue #615). - MCP daemon — an advanced option for heavy users who want warm models (
qmd mcp --http --daemon); setQMD_CONFIG_DIR/ the db path explicitly so the server opens the real index. - Confidence-aware ranking: qmd ranks by relevance; then re-order by each page's
confidence(down-ranklow/very-low, lifthigh/authoritative) and break ties by newerupdated(supersession), per CLAUDE.md §4.6. Then deep-read the top pages and govern as usual. - Index-first, always:
index.mdis read first; qmd is the fallback / widener when the catalogue is insufficient or the corpus is large. A qmd hit never bypasses the governing deep-read.
Refresh before search — one-shot, never resident
Confidence still refreshes on write. For every created or changed page, the agent assigns or confirms confidence and stamps audited: per CLAUDE.md §4.6, independently of qmd.
The turn-end refresh is retired. No write operation, ingest completion or turn end starts qmd update or qmd embed. Immediately before every qmd search, run this gate from the vault root, with the same environment as the search:
/bin/sh .claude/skills/qmd-search/qmd-fresh.sh- Exit 0: the index is fresh or a completed
qmd update && qmd embedcaught it up. The requested qmd search may now run. - Exit 1: qmd is absent,
.qmd-offis present, another session holds the refresh lock, or the refresh failed. Useindex.mdthengrep, and say the semantic index is not current using the gate's one-line reason. Never search the stale index. - Exit 2:
PROBE FAILEDnames a broken premise, such as a missing source tree or failed filesystem operation. Use the same plain route and report that reason; this is never a clean freshness result.
The gate checks both files and directories under wiki/ and raw/ against the refresh stamp. Directory mtimes expose deletions; a missing stamp forces a refresh. It acquires the directory lock before checking freshness, waits for update and embed to finish when stale, stamps before the work and promotes the stamp only after both commands succeed. A change during refresh remains newer than that stamp and is caught at the next search. It neither waits on another session's lock nor removes that session's lock. A lock left by a killed process also takes the plain route.
The default cache is ${XDG_CACHE_HOME:-$HOME/.cache}/qmd, with vault-refresh-stamp and vault-refresh.lock. An absolute INDEX_PATH uses adjacent <INDEX_PATH>.vault-refresh-stamp and <INDEX_PATH>.vault-refresh.lock instead. Keep the root, config and database environment identical for the gate and search; the gate uses the default qmd invocation, so do not add a different --index to the search alone. qmd updates only its configured collections; the existing exclusion of wiki/log.md is unchanged. No daemon, watcher or periodic write-time backstop is needed.
Graceful degradation (mandatory)
Any qmd call that errors, times out or returns nonzero takes index.md → grep. Say why the semantic route was unavailable; a freshness failure says the semantic index is not current. The vault never depends on qmd; it only accelerates with it.
Hard constraints
- Retrieval only. qmd never creates, edits, or deletes wiki pages, and never decides
confidenceor conflicts — those stay withingest/query/deep-lint. - Nothing resident. Every qmd invocation — by the agent or by the pre-search gate — is a
one-shot CLI call (
qmd search/vsearch/query/update/embed) that runs and exits. The agent MUST NOT start the MCP daemon (qmd mcp …) or any long-running/watching qmd process; that is a manual, user-only opt-in. Nothing qmd-related stays resident, and nothing runs while the vault is idle. - Dormant by default. Do nothing unless detection passes; never prompt a non-adopter to install qmd.
- Index-first.
index.mdis read before qmd; qmd is the semantic fallback/widener, not a replacement. - State stays out of git. qmd config/index/models live in
~/.config/qmdand~/.cache/qmd; a project-local index (.qmd/,*.sqlite) is git-ignored. - British/UK English in any user-facing output.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

