SkillAgentSearch skills...

wiki-query

Search and synthesize answers from the compiled Obsidian wiki, including cited and multi-hop answers. Use for questions about existing wiki knowledge or fast index-only lookups, and for challenge requests ("challenge this", "argue against X", "poke holes in my plan") that look for the vault's own ev…

Install / Use

npx skills add Ar9av/obsidian-wiki --skill wiki-query

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

95/100

Supported Platforms

Universal

Tags

Our assessment of wiki-query

wiki-query scores 95/100 on our quality scale, 129th of 1,155 Content & Media skills we index (top 12%).

Its SKILL.md is 26 KB long, well organised into 15 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.

With 3,485 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
15/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so wiki-query is actively maintained.
  • Our last check on 2026-11-16 could not reach the source (HTTP 404); it may have been moved or deleted.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

wiki-query compared with similar skills

All 4 of these similar skills score higher than wiki-query; compare them before choosing.

SkillScoreStarsUpdatedFormat
wiki-query (this skill)by Ar9av953.5k54d agoSKILL.md
siyuanby siyuan-note10047.3ktodayMCP Server
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md

Frequently asked questions

How do I install wiki-query?
Run npx skills add Ar9av/obsidian-wiki --skill wiki-query. The install tabs above show the steps for each supported agent.
Which AI agents does wiki-query work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is wiki-query safe to use?
It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is wiki-query still maintained?
The repository was last updated about 2 months ago, so wiki-query is actively maintained.

name: wiki-query description: > Search and synthesize answers from the compiled Obsidian wiki, including cited and multi-hop answers. Use for questions about existing wiki knowledge or fast index-only lookups, and for challenge requests ("challenge this", "argue against X", "poke holes in my plan") that look for the vault's own evidence against a plan. Supports named-vault routing such as wiki-query @work; not for ingesting new sources.

Wiki Query — Knowledge Retrieval

You are answering questions against a compiled Obsidian wiki, not raw source documents. The wiki contains pre-synthesized, cross-referenced knowledge.

This skill is READ-ONLY

wiki-query answers questions. It MUST NOT create or modify any wiki content. The ONLY write it may perform is the single Step 6 append to log.md.

Never, even when a change seems obviously helpful:

  • create or edit pages under concepts/, entities/, skills/, references/, synthesis/, journal/, or projects/
  • modify index.md, hot.md, _insights.md, or .manifest.json

If the user's message contains a new finding, an action request ("save this", "ban X", "record that"), or anything implying a change, do not perform it. Answer the question, PROPOSE the change, and route the user to the right skill:

  • quick note / gotcha → wiki-capture --quick
  • a full new page → wiki-capture
  • a project-knowledge sync → wiki-update

Before You Start

  1. Resolve config — follow the Config Resolution Protocol in llm-wiki/SKILL.md (inline @name override → walk up CWD for .env → global config → prompt setup). For cross-project queries without @name, prefer the global config when present, even if it is a symlink to the vault .env. This gives OBSIDIAN_VAULT_PATH and any QMD variables. Works from any project directory.
  2. Load QMD settings from the resolved config before deciding retrieval strategy. If QMD_WIKI_COLLECTION is set, treat QMD as available subject only to transport/tool checks below. If it is empty or unset, say briefly why QMD is being skipped before using grep/page reads.
  3. If $OBSIDIAN_VAULT_PATH/hot.md exists, read it first — it gives you instant context on recent activity. If the user's question is about something ingested recently, hot.md may answer it before you even open index.md.
  4. Read $OBSIDIAN_VAULT_PATH/index.md to understand the wiki's scope and structure

Visibility Filter (optional)

By default, all pages are returned regardless of visibility tags. This preserves existing behavior — nothing changes unless the user asks for it.

If the user's query includes phrases like "public only", "user-facing", "no internal content", "as a user would see it", or "exclude internal", activate filtered mode:

  • Build a blocked tag set: {visibility/internal, visibility/pii}
  • In the Index Pass (Step 2), skip any candidate whose frontmatter tags contain a blocked tag
  • In Section/Full Read passes (Steps 3–4), do not read or cite any blocked page
  • Synthesize the answer only from allowed pages — do not mention that excluded pages exist

