From 648b238b647410b1a23bf6a6d08caf9c87e992c5 Mon Sep 17 00:00:00 2001 From: vitya Date: Sat, 6 Jun 2026 20:01:13 +0300 Subject: [PATCH] feat(using-wiki-graph): thin trigger skill for the wiki-graph MCP [v0.1.0] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit skills/using-wiki-graph/SKILL.md — triggers on relational/structural wiki questions («что связывает X и Y», path/neighbors/backlinks/orphans), routes to mcp__wiki-graph__* instead of single-page reads (the 0%-recall failure mode). Precondition: dense corpora only (modulair yes, sparse meta-wiki no). hermes/mapping.yaml: registered as `pending` (intended auto/mcp, mirrors using-vds-ops) — NOT promoted to auto; promotion gated on a using-wiki-graph-test-trigger behavioral audit (instrument-touch). Installed scoped via scripts/install.sh. Closes [wiki-graph-skill]. NOTE: build-hermes currently red on pre-existing unmapped skill 'meta-host-routing' (not this change). Co-Authored-By: Claude Opus 4.8 (1M context) --- hermes/mapping.yaml | 7 +++++ skills/using-wiki-graph/SKILL.md | 54 ++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 skills/using-wiki-graph/SKILL.md diff --git a/hermes/mapping.yaml b/hermes/mapping.yaml index 0399504..7a60efc 100644 --- a/hermes/mapping.yaml +++ b/hermes/mapping.yaml @@ -154,6 +154,13 @@ skills: category: mcp reason: "Calls mcp__vds-ops__* tools (read-only, but touches infrastructure). Behavioral audit via using-vds-ops-test-trigger required before promotion to auto." + using-wiki-graph: + mode: pending + intended: + mode: auto + category: mcp + reason: "Calls mcp__wiki-graph__* tools (read-only, parses a .wiki/ corpus server-side). Behavioral audit via using-wiki-graph-test-trigger required before promotion to auto." + session-handoff: mode: pending intended: diff --git a/skills/using-wiki-graph/SKILL.md b/skills/using-wiki-graph/SKILL.md new file mode 100644 index 0000000..edbebe9 --- /dev/null +++ b/skills/using-wiki-graph/SKILL.md @@ -0,0 +1,54 @@ +--- +name: using-wiki-graph +version: 0.1.0 +description: "Use when a question is RELATIONAL about a wiki — «что связывает X и Y», «как связаны X и Y», «путь между X и Y», «через что X выходит на Y», «what connects X and Y», «how is X related to Y», «shortest path between pages» — or about wiki STRUCTURE/HEALTH — «что ссылается на X», «кто линкует X», «соседи страницы X», «сироты в вики», «битые/dangling ссылки», «сколько связных компонент», «backlinks of X», «orphan pages». Triggers the `wiki-graph` MCP server (`mcp__wiki-graph__path|neighbors|backlinks|orphans|stats`), which runs a deterministic BFS over `[[wikilinks]]` server-side. The failure-mode this guards: on a relational question the agent does a semantic read of one page and STOPS, never walking the multi-hop link chain (0% recall on such queries vs 67% for graph BFS). Precondition: only DENSE corpora (e.g. modulair-wiki, 150 linked pages) — skip on sparse wikis (the shared meta-wiki has ~1 link total, graph is empty). Each tool needs `corpus` = absolute path to the `.wiki/` dir. Read-only, no grant needed. Skip for content/semantic questions answerable by reading a single page, and for wikis with no `[[links]]`." +--- + +# using-wiki-graph + +Stop and call the graph. On a **relational** or **structural** wiki question, do not answer from reading one page — the links form a graph the LLM does not traverse reliably by reading. The `wiki-graph` MCP server walks `[[wikilinks]]` deterministically and returns the answer in a few lines; the corpus never enters context. + +## When to use + +Trigger when the question is about **connections between pages** or **wiki structure**, not about the content of a single page: + +- relational — "what connects X and Y", "how are X and Y related", "path between X and Y", «что связывает», «как связаны», «путь между»; +- neighbourhood — "neighbours of X", "what does X reach in 2 hops", «соседи X», «что рядом с X»; +- incoming — "what links to X", "who references X", «кто ссылается на X», «backlinks»; +- health — "orphan pages", "dangling/broken links", "how many components", «сироты», «битые ссылки», «здоровье вики». + +## Precondition — dense corpus only + +The graph is useful only when the wiki is actually linked. modulair-wiki (~150 linked pages, ~715 edges) — **yes**. The shared meta-wiki (`~/projects/.wiki/`, ~1 link total) — **no**, the graph is empty; answer by reading instead. If unsure, run `stats` first: near-zero `edges` ⇒ fall back to reading. + +## Inputs + +- `corpus` — **absolute** path to the wiki's `.wiki/` directory (e.g. `C:/Users/vitya/projects/modulair-wiki/.wiki`). Every tool requires it. Provenance dirs (`raw/`, `sources/`, `assets/`) are excluded automatically; the graph is the canonical concept/entity network. +- page references are **slugs** (the `.md` basename, kebab-case), case-insensitive — e.g. `euclidean-rhythms`, not a title or path. + +## Steps + +1. Pick the tool from the question shape: + - relational / "what connects" → `mcp__wiki-graph__path` (`from`, `to`) — shortest undirected chain. + - neighbourhood → `mcp__wiki-graph__neighbors` (`node`, `depth` default 1) — outgoing within N hops. + - "who links to" → `mcp__wiki-graph__backlinks` (`node`) — incoming references. + - health → `mcp__wiki-graph__orphans` (unlinked pages + dangling targets) or `mcp__wiki-graph__stats` (counts). +2. Pass `corpus` + the slugs. Report the returned chain/list directly; don't re-derive it by reading pages. +3. Empty `path` result = genuinely no link chain — say so, don't invent one from prose proximity. + +## Failure modes + +- Slug typo / page not under a canonical dir → `path` returns empty or the node is unknown. Verify the slug is a real `.md` basename. +- Sparse corpus → empty/near-empty graph. Don't force it; read instead (see Precondition). +- `wiki-graph` server not registered → tools absent in session. Then read manually and note the server needs registering in `~/.claude.json`. + +## Side effects + +None. Read-only; parses files server-side. No writes, no grant, no network. + +## What NOT to do + +- Don't answer a relational question from a single-page read — that's the exact 0%-recall failure this skill exists to prevent. +- Don't paste the whole wiki into context to "trace" links by hand — the server does it at zero token cost. +- Don't invoke on dense-content questions ("what is euclidean-rhythms about") — that's a read, not a graph walk. +- Don't pass titles or relative paths — only absolute `corpus` + basename slugs.