New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Vault Contextual Retrieval

by AgriciDaniel in AgriciDaniel/claude-obsidian

Builds and queries a local contextual BM25 index over an Obsidian vault, with optional Nomic reranking through Ollama and strict consent rules before any text leaves the machine.

MITAuto-check passedKnowledge Management

Install Vault Contextual Retrieval

skills CLI
$ npx skills add AgriciDaniel/claude-obsidian --skill wiki-retrieve -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install AgriciDaniel/claude-obsidian wiki-retrieve --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/AgriciDaniel/claude-obsidian.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/wiki-retrieve .claude/skills/wiki-retrieve && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
wiki-retrieve
GitHub stars
15k
Token cost
~1.4k tokens
SKILL.md length
601 words
Files
1
Skills in repo
15
Repo updated
First seen
Licence
MIT

At a glance

Builds and queries a local contextual BM25 index over an Obsidian vault, with optional Nomic reranking through Ollama and strict consent rules before any text leaves the machine.

  • Works in 4 steps: contextual-prefix.py splits pages on… → bm25-index.py builds a local,… → retrieve.py selects BM25 candidates,… → …
  • Building a search index for an Obsidian vault
  • SKILL.md covers Pipeline, Provision locally, Contextual-prefix privacy and Query, plus 2 more sections
  • Calls python3

What it does

A three-step pipeline derives search data from the wiki folder into .vault-meta without touching canonical notes. 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 BM25 index using only the standard library, and retrieve.py picks BM25 candidates, optionally reranks them, drops invalid records, deduplicates by page and returns paths and snippets. The caller still has to read the pages, since retrieval output is not evidence.

Provisioning starts with a preview and builds synthetic prefixes locally with no network use. Chunk and index files are disposable, incremental runs skip unchanged records, and a busy vault fails closed instead of publishing a partial index. Prefix generation through the Anthropic API or a claude subprocess can send page bodies off the machine, so it needs your explicit consent plus an egress flag, and consent is never inferred from an API key. Remote Ollama endpoints need separate approval, and the default reranker accepts localhost only.

When your agent uses it

  • Building a search index for an Obsidian vault
  • Finding relevant passages in a vault with BM25 or a reranked hybrid search
  • Diagnosing why retrieval returns stale or empty results

Example prompts

  • “Build the retrieval index for my vault using local prefixes only.”
  • “Search the vault for passages about contract renewals and rerank them with the local model.”
  • “Retrieval says the index is stale, so run the diagnostics and tell me why.”

Requirements

  • An Obsidian vault with the claude-obsidian plugin
  • Python 3 for the bundled scripts
  • Ollama on localhost for optional reranking

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. contextual-prefix.py splits pages on paragraph boundaries and stores the
  2. bm25-index.py builds a local, standard-library BM25 index over the
  3. retrieve.py selects BM25 candidates, optionally reranks them, rejects
  4. The caller reads the returned pages and performs synthesis; retrieval output

What it can do on your machine

Read from SKILL.md and the folder at commit 32ac5a0. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Vault Contextual Retrieval loads about 1.4k tokens when it runs. Until then it costs about 107 tokens; SKILL.md has 601 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~107
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from AgriciDaniel/claude-obsidian at commit 32ac5a0, republished under its MIT licence (© AgriciDaniel). 601 words, ~1,397 tokens.

