How to use the wiki-retrieve agent skill for vault search

What the skill makes the agent do

The skill derives search data from the wiki/ folder of your vault and stores it in a hidden .vault-meta folder. It never changes your original notes. The pipeline splits pages into chunks, adds a short page-level prefix to each chunk, builds a keyword-scoring index (BM25) over the result, and then returns the matching page paths and snippets.

Retrieval output is not evidence. The agent is expected to read the returned pages and verify them before answering.

• contextual-prefix.py splits pages on paragraph boundaries and stores each raw chunk with a short page-level prefix.
• bm25-index.py builds a local, standard-library BM25 index over the contextualized text.
• retrieve.py selects BM25 candidates, optionally reranks them, removes invalid records, deduplicates by page and returns paths and snippets.

Install the wiki-retrieve skill

Download the skill ZIP from this page. Then install it in one of two ways: unzip it into ~/.claude/skills/ for your personal skills, or into a project's .claude/skills/ folder to limit it to that project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill is the SKILL.md file and needs the claude-obsidian product scripts installed locally. Before running anything, set PRODUCT_ROOT to the absolute path of your installed claude-obsidian folder. The skill checks that the four scripts exist.

• Requires Python 3.
• Requires the claude-obsidian scripts: contextual-prefix.py, bm25-index.py, retrieve.py and rerank.py.

Build the index for your vault

Preview first, then build. The synthetic prefix mode uses only local frontmatter and page text and makes no network calls. Chunk and index files are disposable runtime state, so you can rebuild them at any time.

Incremental prefixing skips records whose chunk hashes, page hashes and provider/model profile still match. A complete scan removes records for deleted pages. Prefix and BM25 build operations share a vault-wide lock, so a busy vault fails rather than publishing a partial index.

Trigger the skill with natural requests

The skill's description lists the phrases that activate it, including retrieve, hybrid retrieval, BM25, rerank, contextual retrieval, chunk search, vault search, semantic search, find relevant passages and retrieval diagnostics. You do not need to type these as commands. Ask the agent in plain language and name the vault or topic.

For a strictly read-only lookup, the agent uses the prebuilt BM25 index with --no-rerank.

• Find the passages in my vault about onboarding checklists for new contractors.
• Do a vault search for notes that mention the Q3 pricing decision and show me the file paths.
• Use semantic search on my wiki to find relevant passages about data retention, then read the pages before answering.
• Run retrieval diagnostics on the vault: is the BM25 index current?

Use optional reranking

Reranking is off unless you request it. When you ask for a rerank, the default is Ollama's multilingual nomic-embed-text-v2-moe model, which is about 958 MB. The product never pulls it automatically, so the model must already be installed. To use an already-installed, smaller, English-oriented v1.5 model, pass --model nomic-embed-text explicitly.

If Ollama is not running, the model is missing, or any embedding fails, the whole result set falls back to the original BM25 order. Cosine and BM25 scores are never mixed.

• Nomic models use search_query: for the query and search_document: for candidate text.
• Nomic v2 has a 512-token input context; BM25 still scores the complete chunk.
• The default reranker accepts localhost only.

Understand the privacy and network rules

Default operation stays local. The cloud prefix profile, which is the explicit Anthropic API profile, can send page bodies off-machine. It needs your consent, the --allow-egress flag and a configured API key. The skill never infers consent from an API key or an installed binary. Preview the scope and state which provider will receive what data before running it.

Local Ollama prefixes are a separate explicit option and use an already-installed name:tag. Remote Ollama endpoints need explicit approval and --allow-remote-ollama. Selecting local prefixes does not enable reranking.

• The skill runs scripts and uses the network, so review the scripts in the claude-obsidian product before trusting them.
• Derived caches stay under .vault-meta; original notes are not modified.
• Cloud prefixing is not for vaults whose text must stay on your machine.

Check results and measure quality

Use the diagnostic commands when results look wrong. A missing or corrupt index makes retrieve.py exit with code 10 and a rebuild command; the agent should then fall back to the standard vault query or text search rather than invent matches. An empty index is a legitimate no-result state.

To measure retrieval quality, write labelled test queries and run the read-only bench command against a prebuilt index. It reports recall, MRR, missing labels and negative cases, and it never rebuilds the index or calls a model.

• Query input is limited to 8,000 normalized characters; result counts must be between 1 and 1,000.
• Avoid quoting benchmark percentages unless a reproducible benchmark for your own vault produced them.