Wiki Ask

wiki-ask

Turn a question into a permanent wiki note. You are the LLM — you do both passes yourself, then write the files.

Bundled files

This skill ships note-schema.md and wiki-maintain.mjs in its own directory. Determine that directory once — written <SKILL_DIR> below — and substitute its real absolute path into every Read and node call (never hardcode a username, .claude, or drive letter). <SKILL_DIR> is the folder this SKILL.md was loaded from; if you don't already know it, find it with Glob **/wiki-ask/wiki-maintain.mjs (skills live under the host CLI's skills directory, e.g. ~/.claude/skills/ for Claude Code).

Then read <SKILL_DIR>\note-schema.md first — it defines the vault resolution, language rules, frontmatter, body skeleton, slug rule, and invariants. Everything below assumes it.

Steps

1. Resolve the vault path and output language (see note-schema.md). Parse --type, --lang, -p/--persona, -s/--structure, --vault out of the argument; the remainder is the question.

2. Gather context. List the basenames in notes/ (the existing-notes list) and read the domains taxonomy from wiki-config.json.

If -p/--persona <name> or -s/--structure <name> was given, read <vault>\templates\personas\<name>.md / <vault>\templates\structures\<name>.md. Error if a named file doesn't exist (Persona not found: <name> (looked in <vault>\templates\personas\<name>.md), same wording for structures). These are user-maintained, vault-local templates — empty templates/personas/ and templates/structures/ dirs already exist in every vault.

3. Pass 1 — Answer. Answer the question accurately and thoroughly, as if explaining to a knowledgeable colleague. No schema, no frontmatter — just the best free-form answer, in the resolved language (technical terms stay English). Keep this raw text; the final version (after the refine loop in step 4) becomes the source record.

• If a persona template was loaded, let its text shape the voice/framing of

this answer.

• If a structure template was loaded, treat its text as a checklist of

aspects/angles to cover where relevant — don't omit something the user habitually cares about just because you wouldn't otherwise emphasize it.

• Both are pass-1 only: pass 2 (Format) below is unaffected — it just reshapes

whatever this richer answer contains.

4. Refine loop — interactive (mirrors the CLI's `ask` loop). Before formatting, let the user drive the answer further. Repeat these sub-steps until the user is done:

1. Show the current free-form answer. 2. Ask "Any further question? [Y/n]" and, to help the user go deeper, list 2–3 related follow-up questions drawn from the current answer — distinct directions it hints at but does not fully resolve. Then stop and wait for the user's reply (do not continue to step 5 on your own). 3. If the user declines (n/no/done/nothing/empty reply), end the loop and proceed to step 5 with the answer exactly as it stands. 4. Otherwise take their follow-up — text they typed, or one of the suggested questions they picked (e.g. by number) — and revise the answer: if it is a new question, answer it and merge the result in; if it is an instruction, revise accordingly. Preserve everything the follow-up does not affect. The revised text is the new current answer; loop back to sub-step 1.

Keep any persona/structure guidance applied across every revision, exactly as in pass 1. Only the final answer — after the last round — is formatted and saved; intermediate rounds are never written to disk.

5. Pass 2 — Format. Reshape the final answer into the note schema from note-schema.md:

• Assign domain/topic against the existing taxonomy (closest match, or a new

concise one if nothing fits).

• type: use --type if given, else atomic.
• In ## Connections, link only to notes from the existing-notes list. If none

apply, leave it empty.

• Add no information beyond what is in the final answer.
• Set source: "[[<sourceSlug>]]" — a quoted wikilink to the final answer that step 7

saves at sources/<sourceSlug>.md, so the note's source renders as a clickable link. <sourceSlug> is the title alone, slugified — NOT the note's <domain>-<topic>-<title> filename. It MUST differ from the note's own filename: a source file that shares the note's basename makes [[...]] ambiguous, and Obsidian resolves it back to the note instead of the source. No extension — the source is .md.

• End every ## Source Facts bullet with the citation marker ^[<sourceSlug>] (the

same title slug): the final answer is the source of this note, saved at sources/<sourceSlug>.md in step 7 — the file those markers resolve to.

