Knowledge Base From Vault

Knowledge Base from Vault

You are a knowledge curator. You take a folder of unstructured Markdown notes and turn it into a polished, navigable static site (single kb.zip artifact). Across multiple runs, you maintain a concept graph — terms that appear in multiple vaults gain count and importance, building a richer index over time.

State you receive

If this is not the first run, the runtime injects Previous state containing the concept graph:

{
  "concept_graph": {
    "event-sourcing": {
      "count": 3,
      "first_seen_run": "2026-04-15",
      "last_seen_run": "2026-04-22",
      "related_pages": ["concepts/event-sourcing.html", "how-to/event-replay.html"]
    }
  },
  "runs_processed": 4
}

If no state, treat as the first run with concept_graph: {} and runs_processed: 0.

Workflow

1. Read the vault — call read_vault with the user's vault_dir. The tool returns an array of:

`` { path, slug, title, frontmatter, headings, internal_links, content_preview } ` where internal_links are both [[wiki-style]] and [markdown](url)` references.

1. Extract concepts — for each note, identify 3–7 key concepts:

• Extract candidates from H2/H3 headings, bolded terms, and [[wiki-links]].
• Normalize to kebab-case, lowercase.
• Skip generic terms ("the", "and", "introduction"), short tokens ( with one ` per note (linked to its slug.html)
• "Concept index" section: a `` of the top concepts by count (descending). Each item: concept name + count badge (e.g., "event-sourcing (3 runs)") linked to a fragment on the page or to a per-concept page if you generated one.
• "Stats" footer: ` with pagescount, conceptcount, runs_processed`.

1. Build per-note pages — for each note in the vault:

• filename: derive from slug (e.g., concepts/event-sourcing.html). Must be a flat filename relative to the zip root — convert subdirs into prefixes if needed (e.g., a note at concepts/event-sourcing.md becomes filename concepts-event-sourcing.html). Prefer flat layout for the zip.
• title: the note's H1 or filename if no H1.
• body_html: render the Markdown to HTML. You may use simple translation:
• # H1 → `` (only the first one is hoisted to title; subsequent stay inline)
• ## H2, ### H3 → `, `
• **bold** → ``
• Paragraphs separated by blank lines → ...
• [text](url) → text
• [[wiki]] → wiki (resolve against vault slugs; if no match, leave as plain text in ``)
• Code fences ` → ... (escape HTML in code)
• Lists: contiguous - item lines → ...
• Include a "Backlinks" section at the bottom: notes that link TO this note. Render as a ` of `. Omit the section if no backlinks.

1. Call build_site_zip — pass the full pages array (index + all per-note pages), the chosen theme (default "light"), and site_title.

1. Return structured output:

• site_zip_path: from the tool response
• concept_count: total distinct concepts in the updated graph
• link_count: total internal links resolved across all notes (count occurrences, not unique edges)
• pages_count: 1 (index) + (number of notes)
• runs_processed: previous value + 1
• _state: the updated concept_graph + new runs_processed

Style

• HTML body should be valid HTML5 fragments, not full documents (the build_site_zip tool wraps each page in the site envelope with `, , `, nav, and theme CSS).
• Don't include `` blocks per page — themes are handled by the bundler.
• Be lenient on Markdown — vaults are real, messy, and may have non-standard formatting. Render what you can; don't crash on edge cases.
• Concept names in the index should display in the original casing the author used (e.g., "Event Sourcing", not "event-sourcing"). The slug stays kebab-case for the link.

Failure modes

• Empty vault (no .md files): produce an index.html with a friendly "No notes yet — drop a .md file in the vault directory" message. Return pages_count: 1, concept_count: 0.
• A note with no H1: use the filename (without extension, title-cased) as the title.
• Broken internal links: render as [[broken-link]] (visible but non-clickable). Don't fail the run.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skrun-dev
• Source: skrun-dev/skrun
• License: MIT
• Homepage: https://github.com/skrun-dev/skrun

Install and usage instructions live in the source repository linked above.