richfrem Obsidian Init (Vault Onboarding)
Status: Active Author: Richard Fremmerlid Domain: Obsidian Integration
Purpose
This skill is the entry point for any project adopting Obsidian. It handles:
- Verifying (and guiding installation of) prerequisites
- Initializing the vault configuration
- Setting up exclusion filters
- Validating the vault is ready for agent operations
Phase 1: Prerequisites Installation
1.1 Obsidian Desktop Application (Required)
The Obsidian desktop app must be installed on the host machine. It is the visual interface for browsing, editing, and viewing the Graph and Canvas.
macOS (Homebrew):
brew install --cask obsidian
Manual Download:
Verify:
ls /Applications/Obsidian.app
1.2 Obsidian CLI v1.12+ (Recommended)
The official CLI communicates with a running Obsidian instance via IPC singleton lock. It enables programmatic vault operations (read, search, backlinks, properties).
npm (global install):
npm install -g obsidian-cli
Verify:
obsidian --version
Note: The CLI requires an active Obsidian Desktop instance to communicate with. It operates in "silent" mode by default. For headless/CI environments where Obsidian is not running, our
vault_ops.py(fromobsidian-vault-crud) handles direct filesystem operations without requiring the CLI.
1.3 ruamel.yaml (Required for CRUD Operations)
Lossless YAML frontmatter handling requires ruamel.yaml:
pip install ruamel.yaml
1.4 Optional Community Plugins
For advanced vault features, install these from within the Obsidian app:
| Plugin | Purpose | Required For |
|---|---|---|
| Dataview | Database-style queries over frontmatter | Structured metadata queries |
| Canvas (built-in) | Visual boards with JSON Canvas spec | obsidian-canvas-architect skill |
| Bases | Table/grid/card views from YAML | obsidian-bases-manager skill |
Phase 2: Vault Initialization
Interactive Init
python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py --vault-root <path>
With Custom Exclusions
python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py \
--vault-root <path> \
--exclude "custom_dir/" "*.tmp"
Validate Only (No Changes)
python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py --vault-root <path> --validate-only
What It Does
- Validates the target directory exists and contains
.mdfiles - Creates the
.obsidian/configuration directory (if not present) - Writes
app.jsonwith sensible exclusion filters for developer repos - Updates
.gitignoreto exclude.obsidian/(user-specific config) - Reports next steps for opening the vault in the Obsidian app
Phase 3: Exclusion Configuration
Default Exclusions
| Pattern | Reason |
|---|---|
node_modules/ |
NPM dependencies |
.worktrees/ |
Git worktree isolation |
.vector_data/ |
ChromaDB binary data |
.git/ |
Git internals |
venv/ |
Python virtual environments |
__pycache__/ |
Python bytecode cache |
*.json |
Data/config files (not knowledge) |
*.jsonl |
Export payloads |
learning_package_snapshot.md |
Machine-generated bundle |
bootstrap_packet.md |
Machine-generated bundle |
learning_debrief.md |
Machine-generated bundle |
*_packet.md |
Audit/review bundles |
*_digest.md |
Context digests |
dataset_package/ |
Export artifacts |
Why Exclude Machine-Generated Files?
These are giant concatenated snapshots produced by bundler/distiller scripts. Indexing them in Obsidian would pollute the graph with thousands of false backlinks pointing into machine-generated text, not human-authored knowledge.
Phase 4: Post-Init Steps
- Open Obsidian → Click "Open Folder as Vault" → Select vault root
- Verify indexing → Check that
01_PROTOCOLS/,ADRs/, etc. appear in sidebar - Test wikilinks → Click any
[[link]]to confirm navigation works - Set VAULT_PATH →
export VAULT_PATH=/path/to/vault
Portability Note
This skill is project-agnostic. It works on any Git repository with markdown files. The exclusion filters are sensible defaults for developer projects. When reusing this plugin in other projects, simply run the init script with the new project's root path.
Quick Reference: Full Install Sequence
# 1. Install prerequisites
brew install --cask obsidian # Desktop app
npm install -g obsidian-cli # CLI tools
pip install ruamel.yaml # Lossless YAML
# 2. Initialize vault
python plugins/obsidian-integration/skills/obsidian-init/scripts/init_vault.py \
--vault-root /path/to/your/project
# 3. Set environment variable
export VAULT_PATH=/path/to/your/project
# 4. Open in Obsidian app
open /Applications/Obsidian.app