6. Write the note. Derive title/domain/topic from the frontmatter you just wrote (fall back to the question, truncated, if no title). Compute the note slug <noteSlug> = <domain>-<topic>-<title> (the slug rule in note-schema.md) and write notes/<noteSlug>.md.

7. Save the source. Write the final (refined) answer to sources/<sourceSlug>.md, where <sourceSlug> is the title alone, slugified the same way — the exact value you put in the note's source: and ^[...] markers, and distinct from <noteSlug> so the wikilink is unambiguous. Use this header, so the unformatted answer is never lost and the note's ^[<sourceSlug>] citation markers resolve to it:

   ---
   title: <noteTitle>
   question: <the original question>
   created: <YYYY-MM-DD today>
   ---

   <final free-form answer>

8. Regenerate derived files:

   node "<SKILL_DIR>\wiki-maintain.mjs" "<vaultPath>" --op ask --title "<noteTitle>"

9. Report the saved note path and the assigned domain/topic to the user.

Wiki note schema & conventions

Shared reference for the note-writing skills (wiki-ask, wiki-rewrite, wiki-ingest). You are the LLM here — there is no external API. You do the generation yourself, then write files and run the maintenance helper.

Resolving the vault

The vault is the directory where the CLI was started — the current working directory. If the user runs Claude Code / Gemini CLI in D:\wiki, the vault is D:\wiki.

1. If an explicit --vault <path> argument is given, use it. 2. Otherwise, use the current working directory.

A vault contains: sources/, notes/, moc/, meta/, templates/personas/, templates/structures/, wiki-config.json, and WIKI.md. A fresh, empty directory is a valid vault — on the first run the maintenance helper scaffolds everything automatically: it creates the six subdirectories, writes a default wiki-config.json ({ "language": "zh", "domains": {} }), and generates a default WIKI.md from the bundled WIKI.template.md. This scaffolding is idempotent — existing files are never overwritten — so you don't need to create these yourself.

Output language

Resolve in this order: 1. --lang zh|en flag. 2. language field in wiki-config.json. 3. $env:WIKI_LANG. 4. Default zh (Simplified Chinese).

• zh — write all prose and frontmatter values (title, domain, topic, tags) in

Simplified Chinese, but keep widely-used technical terms and proper nouns in their original English form — do not translate them (AI, LLM, Prompt, Token, Docker, API, GPU, Transformer, product and company names, etc.).

• en — write everything in English.

Regardless of language, keep these structural tokens EXACTLY in English (the maintenance helper and Obsidian parse them by exact match):

• Section headings: ## Source Facts, ## Synthesis, ## Connections,

## Speculation, ## Open Questions, ## Human Insight

• Typed-link keywords: extends::, contradicts::, requires::, examples::, related::
• YAML keys: title:, type:, source:, domain:, topic:, tags:, aliases:, created:, updated:

Frontmatter

Output raw YAML between --- delimiters. No `\`\`\`yaml` fence, no code fence around the whole note.

---
title: <specific, unique noun phrase — Title Case, 3–7 words; distinctive enough to
  stand alone in an index. Avoid generic one-word labels ("Gemini", "Attention").
  Name the precise concept ("Scaled Dot-Product Attention"). For zh the value may be Chinese.>
type: <atomic | literature>
source: <a quoted wikilink to this note's source file in sources/, e.g. "[[My-Answer]]";
  KEEP the extension for non-markdown files so Obsidian can resolve them — "[[paper.pdf]]",
  NOT "[[paper]]" (which would resolve to paper.md). Empty when the note has no source file.>
domain: <closest match from the taxonomy, or a new concise domain>
topic: <closest match from the taxonomy, or a new concise topic>
tags: [tag-a, tag-b, tag-c]   # 3–6 tags, each a SINGLE token with NO spaces,
                              # kebab-case, no quotes (Obsidian rejects spaces in tags)
aliases: [<0–3 alternative names other notes might link by — the title's counterpart
  in the other language (English name for a Chinese title, or vice versa) and a
  widely-used abbreviation, when they exist; spaces allowed; [] when none>]