Download SKILL.mdSave it as .claude/skills/wiki-retrieve/SKILL.md (or your agent's skills folder).
name
wiki-retrieve
description
Build and query a vault-local contextual BM25 retrieval index with optional multilingual Nomic cosine reranking; use for retrieve, hybrid retrieval, BM25, rerank, contextual retrieval, chunk search, vault search, semantic search, find relevant passages, or retrieval diagnostics. Derived caches stay under .vault-meta, remote egress requires explicit consent, and unavailable reranking falls back deterministically.

Retrieve relevant passages

This extension derives search data from wiki/ into .vault-meta/. It never changes canonical notes. Always pass the selected vault explicitly.

Resolve the installed product root from this skill's own location, not from the vault or current working directory:

bash
PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
PREFIX="$PRODUCT_ROOT/scripts/contextual-prefix.py"
BM25="$PRODUCT_ROOT/scripts/bm25-index.py"
RETRIEVE="$PRODUCT_ROOT/scripts/retrieve.py"
RERANK="$PRODUCT_ROOT/scripts/rerank.py"
test -f "$PREFIX" && test -f "$BM25" && test -f "$RETRIEVE" && test -f "$RERANK"

Pipeline

  1. contextual-prefix.py splits pages on paragraph boundaries and stores the raw chunk plus a short page-level prefix.
  2. bm25-index.py builds a local, standard-library BM25 index over the contextualized text.
  3. retrieve.py selects BM25 candidates, optionally reranks them, rejects invalid records, deduplicates by page, and returns paths and snippets.
  4. The caller reads the returned pages and performs synthesis; retrieval output is not itself evidence.

Provision locally

Preview first, then build synthetic prefixes without network egress:

bash
python3 "$PREFIX" --vault "$VAULT" --all --no-llm --peek
python3 "$PREFIX" --vault "$VAULT" --all --no-llm
python3 "$BM25" --vault "$VAULT" build
python3 "$RETRIEVE" --vault "$VAULT" "wiki" --top 1 --no-rerank --explain

Chunk and index files are disposable runtime state. Incremental prefixing skips records whose chunk and page hashes still match. A complete scan removes surplus records for deleted pages, and the prefixer invalidates the BM25 index before changing its chunk set so a mixed stale index is not served. Prefix and BM25 build operations share the vault-wide mutation lock with every other writer; a busy vault fails closed instead of publishing a partial index.

Contextual-prefix privacy

Synthetic prefixes use only local frontmatter and page text. The Anthropic API and claude subprocess tiers can send page bodies off-machine and therefore require the user's explicit consent plus --allow-egress. Never infer consent from an API key or installed binary. Preview the scope first and state which provider will receive what data.

Remote Ollama endpoints also require explicit approval and --allow-remote-ollama; the default reranker accepts localhost only.

Query

For a strictly read-only lookup, use the prebuilt BM25 index:

bash
python3 "$RETRIEVE" --vault "$VAULT" "$QUERY" --top 5 --no-rerank --explain

For an explicitly requested rerank, omit --no-rerank. The default is Ollama's multilingual nomic-embed-text-v2-moe model (approximately 958 MB); the product never pulls it automatically. To use an already-installed, smaller, English-oriented v1.5 model, pass --model nomic-embed-text explicitly. Nomic models use search_query: for the query and search_document: for candidate text. Nomic v2 has a 512-token input context and Ollama truncates longer embedding inputs by default; BM25 still scores the complete chunk. Embeddings are cached by exact model, input scheme, and hash of the exact prefixed input. A missing local Ollama service, missing selected model, unusable vector, or any candidate embedding failure falls back for the complete result set to the original BM25 order; it never mixes cosine and BM25 score scales.

Query input is bounded at 8,000 normalized characters and result counts must be between 1 and 1,000. Oversized queries and invalid limits fail with an actionable usage error instead of looking like an empty successful search. An untagged model request matches only the installed untagged name or its :latest alias; select any other tag explicitly.

Use direct diagnostics when needed:

bash
python3 "$BM25" --vault "$VAULT" stats
python3 "$BM25" --vault "$VAULT" query "$QUERY" --top 10
python3 "$RERANK" --vault "$VAULT" "$QUERY" --peek
python3 "$RERANK" --vault "$VAULT" "$QUERY" --model nomic-embed-text --peek
Show full SKILL.md (153 more words)Show less

Integrity rules

  • Accept only relative chunk and page paths whose resolved targets remain under $VAULT/.vault-meta/chunks/ and $VAULT/wiki/ respectively.
  • Reject hashless legacy chunk records and require chunk-body, page, and index hashes to match before a cached record can be built or served.
  • Reject absolute paths, symlink escapes, missing pages, mismatched chunk IDs, changed page hashes, and stale index/chunk hash pairs.
  • Rerank the full candidate set, then deduplicate by page, then apply --top.
  • An empty index is an honest no-result state. A missing or corrupt index makes retrieve.py exit 10 with a stable rebuild command; callers fall back to the standard vault query/text-search path and do not fabricate matches.
  • Do not cite benchmark percentages unless a reproducible vault-specific benchmark produced them.

Checkpoint

Observe cache readiness and privacy boundaries, think about whether lexical or semantic ranking is needed, verify returned paths and source freshness, and grow by measuring retrieval misses against a maintained local query set.

© AgriciDaniel, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/wiki-retrieve of AgriciDaniel/claude-obsidian.

Open the folder on GitHubat commit 32ac5a0

Compare with similar skills

Vault Contextual Retrieval next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Vault Contextual Retrieval compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Vault Contextual Retrieval this skillAgriciDaniel/claude-obsidian15k—~1.4kAutomated safety check: PassMIT
Gnogmickel/gno1151 repos~1.6kAutomated safety check: PassMIT
LLM Wikipraneybehl/llm-wiki-plugin118—~5.7kAutomated safety check: PassMIT
Gnogmickel/gno115—~11kAutomated safety check: PassMIT
Engraphdevwhodevs/engraph171—~792Automated safety check: PassMIT
Langchain4j RAG Implementation Patternsgiuseppe-trisciuoglio/developer-kit356—~3.3kAutomated safety check: NotesMIT

Similar skills

  • Gno

    gmickel/gno

    Search local documents, files, notes, and knowledge bases. An agent skill from gmickel/gno.

    115 GitHub starsUsed in 1 repo~1.6k tokens
    Knowledge ManagementAuto-check passed

  • LLM Wiki

    praneybehl/llm-wiki-plugin

    Build and maintain an LLM-curated knowledge base from papers, articles, transcripts, notes and project findings.

    118 GitHub stars~5.7k tokensUpdated 26 days ago
    Knowledge ManagementAuto-check passed

  • Gno

    gmickel/gno

    Search local documents, files, notes, and knowledge bases. An agent skill from gmickel/gno.

    115 GitHub stars~11k tokensUpdated 2 days ago
    Knowledge ManagementAuto-check passed

  • Engraph

    devwhodevs/engraph

    Index and search document collections using hybrid semantic + graph + full-text search.

    171 GitHub stars~792 tokensUpdated 4 mo ago
    Knowledge ManagementAuto-check passed

  • Langchain4j RAG Implementation Patterns

    giuseppe-trisciuoglio/developer-kit

    Provides Retrieval-Augmented Generation (RAG) implementation patterns with LangChain4j for Java.

    356 GitHub stars~3.3k tokensUpdated 29 days ago
    AI & LLM EngineeringAuto-check: notes

  • Knowledge Query

    evolution-foundation/evo-nexus

    Hybrid search (vector + BM25 via RRF + metadata boost) against the pgvector Knowledge base, with optional RAG synthesis.

    545 GitHub stars~804 tokensUpdated 4 mo ago
    AI & LLM EngineeringAuto-check: notes

More from AgriciDaniel/claude-obsidian

All 15 skills in this repo

  • Bounded Autoresearch

    AgriciDaniel/claude-obsidian

    Runs a bounded, source-grounded research loop that drafts a cited dossier and can propose a separately reviewed merge into an Obsidian vault.

    15k GitHub stars~1.6k tokensUpdated 29 days ago
    Auto-check passed

  • Obsidian Canvas Boards

    AgriciDaniel/claude-obsidian

    Creates, inspects and updates Obsidian JSON Canvas boards in a vault, with text, file, link, group and edge nodes, using safe recoverable edits.

    15k GitHub stars~1.4k tokensUpdated 29 days ago
    Auto-check passed

  • Obsidian Wiki Vault Setup

    AgriciDaniel/claude-obsidian

    Sets up or adopts a separate Obsidian knowledge vault through the claude-obsidian core script and routes follow-up work to the right wiki sub-skill.

    15k GitHub stars~1.3k tokensUpdated 29 days ago
    Auto-check passed

  • Obsidian Wiki Log Fold

    AgriciDaniel/claude-obsidian

    Creates a bounded, extractive rollup of recent Obsidian wiki log entries, previewed by default, with one optional apply step and no changes to child pages.

    15k GitHub stars~1.2k tokensUpdated 29 days ago
    Auto-check passed

  • Defuddle Web Page Cleaner

    AgriciDaniel/claude-obsidian

    Plans, and with explicit network consent runs, an external Defuddle extractor that turns an article-like HTTPS page into clean Markdown for later wiki ingestion.

    15k GitHub stars~1.1k tokensUpdated 29 days ago
    Auto-check passed

  • Obsidian Bases Editor

    AgriciDaniel/claude-obsidian

    Explains, drafts and validates Obsidian Bases .base files, building filters, formulas and table, card or list views, and applying edits only through one inspected transaction.

    15k GitHub stars~1.2k tokensUpdated 29 days ago
    Auto-check passed

Works with

Categories

Questions about Vault Contextual Retrieval

What does Vault Contextual Retrieval do?

Builds and queries a local contextual BM25 index over an Obsidian vault, with optional Nomic reranking through Ollama and strict consent rules before any text leaves the machine. vault-meta without touching canonical notes.py picks BM25 candidates, optionally reranks them, drops invalid records, deduplicates by page and returns paths and snippets.

When should I use Vault Contextual Retrieval?

Vault Contextual Retrieval fits situations like: building a search index for an Obsidian vault; finding relevant passages in a vault with BM25 or a reranked hybrid search; diagnosing why retrieval returns stale or empty results.

How do I install Vault Contextual Retrieval in Claude Code?

Run `npx skills add AgriciDaniel/claude-obsidian --skill wiki-retrieve -a claude-code`. Or copy the skill folder (skills/wiki-retrieve in AgriciDaniel/claude-obsidian) into .claude/skills/wiki-retrieve in your project. Claude Code loads it when a task matches its description.

How do I install Vault Contextual Retrieval in Codex?

Run `npx skills add AgriciDaniel/claude-obsidian --skill wiki-retrieve -a codex`. Or copy the skill folder (skills/wiki-retrieve in AgriciDaniel/claude-obsidian) into .agents/skills/wiki-retrieve in your project. Codex loads it when a task matches its description.

Can I use Vault Contextual Retrieval in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add AgriciDaniel/claude-obsidian --skill wiki-retrieve -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/wiki-retrieve, .gemini/skills/wiki-retrieve, .github/skills/wiki-retrieve and .opencode/skills/wiki-retrieve in your project.

What does Vault Contextual Retrieval need to run?

Going by SKILL.md and its folder, Vault Contextual Retrieval needs the command-line tools its instructions call (python3). Our summary lists: An Obsidian vault with the claude-obsidian plugin; Python 3 for the bundled scripts; Ollama on localhost for optional reranking.

Does Vault Contextual Retrieval access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Vault Contextual Retrieval safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Vault Contextual Retrieval use?

Vault Contextual Retrieval is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Vault Contextual Retrieval use?

About 1.4k tokens (SKILL.md is roughly 5.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Vault Contextual Retrieval?

Skills that share tags, products or a category with Vault Contextual Retrieval: Gno (gmickel/gno, 115 stars), LLM Wiki (praneybehl/llm-wiki-plugin, 118 stars), Gno (gmickel/gno, 115 stars) and Engraph (devwhodevs/engraph, 171 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Vault Contextual Retrieval?

AgriciDaniel (a GitHub user) maintains it in AgriciDaniel/claude-obsidian, which has 15,420 GitHub stars. The repository holds 15 skills in this directory. The repository was last updated on September 10, 2026.

Source: AgriciDaniel/claude-obsidian on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.