Pages with no visibility/ tag, or tagged visibility/public, are always included.

In filtered mode, note the filter in the Step 6 log entry: mode=filtered.

Retrieval Protocol

Follow the Retrieval Primitives table in llm-wiki/SKILL.md. Reading is the dominant cost of this skill — use the cheapest primitive that answers the question and escalate only when it can't. Never jump straight to full-page reads.

Step 0: GraphRAG Pre-pass (fast index query — no page reads)

Before opening any pages, query the compiled graph index:

obsidian-wiki graph-query "$OBSIDIAN_VAULT_PATH" "<question>" --pretty

Output fields:

  • answer_type: direct | path | list | gap | impact | bridges | hubs | clusters | surprising — shapes what to do next. The last five are structural intents: the question is about the shape of the vault, and the answer comes back fully computed in graph (see below) with no page reads at all.
  • graph: present only for structural intents — the computed answer. null otherwise.
  • candidates: top-ranked pages by title/tag/summary match + degree, with scores and summaries
  • should_read: the pages most worth opening — start here instead of speculatively reading many files
  • path: for multi-hop queries, the shortest wikilink path between the two concepts
  • god_nodes_relevant: hub pages related to your query terms — always useful context
  • index_only: if true, the top candidate's summary already answers the question — skip page reads
  • temporal: as_of, retrievable, excluded_historical — how many pages the event-time filter held back (see below)

Structural intents — these are answered entirely from the graph. The user's phrasing routes automatically:

| The user asks | answer_type | graph contains | |---|---|---| | "what breaks if I delete X" / "what depends on X" / "what links to X" | impact | direct_dependents, transitive_dependents, total | | "which pages bridge my clusters" / "what would fragment my vault" | bridges | pages by betweenness, with label and connects_labels | | "what's central" / "top hubs" / "my main topics" | hubs | pages by degree, with in/out split | | "what clusters do I have" / "how is my wiki organised" | clusters | each cluster's label, size, cohesion, fragmented | | "surprising connections" / "unexpected links" | surprising | cross-cluster links, rarest first |

Report the graph payload directly — do not re-derive it by reading pages. If a structural question names a page that can't be resolved, the CLI falls back to direct and graph is null.

Decision tree:

  1. If graph is non-null → the structural answer is complete. Report it and stop; no page reads.
  2. If index_only: true → answer directly from candidates[0].summary. Skip Steps 1–4, go to Step 5.
  3. If answer_type == "path" and path is non-empty → the connection is in path. Read only those pages.
  4. Otherwise → open only should_read pages (not all candidates). This replaces the speculative 5–10 page reads the old flow required.

The graph used here excludes vault bookkeeping files (index.md, log.md, hot.md, _insights.md). They link to nearly every page, so including them made any two pages look ~2 hops apart and produced meaningless A → index → B paths.

Event time. Pages may carry valid_from / valid_until / superseded_by frontmatter. A page whose valid_until has passed is historical: it stays in the vault and in the graph, but drops out of candidates by default, so "which X do we use?" answers with what is true now rather than whatever was written first.

  • When temporal.excluded_historical is non-zero, say so if it is material to the answer — the user may be asking about the superseded state.
  • If the question is about the past ("what did we use in 2025", "before the migration"), re-run with --as-of YYYY-MM-DD to retrieve what held then.
  • Use --include-historical when the user explicitly wants the whole history, or when you are tracing how a decision changed.
  • A returned candidate carrying superseded_by names its replacement — follow it rather than reporting the stale claim as current.
obsidian-wiki graph-query "$OBSIDIAN_VAULT_PATH" "<question>" --as-of 2025-06-01 --pretty
obsidian-wiki graph-query "$OBSIDIAN_VAULT_PATH" "<question>" --include-historical --pretty

