kb-init

Overview

One-time (or re-runnable) setup that bootstraps a knowledge base project as an Obsidian vault with full omni-document support.

Prerequisites

Obsidian must be installed.

Plugin Setup

After confirming the vault path, run the bundled setup script via Bash tool:

# Interactive — asks user about each optional plugin
bash plugins/kb/setup.sh /path/to/vault

# Install everything
bash plugins/kb/setup.sh /path/to/vault --all

# Install specific plugins only
bash plugins/kb/setup.sh /path/to/vault --only dataview,obsidian-git

Required plugins (always installed):

• Dataview — query wiki articles like a database
• Obsidian Git — auto-backup vault to git

Optional plugins (user chooses interactively):

• Kanban — track wiki tasks on boards
• Outliner — better list editing for article drafts
• Tag Wrangler — rename and merge tags across the wiki
• Local Images Plus — download and store remote images locally

Browser extension (printed as manual step):

• Web Clipper — clip web articles into raw/

The script is idempotent — safe to re-run. If Obsidian is open, tell the user to restart it.

Flow

1. Vault Setup

Ask: create a new vault or use an existing directory? If new, scaffold .obsidian/. If existing, verify it exists.

2. Source Gathering Strategy

Ask how the user wants to get raw data in:

• Self-serve -- User drops files in raw/. Per-type guidance:
  • Web articles: Obsidian Web Clipper extension -> raw/articles/
  • Academic papers (PDF): Download to raw/papers/
  • GitHub repos: Clone/snapshot to raw/repos/
  • Local markdown/text: Copy to raw/notes/
  • Images/diagrams/posters: Place in raw/images/
  • YouTube transcripts: Transcript tool -> raw/transcripts/
  • Podcast episodes: Audio files -> raw/transcripts/
  • Slide decks (.pptx): Place in raw/articles/
  • Datasets (CSV, JSON): Place in raw/datasets/
  • Jupyter notebooks: Place in raw/repos/
  • X/Twitter posts: Via Smaug (optional) -> raw/articles/
• Assisted -- Claude fetches via WebFetch, Bash (clone repos, download PDFs, pull transcripts, fetch YouTube subtitles)
• Mixed -- Some of each

3. Output Format Preferences

Ask which formats the user wants: markdown (always on), Marp slides, matplotlib charts, HTML, CSV, Excalidraw, other. Use an extensible pattern so new formats can be added later.

4. Maintenance Cadence

Inform about options:

• Daily/hourly: /loop (e.g., /loop 1d kb lint)
• Weekly/monthly: /schedule
• Manual: just ask anytime

5. Check Optional Dependencies

Detect and report availability of optional tools that enhance the system:

# Check each tool
which whisper 2>/dev/null && echo "whisper: available" || echo "whisper: not installed (needed for audio/video transcription)"
which ffmpeg 2>/dev/null && echo "ffmpeg: available" || echo "ffmpeg: not installed (needed for audio extraction from video)"
which yt-dlp 2>/dev/null && echo "yt-dlp: available" || echo "yt-dlp: not installed (needed for YouTube transcript fetching)"
python -c "import pptx" 2>/dev/null && echo "python-pptx: available" || echo "python-pptx: not installed (needed for slide extraction)"
python -c "import pandas" 2>/dev/null && echo "pandas: available" || echo "pandas: not installed (needed for dataset analysis)"

Report which media types are fully supported vs. which need manual input. Don't force installation — just inform.

5.5 Gather Report Preferences

Reports, wiki compilations, and query answers are written very differently depending on who the reader is, how much depth they want, and how they want code and references handled. Capture these preferences now so every report-generating skill can apply them.

Preferences live in kb.yaml under report_preferences:. Factory defaults are in plugins/kb/references/report-style-guide.md — read that file first to see the field list, defaults, and variants.

Ask the user these 5 open-ended questions (AskUserQuestion, one at a time):

1. "Who's the primary reader for reports from this vault? (e.g., just you, your team, or external readers like a blog or paper)" → shapes the audience field.
2. "Any style preferences — formal / plain / casual, short / long, anything else?" → shapes the register field.
3. "When covering technical projects, what balance of depth vs breadth do you want? (fewer items with deep walkthroughs, or broad surveys with short entries)" → shapes the depth field.
4. "How should I handle code in reports? Inline snippets, links to github, or walkthroughs with your editor open?" → shapes the code_handling field.
5. "Anything else worth noting upfront — diagram preferences, citation strictness, or any peeves to avoid?" → appended verbatim to the notes field, plus used to tweak diagrams / citations if a clear signal appears.

For each answer:

• Open plugins/kb/references/report-style-guide.md.
• Pick the variant best matching the user's answer (### Default, ### Variant (formal), etc.).
• If the user's phrasing adds a specific constraint the variant doesn't cover, weave it in.
• Write the resulting free-text string to the corresponding field in kb.yaml.

If the user says "use defaults" / "I don't know" / skips a question — copy the ### Default variant for that field unchanged.

The three fields not asked about at init (self_containment, citations, argument_iteration) get their ### Default variants copied in unchanged. Tell the user these defaults are in place and can be updated later via /kb-preferences update <field>.

At the end of this section, briefly summarize the captured preferences back to the user and remind them:

These preferences are stored in kb.yaml under report_preferences:. Skills will propose updates after reports based on your feedback — you'll approve before anything changes. You can edit them anytime via /kb-preferences.

6. Generate kb.yaml

Write kb.yaml at project root with paths, output_formats, obsidian config, and an integrations section. Example:

project:
  name: "My Knowledge Base"
  description: "Knowledge base for [topic]"

paths:
  raw: raw/
  wiki: wiki/
  output: output/
  raw_articles: raw/articles/
  raw_papers: raw/papers/
  raw_repos: raw/repos/
  raw_notes: raw/notes/
  raw_images: raw/images/
  raw_transcripts: raw/transcripts/
  raw_datasets: raw/datasets/

source_strategy: mixed  # self-serve, assisted, or mixed

# Auto-save web pages fetched during any workflow (compile, query, evolve)
# Only saves pages that actually contributed to the output
auto_capture_web: true

output_formats:
  - markdown
  # - charts
  # - html
  # - marp

# How reports, wiki compilations, and query answers should be written.
# Populated from the 5 init questions + factory defaults in
# plugins/kb/references/report-style-guide.md. Free-text fields — skills
# read them as instructions, not parse them as keywords. Updatable via
# /kb-preferences or by hand-editing.
report_preferences:
  audience: |
    <<FILL: style-guide "audience" variant matching user's Q1 answer, tweaked with their phrasing>>
  register: |
    <<FILL: style-guide "register" variant matching user's Q2 answer>>
  depth: |
    <<FILL: style-guide "depth" variant matching user's Q3 answer>>
  code_handling: |
    <<FILL: style-guide "code_handling" variant matching user's Q4 answer>>
  diagrams: |
    <<FILL: style-guide "diagrams" default, unless Q5 signaled otherwise>>
  self_containment: |
    <<FILL: style-guide "self_containment" default>>
  citations: |
    <<FILL: style-guide "citations" default; use "external" variant if audience is publication>>
  argument_iteration: |
    <<FILL: style-guide "argument_iteration" default>>
  notes: |
    <<FILL: Q5 "anything else" answer verbatim, or leave empty if none>>

maintenance:
  manual: true
  scheduled: false

obsidian:
  vault_path: /pat