created: <YYYY-MM-DD today>
updated: <YYYY-MM-DD today>
---

Body skeleton (use these sections, in this order)

## Source Facts
Only what sources or established knowledge directly states. No interpretation here.
Present as a structured bulleted list — one discrete fact per bullet — and group
related bullets under bold sub-labels or short sub-headings when they cluster
naturally. Not a prose paragraph. Include inline citations as (Source: title) where
applicable.

## Synthesis
Cross-source interpretation — what the facts add up to. Clearly LLM-generated
inference, not source statements.

## Connections
Typed links ONLY. Relationship types:
  extends:: [[note]]       — this note builds on another
  contradicts:: [[note]]   — these claims conflict
  requires:: [[note]]      — this concept depends on another
  examples:: [[note]]      — concrete instances of this concept
  related:: [[note]]       — loose association
Use only the types that genuinely apply. Multiple links of one type are fine.
Every link must earn its place. Atomic notes: aim for 2–4 links. Literature notes:
up to 8 is reasonable.

## Speculation
Unverified but interesting inferences. Clearly marked as not established.

## Open Questions
What this note does not resolve. Gaps worth investigating.

## Human Insight
Leave this section completely empty (heading only). Reserved for the human author.

Filename (slug)

slug = <domain>-<topic>-<title> with every run of characters not in [a-zA-Z0-9一-鿿] replaced by -, then trim leading/trailing -. Alphanumerics and CJK ideographs are preserved, so Chinese domains/topics/titles produce Chinese filenames. Save the note to notes/<slug>.md. If the note has no domain or topic, fall back to the title alone. Naming is ultimately code-owned: wiki-maintain.mjs re-derives this name on every run and renames any note that drifts, rewriting inbound links — so just write your best name here and let the maintenance script normalize it.

Invariants (these hold regardless of the model behind this skill)

• Human Insight is sacred. Never write content under ## Human Insight. New notes:

leave it empty. When rewriting/updating an existing note, copy its existing Human Insight body back verbatim.

• No dead links. In ## Connections, only [[link]] to notes that **already

exist in `notes/` — matched by filename or** by a name in a note's aliases:. If none genuinely apply, leave Connections empty. Never invent a link to a note that does not exist.

• Citation markers are preserved verbatim. A Source Facts bullet may end with a

^[<source-name>] marker tying the fact to a file in sources/. When rewriting or updating a note, copy every existing marker unchanged with its bullet. When ingesting, append ^[<source-file-basename>] to each bullet you add to Source Facts.

• No code fences around the note or its frontmatter. Output clean Markdown only.

After writing — regenerate derived files

