# Vault Init > Use when the user wants to scaffold a new Karpathy-style LLM Wiki vault for the current project and register it for the vault-keeper skill. Triggers on phrases like "init a vault", "set up a knowledge vault", "create a second brain for this project", "scaffold the wiki", "vault-init", "start a new vault here". - Skill: `bernardorubin/vault-init` (Agent Skill) - Install (CLI): `npx skillmds@latest add bernardorubin/vault-init` - Raw SKILL.md: https://api.skillmd.com/api/skills/bernardorubin/vault-init/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: bernardorubin (https://skillmd.com/u/bernardorubin) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/bernardorubin/vault-init --- # Initialize a new project vault Scaffold a Karpathy-style LLM Wiki vault for the current project, register it, and (optionally) version-control it. After this runs, the [[vault-keeper]] skill will auto-engage on this project — Claude reads from and writes to the vault during normal work. ## Arguments `$ARGUMENTS` — Optional. Accepts a vault path. If omitted, prompts interactively. ``` /vault-init → Interactive: prompts for paths, git, GitHub /vault-init ~/MyProjectVault → Use this vault path; still prompts for the rest /vault-init ~/MyProjectVault --no-git → No git; just scaffold + register ``` ## Instructions ### Step 1 — Determine the project path The **project path** is the directory whose Claude sessions should activate the vault. Walk up from the current working directory until you find a directory that looks like a project root (contains any of: `.git/`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `CLAUDE.md`). If `$ARGUMENTS` doesn't override the path, **ask the user**: > Project path to register? \[default: ``\] If they accept the default, use it. Otherwise use what they provide. Resolve to an absolute path. ### Step 2 — Determine the vault path Default vault path: `~/Vault` (e.g., project `apps/myapp` → `~/MyappVault`, capitalized). If `$ARGUMENTS` provided a vault path, use that. Otherwise ask: > Vault path? \[default: `~/MyappVault`\] Expand `~` to `$HOME`. Resolve to an absolute path. **Refuse to proceed if:** - The project path is already registered in `~/.config/claude-pro-skills/vaults.json` (offer to overwrite explicitly) - The vault path already exists and contains files other than `.obsidian/` or `.git/` (offer to use it as-is and skip scaffolding, or pick a different path) ### Step 3 — Ask about version control Two prompts (independent): > Init git inside the vault? \[Y/n\] > Create a private GitHub repo? \[Y/n\] Default both to yes. The GitHub repo only happens if `gh` is installed and authed (`gh auth status` succeeds). If git is no, GitHub is automatically no. ### Step 4 — Scaffold the vault Create the directory structure: ```bash mkdir -p {vault}/raw/{projects,work-logs,archive/projects} mkdir -p {vault}/wiki/{people,projects,integrations,concepts,playbooks,tickets,sources} mkdir -p {vault}/templates touch {vault}/raw/{projects,work-logs,archive,archive/projects}/.gitkeep touch {vault}/wiki/{people,projects,integrations,concepts,playbooks,tickets,sources}/.gitkeep ``` > **Note on `work-logs/`**: per-user subfolders (`work-logs//`) and their `archive/` are created lazily by `/save-session-to-worklog` on first use. Don't pre-scaffold them — the active user is unknown at vault-init time. Write the following files (use the exact content shown — these are templates, not Claude-generated prose): #### `{vault}/CLAUDE.md` The schema. Generic Karpathy-style. The user will customize it over time as their domain becomes clearer. ````markdown # {Project} Vault — LLM Wiki A persistent, auto-updating second brain for {Project} work. Based on Andrej Karpathy's LLM Wiki pattern. The human curates sources, asks questions, and directs analysis. **Claude maintains the wiki** — writing pages, cross-linking, updating the index, logging operations, and folding new findings into existing pages so knowledge compounds instead of getting re-derived every session. ## Folder structure ``` raw/ ← source documents projects/ ← EPIC/INITIATIVE-SCOPED bundles — refs + plans for one project / ← e.g. payments-integration/, mobile-redesign/, etc. *.md ← reference docs (immutable) AND living plans together work-logs/ ← per-user worklog folders (created lazily by /save-session-to-worklog) / ← e.g. bernardorubin/, alice/ — one folder per teammate *.md ← current month's worklog at the top archive/ ← past months auto-rotated here by /save-session-to-worklog archive/ projects/ ← retired epic folders (final-ingested + archived) wiki/ ← LLM-maintained markdown index.md ← TOC for the entire wiki, organized by category log.md ← append-only chronological operation log (single file, Karpathy pattern) people/ ← people involved (one page per person) projects/ ← repos / sub-projects integrations/ ← third-party services and APIs concepts/ ← flows, patterns, domain ideas playbooks/ ← repeatable how-tos (testing, deployment, debugging) tickets/ ← major tickets/epics worth persistent context sources/ ← summary pages for ingested raw/ docs templates/ ← page templates for new wiki entries .obsidian/ ← Obsidian config (don't touch, if used) ``` ## Page format Every wiki page uses YAML frontmatter + a structured body: ```markdown --- summary: One-line description. sources: - filename.md last_updated: YYYY-MM-DD tags: [tag1, tag2] --- # Page Title **Summary**: One to two sentences expanding on the frontmatter summary. --- Main content. Short paragraphs, clear headings. Use [[wiki-links]] generously to connect related concepts. Every factual claim that came from a source gets a citation: Some claim (source: filename.md). ## Related pages - [[related-page-1]] - [[related-page-2]] ``` **Page-name conventions**: lowercase, hyphenated. Tickets are the exception (e.g., `ACME-5611.md`). ## When to write to the vault (auto-update triggers) You don't wait for an explicit "ingest" command for everyday updates. During any session, when you encounter one of the following, write or update the relevant wiki page **without asking permission** (1–2 page touches max). For larger ingests of a new raw source, follow the **ingest workflow** below. | Signal | Action | |---|---| | Integration detail or quirk worth remembering | Update `wiki/integrations/.md` | | Architectural decision + rationale | Update `wiki/projects/*.md` and/or `wiki/concepts/*.md` | | Debugging finding (root cause + fix pattern) | Add/update `wiki/playbooks/.md` | | Person fact (ownership, expertise, communication norms) | Update `wiki/people/.md` | | Multi-step or multi-week effort touching many files | Create/update `wiki/tickets/.md` | | Contradiction with an existing claim | Note both, mark contradiction explicitly, link to newer source | | New term/concept used multiple times | Create `wiki/concepts/.md` | **Always after any auto-update**: 1. Add or refresh the entry in `wiki/index.md` 2. Append a one-line entry to `wiki/log.md` (single append-only operation log). Format: `## [YYYY-MM-DD] update | {page} | {what}` 3. If the update introduces a new wiki-link, ensure the target page exists (stub if needed) **Threshold for writing**: if a fact would have saved 5+ minutes if known at session start, file it. If it's obvious from reading the code, don't. ## Ingest workflow When the user adds a new source to `raw/` and asks you to ingest it: 1. Read the full source document 2. **Discuss key takeaways with the user before writing anything** — surface the 3–7 most important findings and ask which to emphasize 3. Write a summary page in `wiki/sources/` named after the source 4. Create or update concept/entity/integration pages for each major idea or entity 5. Add `[[wiki-links]]` connecting related pages (in both directions) 6. Update `wiki/index.md` with new pages and one-line summaries 7. Append a log entry to `wiki/log.md`: `## [YYYY-MM-DD] ingest | {source title} | {pages touched count}` If a source contradicts an existing wiki page, do NOT silently overwrite. Note the contradiction in the page (`> **Conflict**: source X says ..., source Y says ...`) and ask the user how to resolve. ## Query workflow When the user asks a question: 1. Read `wiki/index.md` first to find candidate pages 2. Follow links and synthesize an answer with citations to specific wiki pages 3. If the answer isn't in the wiki, say so clearly. Offer to investigate and **file the answer back as a new wiki page** ## Lint workflow When asked to lint or audit: - Orphans (pages with no inbound `[[wiki-links]]`) - Stubs (`[[wiki-links]]` to nonexistent pages) - Contradictions - Stale claims (`last_updated` older than newer sources cited) - Format violations - Index drift (pages exist but not in `index.md`, or vice versa) Report as a numbered list. Don't auto-fix — surface and let the user decide. ## Citation rules - Every factual claim from `raw/` gets a citation: `(source: filename.md)`. - If two sources disagree, note the contradiction explicitly. - If a claim has no source (came from code, conversation, inference), mark it `(unverified)` or `(from code: path/to/file.ts)`. - Wiki-to-wiki references use `[[wiki-links]]`, not citations. ## Hard rules 1. **`raw/` is per-file mutable.** Reference docs (anything inside `raw/projects//` that's not flagged as a living plan) are citation anchors and shouldn't be modified. Living plans (typically the execution-plan file within each project folder) and worklog files (`raw/work-logs//`) ARE meant to be edited freely by both Claude and the user. The immutability principle is per-file, not per-`raw/`. **Worklog folders are user-scoped** — only edit worklogs under your own `/` (resolved by `/save-session-to-worklog`); other teammates' folders are read-only to you. 2. **Always update `wiki/index.md` and `wiki/log.md`** after any wiki write. 3. **Page names are lowercase-hyphenated** (except ticket IDs). 4. **No empty wiki pages** — at least a summary line and a "Related pages" section. 5. **When uncertain about categorization, ask the user.** 6. **The vault auto-syncs to its remote.** The vault is its own git repo, separate from any code repo, and is meant to stay continuously synced. The claude-pro-skills vault skills commit + push after every write, union-merging any conflict (keep BOTH sides, never discard — see the vault-resolve-conflicts skill). If you edit the vault directly, do the same: commit, `pull --rebase` (union-merge any conflict), push. This is a deliberate vault-only exception to per-push approval; code repos keep theirs. Skip if the vault has no remote. ## Epic-shipped workflow (when work for a project completes) When an epic in `raw/projects//` is complete: User says: *"Do a final ingest of `raw/projects//` then archive it"* (optionally adds *"and delete it"*). Claude: 1. Re-reads each file in the folder and diffs against existing wiki content 2. Files anything new or changed into the relevant wiki pages (concepts, integrations, tickets, etc.) 3. Adds a log entry capturing what was new in the final pass 4. `git mv raw/projects// raw/archive/projects//` 5. If the user said "and delete it": also `rm -rf raw/archive/projects//` after archiving (or instead — confirm intent) 6. Confirms: "archived [and deleted]; citations are filename-only and remain valid" Default behavior is archive (reversible). Deletion is explicit because re-ingestion is sometimes useful later. ```` > Replace `{Project}` with the project basename (e.g., "Acme", "MyApp"). Do this textual substitution, not literally. #### `{vault}/wiki/index.md` ```markdown --- summary: Table of contents for the entire {Project} wiki. Updated on every page create/update. last_updated: YYYY-MM-DD tags: [meta, index] --- # {Project} Wiki Index The catalog of every wiki page. Browse by category. Each entry: link + one-line summary. > **Status**: scaffolded YYYY-MM-DD. Empty until first ingest. --- ## People _Stubs to fill as encountered._ ## Projects / Areas _Stubs to fill as encountered._ ## Integrations _Stubs to fill as encountered._ ## Concepts _Stubs to fill as encountered._ ## Playbooks _Stubs to fill as encountered._ ## Tickets / Epics _Stubs to fill as encountered._ ## Sources (raw/) _Summary pages for ingested raw documents._ ``` #### `{vault}/wiki/log.md` Single append-only chronological log (Karpathy's pattern). One file, never rotates. ```markdown # {Project} Vault Operation Log Append-only chronological record of every vault operation. Newest entries at the bottom. Format: `## [YYYY-MM-DD] {op} | {target} | {note}`. Greppable: `grep "^## \[" wiki/log.md | tail -10` Operation types: `init`, `ingest`, `update`, `lint`, `query`, `worklog`. --- ## [YYYY-MM-DD] init | vault scaffolded Created CLAUDE.md schema, wiki/index.md, wiki/log.md, and category subfolders. Registered with vault-keeper. ``` #### `{vault}/templates/page.md` ```markdown --- summary: One-line description of this page. sources: [] last_updated: YYYY-MM-DD tags: [] --- # {{Page Title}} **Summary**: One to two sentences. --- ## Overview Main content. ## Related pages - [[related-page]] ``` (Optionally also write `templates/person.md`, `templates/integration.md`, `templates/ticket.md` — same frontmatter+headings pattern as `page.md`, specialized per category. Keep it minimal at scaffold time; the user can add more templates as their wiki grows.) #### `{vault}/.gitignore` ```gitignore # Obsidian — track config, ignore per-machine workspace state .obsidian/workspace*.json .obsidian/cache/ .obsidian/plugins/*/data.json # macOS .DS_Store # Editor / IDE .vscode/ .idea/ *.swp *~ ``` #### `{vault}/README.md` ```markdown # {Project} Vault A personal knowledge base for {Project} work. Built on Andrej Karpathy's LLM Wiki pattern. Three layers: 1. `raw/` — source documents (immutable; user curates) 2. `wiki/` — markdown pages Claude maintains, cross-linked via `[[wiki-links]]` 3. `CLAUDE.md` — the schema (page format, ingest workflow, auto-update triggers) Open in [Obsidian](https://obsidian.md). Entry point: `wiki/index.md`. The vault auto-updates during Claude sessions via the `vault-keeper` skill in claude-pro-skills. > ⚠️ Personal knowledge base. ``` ### Step 5 — Init git (if requested) ```bash # Always git -C, never cd — the shell's cwd persists across the session git init -q {vault} git -C {vault} add -A git -C {vault} commit -q -m "Scaffold {Project} vault" ``` ### Step 6 — Create GitHub repo (if requested) Confirm `gh` is installed and authed first: ```bash command -v gh >/dev/null && gh auth status >/dev/null 2>&1 ``` If yes, create the repo: ```bash gh repo create "{vault-basename}" --private \ --source={vault} --remote=origin --push \ --description="Personal LLM Wiki / second brain for {Project} work (Karpathy pattern)" ``` If `gh` isn't available or auth fails, skip silently and tell the user how to do it manually: > Skipped GitHub creation. To do it later: `cd {vault} && gh repo create {vault-basename} --private --source=. --remote=origin --push` ### Step 6.5 — Add a Knowledge Vault section to the project's CLAUDE.md Look for an existing `CLAUDE.md` at the **project path** (not the vault path) — this is the file Claude auto-loads on every session in that project. Adding a short section makes the vault discoverable to anyone reading it. Ask the user (default Yes): > Add a "Knowledge Vault" section to `{project-path}/CLAUDE.md`? \[Y/n\] If they accept: - **If `{project-path}/CLAUDE.md` exists** and does NOT already contain a `## Knowledge Vault` heading: append the snippet below. - **If `{project-path}/CLAUDE.md` exists** AND already has a `## Knowledge Vault` heading: skip with a note ("project already has a vault section, skipped"). Do not silently rewrite. - **If `{project-path}/CLAUDE.md` does NOT exist**: ask whether to create one with just the vault section. Default Yes. The snippet (substitute `{vault-path}` and `{project-basename}`): ```markdown ## Knowledge Vault A `{project-basename}` vault is registered for this project at `{vault-path}` (Karpathy-style LLM Wiki, Obsidian-compatible). The `vault-keeper` skill (claude-pro-skills) handles read/write rules — see its SKILL.md for the auto-update triggers and the vault's own `CLAUDE.md` for schema rules. The `~/.claude/projects//memory/` files remain session-level scratch (per-conversation feedback) — distinct from the vault's persistent, cross-linked knowledge layer. ``` If the user declines, skip silently. The registry alone is enough for the skill to function. ### Step 7 — Register the vault Update `~/.config/claude-pro-skills/vaults.json`. Create the file + parent dir if missing. ```bash mkdir -p ~/.config/claude-pro-skills if [ ! -f ~/.config/claude-pro-skills/vaults.json ]; then echo '{"vaults":{}}' > ~/.config/claude-pro-skills/vaults.json fi # Add the entry (idempotent — overwrites if key exists): jq --arg p "{project-path}" --arg v "{vault-path}" \ '.vaults[$p] = $v' \ ~/.config/claude-pro-skills/vaults.json > ~/.config/claude-pro-skills/vaults.json.tmp \ && mv ~/.config/claude-pro-skills/vaults.json.tmp ~/.config/claude-pro-skills/vaults.json ``` ### Step 8 — Confirm Tell the user, briefly: ``` ✓ Vault scaffolded at {vault} ✓ Registered {project} → {vault} [✓ Added "Knowledge Vault" section to {project}/CLAUDE.md] [✓ git init + initial commit] [✓ GitHub: github.com// (private)] The vault-keeper skill will now auto-engage on sessions in {project}. Open the vault in Obsidian to browse. Entry point: wiki/index.md. ``` Don't dump the full file tree. The user can `ls` if curious. Bracketed lines are conditional — only include them for steps that actually ran. ## Edge cases - **Project already registered**: ask if they want to overwrite the existing mapping. Default no. - **Vault path exists with content**: ask if they want to use it as-is (skip scaffolding) or pick a different path. - **`gh` not installed / not authed**: skip GitHub silently, tell the user how to do it manually. - **Running outside a git repo and outside any project-like dir**: still allow it; vault doesn't require a project to be initialized for itself. ## Related - `vault-keeper` skill — does the actual reading/writing once the vault exists - `/save-session-to-worklog` — vault-aware; routes worklogs into `{vault}/raw/work-logs//` (per-user subfolder, derived from `git config user.email` or `$CLAUDE_PRO_SKILLS_VAULT_USER`) for any project registered in the vault registry