soia-pkm-bootstrap-vault-base

Initialize an AI-native knowledge base with a knowledge-base-neutral Markdown skeleton: PARA directories, AGENTS routing, templates, multi-AI entry points, and PKM closed-loop skills. Platforms such as Obsidian and Tencent ima only consume local Markdown; platform-specific configuration is handled by the corresponding skill.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Build a local Markdown knowledge base from scratch	Create the PARA skeleton, per-area rules, templates, and usage manual according to the configuration	Directories, rule files, templates, and terminal summary
Let multiple AIs share one set of rules	Create multi-AI adapters and let `AGENTS.md` remain the single source of truth	Entry files and rule routing for each entry point
Connect the PKM closed loop	Install or check SOIA skills such as clip, organize, distill, compose, and publish	Installation results, missing dependencies, and follow-up commands

This skill is not responsible for installing or configuring Obsidian, nor for uploading content to ima. When these capabilities are needed, continue using soia-pkm-bootstrap-vault-obsidian or soia-pkm-bootstrap-vault-ima。

How customers use it

Provide the target vault path, and state whether to use the default JSON configuration or your own JSON/YAML configuration.
When running the initialization script for a general Markdown knowledge base, use --no-obsidian, skipping the .obsidian/** artifacts in the default configuration.
Check the generated directories, rules, and templates, then connect the required AI and PKM skills.
When Obsidian is needed, let soia-pkm-bootstrap-vault-obsidian handle platform configuration after base is complete; when ima is needed, let soia-pkm-bootstrap-vault-ima handle cloud consumer-side integration.
After execution, verify the actual files and closed-loop examples; do not claim completion based solely on the command exit code.

Dependencies and installation

Install this skill:

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

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-bootstrap-vault-base/config.yml
SOIA_PKM_BOOTSTRAP_VAULT_BASE_CONFIG_FILE=<custom-config-path>

This skill has no SOIA-managed hard dependency; the two platform-specific skills declare it as a hard dependency.
weread-skills and huashu-weread-advisor are installed only when the user needs reading sync or enhancement, and are not blocking dependencies for general initialization.
Private paths, API keys, cookies, sessions, and login states can only be placed in the user's own configuration or provider login state.

Logging and completion receipt

Every execution must report: the vault/config used (without printing secrets), the categories of directories and files created or skipped, skill installation results, verification commands, failure reasons, and next steps. When local resources are involved, report only the target location already provided by the user, and do not leak other local paths or private data.

Initialization flow (Step 2–5 + optional Step 6)

Step 2 — Build the knowledge base skeleton

python3 scripts/init_vault.py <目标 vault 路径> --no-obsidian
python3 scripts/init_vault.py <目标 vault 路径> --config <你的配置.json> --no-obsidian

The script idempotently creates the directory skeleton, per-area AGENTS.md, Markdown templates, usage manual, and multi-AI entry files. Existing files are not overwritten by default.--no-obsidian only skips the configuration's .obsidian/** directory and files; when the parameter is omitted, the existing default behavior is kept, making upgrades compatible for existing Obsidian users.

The directory and seed files come from scripts/default_config.json, don't hardcode personal needs into the script. To customize:

python3 scripts/init_vault.py --print-default-config > my-vault-config.json
python3 scripts/init_vault.py <目标 vault 路径> --config my-vault-config.json --no-obsidian

Configuration supports JSON (zero dependencies) and YAML (requires PyYAML installed locally).scripts/example_custom_config.json demonstrates how to add or remove directories and replace seed files.

Step 3 — Integrate Multiple AIs

AGENTS.md is the single source of rules; other entry points only do adaptation and do not establish a separate set of specifications.

AI	Entry point	Description
Codex	`AGENTS.md`	Natively reads root rules and subdirectory rules
Claude Code	`CLAUDE.md`	Reads back `AGENTS.md`, can load `~/.claude/skills/`
Gemini CLI	`GEMINI.md`	Reads back `AGENTS.md`, can use shared `~/.agents/skills/`
Antigravity CLI	`AGENTS.md` / `GEMINI.md`	Keeps existing rule files
opencode	`OPENCODE.md`	Reads back `AGENTS.md`
workbuddy	`WORKBUDDY.md` / `.workbuddy/memory/`	Memory stores only long-term facts and does not replace vault body text

AI directly reads and writes the vault's .md files, without taking any platform plugin as a prerequisite for the common layer. Skill installation conventions: Claude Code uses ~/.claude/skills/, Codex uses ~/.codex/skills/, other agents preferentially share ~/.agents/skills/。

Step 4 — Install the PKM closed-loop skills

npx skills add soia-team/soia-open-skills
npx skills add Tencent/WeChatReading  # 仅在需要读书线时

bootstrap itself is only responsible for initializing the local skeleton and installing the self-built SOIA skill; it does not modify third-party skill files.

Closed loop:clip-*(收) → organize(整理) → distill(点) → compose(写) → publish(发). Support:soia-pkm-maintain(weekly maintenance lint + briefing; for automatic session log integration see Step 6).

Step 5 — Verify

Say to the AI 归档这条 X：<URL>, confirm the article lands in the article excerpt directory in the configuration; then say 给这篇补我的看法 to run a distillation once. If the user has not installed the corresponding clip or distill skill, record the missing items and do not write an unexecuted closed loop as completed.

The initialization script's fixture / forward test covers at least two runs: in a temporary directory, run initialization once with --no-obsidian and confirm the common directories and templates exist and that .obsidian/ does not exist; then in another temporary directory, run initialization without that parameter and confirm the default .obsidian/snippets/wide-page.css exists. Run it once more and confirm that existing seed files are skipped rather than silently overwritten.

Step 6 — Integrate Session Logs (Optional)

After installing the PKM skills, first obtain the user's consent, then append a snapshot of each session's changes to the configured log directory:

Claude Code: in .claude/settings.json add SessionEnd hook。
Codex: modify config.toml 's notify wrapper.
For detailed steps see soia-pkm-maintain 's references/session-log-setup.md。

Must not silently modify agent configuration or read private session content.

Workflow from zero to publish

After initialization is complete, the full path is:

clip-*(收集) → organize(清洗/归类/MOC) → distill(用户观点) → compose(草稿) → publish(平台适配/发布留底) → vault 周维护

The prompt should have the user provide the vault path, directory naming preferences, research field, output platform, available AIs, and whether to use the default configuration; require preserving the original text and sources, with opinions written only as the user's own; the final report should cover what was completed, what was not completed, what needs to be done manually, and the next steps.

Deliverables

A usable local Markdown knowledge base skeleton, integrated multi-AI entry points, and PKM closed-loop skills. Obsidian and ima serve only as consumption ends, integrated respectively by the corresponding specialized skills.

Completion receipt

After execution, the following must be output:

What was done: a one-sentence summary.
File changes: categories and locations of newly created, modified, and moved files.
Verification: commands actually run or manual checkpoints.
Next steps: platform specialization, missing dependencies, or customer manual operations; if none, write "None".