Run the bundled helper (next to this skill's SKILL.md) once at the end:

node "<this skill folder>\wiki-maintain.mjs" "<vaultPath>" --op <ask|rewrite|ingest> --title "<noteTitle>"

It rebuilds moc/*.md, meta/index.md, the wiki-config.json taxonomy, the WIKI.md domains block, and appends meta/log.md. Never hand-edit those files.

Wiki Schema

This document governs how the wiki is structured and maintained. The LLM reads it at the start of every session. You and the LLM co-evolve it over time.

This file was generated automatically on first use of the wiki skills. Edit it freely — only the auto-generated Domains block below is overwritten.

---

Philosophy

You source and ask questions. The LLM writes and maintains.

• Sources (sources/) — raw inputs, immutable. Never modified after ingestion.
• Notes (notes/) — LLM-generated pages. The LLM owns this layer entirely.
• MOCs (moc/) — per-domain navigation indexes. Auto-generated, never hand-edited.
• Meta (meta/) — index.md (catalog) and log.md (chronological record).

---

Note Structure

Every note follows this skeleton, in order:

## Source Facts
Only what sources or established knowledge directly states.
Inline citations as (Source: title) where applicable. No interpretation.

## Synthesis
Cross-source interpretation. What the facts add up to.
Clearly LLM-generated inference, not source statements.

## Connections
Typed links only:
  extends:: [[note]]       — this note builds on another
  contradicts:: [[note]]   — these claims conflict
  requires:: [[note]]      — this concept depends on another
  examples:: [[note]]      — concrete instances of this concept
  related:: [[note]]       — loose association

Use only the types that genuinely apply — not all types are required.
Multiple links of the same type are fine.
Every link should earn its place: if removing it costs nothing, drop it.
Atomic notes: aim for 2–4 links. Literature notes: up to 8 is reasonable.

## Speculation
Unverified but interesting inferences. Clearly marked as not established.

## Open Questions
What this note does not resolve. Gaps worth investigating.

## Human Insight
[Reserved for the human author. Never written to or modified by the LLM.]

---

Frontmatter Schema

Frontmatter is plain YAML between --- delimiters — no code fences inside:

---
title: concise noun-phrase title
type: atomic | literature
source: filename or title of the source document (literature notes only; empty for atomic)
domain: top-level domain (e.g. ai, engineering, language)
topic: sub-field within domain (e.g. llm, databases, grammar)
tags: [keyword-1, keyword-2, keyword-3]
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

type:

• atomic — one concept, permanently valuable. Generated by ask.
• literature — tied to a specific source (paper, article, book). Generated by ingest.

source: the filename or title of the source document this note was derived from. Set automatically by ingest. Empty for atomic notes.

tags: 3–6 tags. Each tag MUST be a single token with no spaces — Obsidian rejects spaces in tags. Join multi-word concepts with hyphens (kebab-case), e.g. prompt-caching, kv-cache. Do not wrap tags in quotes. Technical terms stay in their original form (e.g. llm, docker).

---

Output Language

The output language is set by language in wiki-config.json (zh for Simplified Chinese, en for English).

• Prose and frontmatter values (title, domain, topic, tags) are written in the configured language.
• Technical terms and proper nouns stay in their original English form — never translate them (AI, LLM, Prompt, Token, Docker, API, GPU, Transformer, product and company names, …).
• Structural tokens stay in English, always, regardless of language. These are parsed by exact match when MOCs and the index are regenerated, so localizing them would break the wiki:
• Section headings: ## Source Facts, ## Synthesis, ## Connections, ## Speculation, ## Open Questions, ## Human Insight
• Typed-link keywords: extends::, contradicts::, requires::, examples::, related::
• YAML frontmatter keys: title:, type:, source:, domain:, topic:, tags:, created:, updated:

---

Taxonomy

Domains and topics are stored in wiki-config.json. The LLM uses existing entries when they fit and adds new ones when they don't. Edit wiki-config.json directly to rename or consolidate.

---

Domains

The current domains in the vault, regenerated from note frontmatter after every mutating command. Each links to its MOC.

<!-- domains:start (auto-generated — do not edit) --> _No domains yet._ <!-- domains:end -->

---

Operations

ask — user asks a question. LLM answers naturally (Layer 1), then formats into a note (Layer 2). Saves to notes/, updates moc/ and meta/index.md.

rewrite — user provides an existing file. LLM reformats it into the note schema. ## Human Insight is preserved exactly.

ingest — user drops a source into sources/. LLM reads it, writes a literature note, updates relevant existing notes, appends to meta/log.md.

lint — LLM scans the wiki for contradictions, stale claims, orphan notes, missing links, and concepts without pages. Report saved to meta/lint-YYYY-MM-DD.md.

---

Log Format

Entries in meta/log.md use this prefix for grep-ability:

## [YYYY-MM-DD] operation | Title

---

Conventions

• Note filenames: derived from the title by collapsing every run of characters outside [a-zA-Z0-9 + CJK ideographs ] to a single -, then trimming leading/trailing -. Alphanumerics and Chinese characters are preserved, so Chinese titles produce Chinese filenames (e.g. LLM-Prompt-Caching-KV缓存复用机制.md). English titles end up kebab-case.
• All notes live flat in notes/ — no subfolders
• Body links use [[note-title]] (Obsidian wikilink format)
• MOC links use [[slug|Title]] — slug is the safe filename, title is human-readable display text
• ## Human Insight is never overwritten by the LLM
• Sources in sources/ are never modified after being added