soia-pkm-bootstrap-vault-obsidian

In soia-pkm-bootstrap-vault-base . Markdown, YAML frontmatter, and Git (if enabled) remain the source of truth for content.

Customer-readable description

What this skill can do

Check whether the Obsidian client is available; version information must be based on the local machine or current official information.
Dry-run preview and structured merge of core-plugins.json、appearance.json and optional app.json, compatible with both the newer object format and the older list format of core plugins.
Preserve unknown core plugins, themes, snippets, and JSON keys; do not overwrite the customer's existing configuration when enabling Bases and wide-page CSS.
Add three create-only .base views for the workbench, curated long-term knowledge, and workbench history; existing views are always preserved.
Back up existing files that will be modified before apply; support --check acceptance.

This skill does not create a PARA skeleton, does not replace base, and does not write Obsidian data back to other cloud knowledge bases.

How customers use it

Other recognizable phrasings include "configure Obsidian", "install Obsidian plugins", "Obsidian-specialized configuration", and "enable Bases"; when building a generic vault skeleton from scratch, first use soia-pkm-bootstrap-vault-base。

First initialize with base or confirm an existing Markdown vault; base does not write .obsidian。
Provide the vault path, and first run the script with the default dry-run.
Show the JSON merge and CSS create/drift list, and after the customer confirms, add --apply。
Run --check, then open Bases and a regular note in Obsidian to verify.

Dependencies and installation

Install this skill (a hard dependency will also require base):

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear as two indexes and drift separately, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-bootstrap-vault-obsidian -y

This skill does not require credentials or private configuration; the target is passed in via the CLI.

External installation entry points:

Obsidian download:https://obsidian.md/download
Version recommendation: 1.9+, subject to the current official version and local system support.

WorkBuddy is loaded as a role-based expert rather than a plugin,npx skills add -a '*' does not cover it, and it must be installed separately; see docs/install/workbuddy.md。

Logging and completion receipt

The receipt must at least state: run mode, backup category, create/update/skip/drift for Bases/CSS/link format,--check results, and manual client verification. Do not print accounts, tokens, or private JSON values.

Private information and intermediate data

This skill does not require an account or credentials. Backups contain only the Obsidian configuration files that will be modified in this round and remain in the customer vault's hidden platform directory; logs report only key/list categories and counts, and do not print full private JSON values.

Configuration workflow

1. Install Obsidian

From the Obsidian official download page , install the desktop client and sign in (if the user needs account capabilities such as sync or community plugins). There is no need to write account credentials into the vault or skill configuration just to open a local Markdown vault.

2. Run generic initialization

General layer commands:

python3 <path-to-base-skill>/scripts/init_vault.py <vault-path>

After confirming the plan:

python3 <path-to-base-skill>/scripts/init_vault.py <vault-path> --apply

base v2 never creates .obsidian; platform configuration is only executed in this skill.

3. Preview and apply safe merge

# 默认 dry-run
python3 scripts/configure_obsidian.py <vault-path>

# 确认后应用；现有配置先备份
python3 scripts/configure_obsidian.py <vault-path> --apply

# 可选：显式设置 link format；不传则保留现值
python3 scripts/configure_obsidian.py <vault-path> --link-format relative --apply

# 验收
python3 scripts/configure_obsidian.py <vault-path> --check

The script enables Bases by default, three create-only .base views and wide-page snippet. JSON only adds missing items and preserves all unknown keys/list members. If existing CSS differs from the bundled version, it reports drift and skips; only after the customer has reviewed the overwrite plan and explicitly authorized it can --force-managed --apply。

Default manifest:

Type	Item	Required?	Purpose
Core	Obsidian 1.9+	Yes	Open and edit a local Markdown vault
Core plugin	Bases	Recommended/as needed per view	Database views such as library and article library
Content view	Workbench/repository/history `.base`	Recommended/as needed per view	Aggregate current status, long-term knowledge, and history from frontmatter
CSS snippet	`wide-page.css`	Recommended	Fill the editor width; provided by this Obsidian-specialized skill
AI CLI	Codex / Claude Code / Gemini CLI / Antigravity CLI / opencode / workbuddy	Recommended	Read and write local Markdown directly
Community plugin	Tars	Optional	Call AI within Obsidian
Community plugin	Terminal	Optional	Run AI CLI within Obsidian
Community plugin	Obsidian Git	Optional	Provide Git version control for the vault

This system does not use Dataview and does not strongly depend on Templater; the default templates and frontmatter are sufficient to run the general closed loop. Before installing community plugins, first verify the author, permissions, and local security policy.

4. Backup and rollback

The pre-modification copy is located at .obsidian/.soia-backups/<timestamp>/, and includes only the Obsidian configuration files that will be modified in this round. When rolling back, first close Obsidian, then precisely restore that batch of files; do not delete the entire .obsidian。

5. Verification

First run --check; then in Obsidian open a Markdown note and a .base view, and check frontmatter, wikilinks, Bases, and wide-page styling. Finally, confirm that unknown plugins, themes, and settings are still preserved.

Completion receipt

After execution, output:

The Obsidian version checked or installed.
The status of Bases, CSS snippets, and optional plugins.
File changes in the vault that are only platform configuration.
The verification results of actually opening articles and views.
Steps the user needs to complete according to the current client interface; if none, write "None".