| name | onboard |
| description | Use when starting a fresh knowledge base from this template, or when the user says "onboard", "set up my KB", "initialize", "rozpocznij". Interviews the user, personalizes the brain (CLAUDE.md, WRITING_STYLE.md, AGENTS.md), scaffolds topic folders, and builds the indexes. |
ONBOARD
When to use
A fresh clone of the KB template. Detect by the presence of CLAUDE.template.md
in the repo root. If CLAUDE.template.md is absent, the vault is already
initialized — report "already initialized" and offer to reconfigure by
re-running the interview from the saved .kb-onboard.json (Phase 4), rather than
clobbering existing files.
Workflow
Four phases. Phase 1 interviews (one question at a time). Phases 2–4 run with the
collected answers.
Phase 1 — Interview (use AskUserQuestion, ONE question at a time)
Collect, in order:
- KB name and owner (free text).
- Primary language (e.g. English / Polish / other).
- Topics/domains — the top-level subject folders (e.g.
AI, BUSINESS,
HEALTH). Capture a short list.
- Note types in use (default:
basic-note, knowledge-note, tool,
book-note, answer-note; let them add/remove).
- Voice: person (first-person vs neutral) and formality (e.g. "direct and
practical"); and whether to keep the emoji-in-headings convention (yes/no).
- Main branch name (default
main).
Phase 2 — Prereq check (non-blocking)
Probe and print a ✅/⚠️ table:
python --version (required for reindex/lint/render).yt-dlp --version (optional — only for YouTube ingest).ffmpeg -version (optional — Whisper fallback).
Warn on missing; do not abort.
Phase 3 — Scaffold (deterministic)
-
Build the values file .kb-onboard.json at the repo root from the answers.
Map answers to the canonical variables:
KB_NAME, KB_OWNER, PRIMARY_LANGUAGE, MAIN_BRANCH, VOICE_PERSON,
VOICE_FORMALITY — direct strings.NOTE_TYPES — the chosen types joined as basic-note | knowledge-note | ....emoji_headings — boolean from the emoji answer.TOPIC_TABLE — pre-render the topic rows as markdown table lines, one per
topic, in the exact form:
| /content/TOPIC/ | <one-line purpose> | Yes |
(newline-separated; this whole block becomes the value of TOPIC_TABLE).
-
Render the three brain files with render.py:
python .claude/skills/onboard/scripts/render.py --template CLAUDE.template.md \
--values .kb-onboard.json --out CLAUDE.md
python .claude/skills/onboard/scripts/render.py --template AGENTS.template.md \
--values .kb-onboard.json --out AGENTS.md
python .claude/skills/onboard/scripts/render.py --template content/WRITING_STYLE.template.md \
--values .kb-onboard.json --out content/WRITING_STYLE.md
If any render exits non-zero, STOP and show the error (a missing value means an
interview answer wasn't captured) — fix the values and re-render. Do not delete
the templates until all three renders succeed.
-
Delete the templates once all renders succeed:
CLAUDE.template.md, AGENTS.template.md, content/WRITING_STYLE.template.md.
-
Create the topic folders from the answers under content/ (e.g.
content/AI/, content/BUSINESS/), each with a .gitkeep so it is tracked.
-
Offer to delete the example content/REFERENCE/ folder and the sample
content/_raw/inbox/sample-source.md (ask: keep as a tutorial, or remove). Act
on the answer.
-
Prune note templates in content/templates/ to the chosen note types
(e.g. remove book.md if book-note was dropped).
-
Rebuild the indexes so they match the new structure (run from the repo
root — the script resolves content/ relative to the current directory):
python .claude/skills/reindex/scripts/build_indexes.py.
Phase 4 — Handoff
Print a short "what now":
- Drop a file in
content/_raw/inbox/ then run /ingest.
- Ask a question with
/qa.
- Run
/lint for a health check.
Summarize the created topic folders and the personalized files.
Idempotence
.kb-onboard.json is the saved answer set. On a re-run when CLAUDE.template.md
is gone, offer reconfigure: re-read .kb-onboard.json, let the user adjust
answers, and re-render — but warn before overwriting an existing CLAUDE.md,
AGENTS.md, or content/WRITING_STYLE.md.
