# Obsidian Query > Specialist skill for answering questions FROM the Obsidian vault — "how does X work", "why did we choose Y", "what do we know about Z", "find the docs about…". It owns the hidden per-project index (a catalog of every note with one-line summaries, in /.claude-docs/) and run log, reads the index first to locate relevant notes, then synthesizes a cited answer. Valuable answers can be filed back into the vault. Use whenever the user asks a question whose answer should live in the documentation, or asks to find/locate notes. - Skill: `rubber-ducks-syndicate/obsidian-query` (Agent Skill) - Install (CLI): `npx skillmds@latest add rubber-ducks-syndicate/obsidian-query` - Raw SKILL.md: https://api.skillmd.com/api/skills/rubber-ducks-syndicate/obsidian-query/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: rubber-ducks-syndicate (https://skillmd.com/u/rubber-ducks-syndicate) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rubber-ducks-syndicate/obsidian-query --- # Query Specialist (index-based retrieval) You turn the vault from write-only documentation into a queryable knowledge base. The pattern (after Karpathy's "LLM Wiki"): keep a compiled **index** of everything, read the index first, drill into only the relevant notes, answer with citations — no embeddings or RAG infrastructure needed at vault scale. Read `../obsidian-documentation/references/conventions.md` first (project scope, vault location resolution). ## The two files you own Both live in a **hidden dot-folder** — `/.claude-docs//` — so Obsidian never shows them and the vault stays clean for humans. They are machine files: write plain relative paths (from the project folder), not wiki links, since Obsidian doesn't index dot-folders anyway. **`/.claude-docs//index.md`** — content catalog, auto-generated (humans browse MOCs; you read this). One line per note: ```markdown --- project: "Atlas" updated: --- # Index — Atlas > Auto-generated by obsidian-query. Do not edit by hand; ask for a rebuild instead. ## Project level - Architecture/System Overview.md — how the repos fit together · #architecture · upd 2026-06-01 - ADRs/… ## Web App (acme/atlas-web) - Web App/Features/Refunds/Refunds.md — customer-initiated refunds via Stripe; manual review > $500 · #feature #backend/api · upd 2026-06-10 - … ## API (acme/atlas-api) - … ``` Group entries by level: project-wide sections first, then one section per repository. One line = relative path, one-line summary (the retrieval payload — write it to answer "is the answer in here?"), key tags, updated date. **`/.claude-docs//log.md`** — append-only history with a parseable prefix, so `grep "^## \[" log.md | tail -5` shows recent activity: ```markdown ## [2026-06-12] document | Refunds feature Created Features/Refunds/* (3 notes, 1 diagram); updated Payment Processing, Features MOC. ``` One entry per orchestrator/maintenance/query-filing run. Operations: `document`, `update`, `maintenance`, `query-filed`, `index-rebuild`. ## Answering a question 1. **Resolve scope.** Which project? (Match the current repo against `config.md`'s `projects:` list, or take it from the question itself; "across everything" → read each project's index in `.claude-docs/`.) 2. **Read the project's `index.md`** and pick candidate notes by their summary lines. No index yet → offer to build it (below), or fall back to filename + grep search for this one question. 3. **Read the candidates** (and follow 1 hop of promising `[[links]]` — the graph is part of retrieval). Diagrams: read the owning note's text, not the JSON. 4. **Synthesize the answer** in chat: lead with the answer, then supporting detail. Cite every claim with the note it came from: `([[Features/Refunds/Refunds]])`. Same grounding rules as everywhere — if the vault doesn't contain the answer, say exactly that and name the closest related notes; never pad gaps with general knowledge without labeling it as such ("not in the vault, but generally…"). 5. **Offer to file valuable answers.** If the answer involved real synthesis — a comparison, a cross-feature analysis, a "why" reconstructed from several ADRs — offer to save it as a note (e.g., `Architecture/Payment vs Subscription Billing.md`), routed through the orchestrator so it gets tags/links/index like everything else. Explorations should compound, not evaporate into chat history. ## Index maintenance - **Incremental** (every documentation run): the orchestrator hands you the run's created/updated/deleted notes — update their index lines and append the Log entry. Keep summaries fresh: a note whose content changed needs its line rewritten, not just its date. - **Rebuild** (first use in a project, or on "rebuild the index"): delegate the sweep to the **vault-scanner** agent (note list + frontmatter + first paragraph each; inline if agents unavailable), then write `index.md` from scratch, creating `.claude-docs//` if needed. Also rebuild when spot-checks show the index lying about note contents. - The index is derived data — never the source of truth. When index and vault disagree, the vault wins and the index gets fixed. ## When the index isn't enough At moderate scale (hundreds of notes) index-first works well. If retrieval starts missing things or the index outgrows comfortable reading, suggest the user add a local search tool such as [qmd](https://github.com/tobi/qmd) (BM25/vector search over markdown, CLI + MCP); you'd then use it for candidate selection and keep the index for browsing and summaries. Suggest once, don't nag. ## Example **"Why do refunds over $500 need manual review?"** → resolve project via config.md → index.md: `Features/Refunds/Refunds.md` and `ADRs/ADR-0013 - Manual Review for Large Refunds.md` look relevant → read both → answer: "Fraud pattern found during the pilot — refunds above $500 were 9× more likely to be fraudulent, so ADR-0013 chose manual review over automated rules ([[ADRs/ADR-0013 - Manual Review for Large Refunds]]); the flow is described in [[Features/Refunds/Refunds]])." → no filing needed (answer already lives in the vault).