The structural intents ignore this filter on purpose: deleting a page still breaks the historical pages that link to it, so a blast radius must not shrink just because a dependent is no longer current.

Fallback (if obsidian-wiki is not installed): proceed with Step 1 as normal using grep and index.md.

Step 1: Understand the Question

Classify the query type:

  • Factual lookup — "What is X?" → Find the relevant page(s)
  • Relationship query — "How does X relate to Y?" / "What contradicts X?" → Find both pages, their cross-references, and their relationships: frontmatter blocks for typed edges
  • Path / multi-hop query — "How is X connected to Y?" / "What links X to Y?" / "Trace the chain from X to Z" / "What does X depend on transitively?" → X and Y don't link directly; the connection runs through intermediate pages. Use the multi-hop graph traversal in Step 4b.
  • Synthesis query — "What's the current thinking on X?" → Find all pages that touch X, synthesize
  • Gap query — "What don't I know about X?" → Find what's missing, check open questions sections
  • Challenge query — "challenge this" / "argue against X" / "poke holes in my plan" / "what did I decide about X?" → The user is about to commit to something. Look for the vault's own evidence against it. See "Challenge queries" under Step 5.

Also decide the mode:

  • Index-only mode — triggered by "quick answer", "just scan", "don't read the pages", "fast lookup". Stops at Step 3. Answers from frontmatter + index.md only.
  • Normal mode — the full tiered pipeline below.

Step 2: Index Pass (cheap)

Build a candidate set without opening any page bodies:

  • You've already read index.md above — use it as the first filter. It lists every page with a one-line description and tags.
  • Use Grep to scan page frontmatter only for title, tag, alias, and summary matches. A pattern like ^(title|tags|aliases|summary): scoped to vault .md files is far cheaper than content grep.
  • Collect the top 5–10 candidate page paths ranked by:
    1. Exact title or alias match
    2. Tag match
    3. Summary field contains the query term
    4. index.md entry contains the query term
  • Apply tier ordering within each rank bucket: when two candidates score equally, prefer tier: core over tier: supporting over tier: peripheral. Read the tier: frontmatter field with the same cheap grep as other fields. Pages without a tier: field are treated as supporting.

Track retrieval counts as you go (for the transparency report in Step 5/6):

  • candidates_seen — total distinct pages that matched any rank criterion above, before trimming to the top 5–10.
  • candidates_used — how many of those you actually carried forward into Steps 3/4.
  • dropped — candidates_seen − candidates_used, i.e. matches that existed but were never read. If this is non-zero, name the dropped pages (or the count if there are many) so the user knows retrieval wasn't exhaustive — this is not an error, just an honest accounting of what was left out.

If you're in index-only mode, stop here. Answer from summary: fields, titles, and index.md descriptions only. Label the answer clearly: "(index-only answer — page bodies not read; facts below are from page summaries and may miss nuance)". Then skip to Step 5.

Step 2b: QMD Semantic Pass (optional — requires QMD_WIKI_COLLECTION in resolved config)

GUARD: If $QMD_WIKI_COLLECTION is empty or unset after config resolution, skip this entire step and proceed to Step 3. Mention the missing variable in your working update.

No QMD? Skip to Step 3 and use Grep directly on the vault. QMD is faster and concept-aware but the grep path is fully functional. See .env.example for setup.

If QMD_WIKI_COLLECTION is set, run QMD before reaching for Grep unless the question is already fully answered by hot.md or index.md metadata. QMD is especially preferred when the question is semantic, project-specific, asks for related context, or uses terms that may not appear verbatim in titles/frontmatter.

Choose the QMD transport from $QMD_TRANSPORT:

  • mcp (default): use the QMD MCP tool configured in the agent.
  • cli: run the local qmd CLI. Use $QMD_CLI if set; otherwise use qmd.

For detailed CLI command selection, maintenance, and VM caveats, use the local $qmd-cli skill when it i

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars3.5k
CategoryContent
Updated1mo ago
Forks345

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions