Create a platform-neutral Markdown content skeleton and AI collaboration rules..obsidian/, ima, or other consumer-side configurations are handled by their respective specialized skills.
Client-Readable Description
What This Skill Can Do
- Create 00/10/20/30/40/50/60/90 partitions, drill-down
AGENTS.md, workspace Schema v2, long-term knowledge Schema and corresponding templates; the curated catalog in partition 20 is fixed as10_主题知识、20_规范与手册、30_学习指南, historical imports use90_历史导入。 - The default metadata directory is consistent with the current SOIA vault conventions, using
00_Obsidian系统/; the workspace inbox uses10_工作台/00_Inbox/. The old name00_知识库系统/、00_收件箱/is no longer created by the default configuration; existing vaults with different naming should be explicitly preserved via custom config. - Establish
AGENTS.mdas the single rule source and the Claude/Gemini/opencode/workbuddy adaptation layer. - Supports JSON/YAML customization, default plan, explicit
--apply, create-only idempotency and--check。 - does not create
.obsidian, does not install plugins, does not configure hooks, does not delete or overwrite existing files.
How Clients Use It
- Provide the target directory, language/naming preferences, and whether to inherit the default structure.
- First run plan, and review create/skip/conflict/drift item by item.
- After client confirmation, add
--apply; existing files are skipped by default. - Then run
--check, and confirm that required directories and seed files exist.
Dependencies and Installation
Python 3 is a hard dependency; JSON configuration has zero third-party dependencies; YAML configuration additionally requires PyYAML. It is recommended to install the entire soia-pkm-vault@soia plugin.
Install the entire domain (Claude Code and Codex share the same domain plugin):
claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia
Install only this one skill:
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-bootstrap-vault-base -y
WorkBuddy The loading unit is a role-based expert rather than a plugin,npx skills add -a '*' Cannot cover it; it needs to be installed separately, see docs/install/workbuddy.md。
Private Information and Intermediate Data
Default assets do not contain personal data, accounts, credentials, absolute paths, or private project facts. Custom configurations are kept by the client; if they contain private content, do not commit them to a public skill repository.
Logs and Completion Receipts
The receipt must list plan/apply/check modes, create/skip/conflict/drift counts, target category, uncovered files, and the next-step platform-specialized skill.
Commands
# 默认只输出 JSON plan,不创建目标目录
python3 scripts/init_vault.py <vault-path>
# 确认后执行 create-only 初始化
python3 scripts/init_vault.py <vault-path> --apply
# 验证必需骨架;缺失或 managed drift 时非 0
python3 scripts/init_vault.py <vault-path> --check
# 自定义
python3 scripts/init_vault.py <vault-path> --config <config.json>
python3 scripts/init_vault.py --print-default-config
--force --apply Will overwrite seed files, which is a high-risk compatibility option: a per-file overwrite plan must first be displayed and explicit authorization obtained. Normal incremental upgrades should use the lifecycle/document synchronization scheme, not force-reload the entire vault.
Default Structure and Lifecycle
10_工作台Retain only the current state/next step: Inbox, single master control, per-project control plane.- One-off research/audit/decision/execution/acceptance is frozen to 30.
- Knowledge that remains reusable after removing state enters 20's topic knowledge, standard manuals, or learning guides through "source retention, create-only refinement"; historical imported corpora are not automatically regarded as curated knowledge.
- Workspace materials that have ended or been superseded are moved to
90_系统归档/10_工作台历史。 - The partition 20 historical import target is
90_历史导入/; its first-level categories use10_保险、20_读书、30_工作、40_技术、50_日记、60_生活、70_写作、80_学习、90_资源. Existing old10_融合分类/Migration is only allowed via the lifecycle manifest; do not rename bare files during initialization. - Agent logs are divided into
10_自动快照 / 20_精选复盘 / 90_历史导入, and full chats are not stored by default.
The default configuration and seed assets are a modifiable starting point and do not claim that the numeric partitions suit all customers. If the customer already has AGENTS.md or different partitions, read them first and extend with a custom config; create-only will preserve existing rules.
Config Schema v2
{
"schema_version": 2,
"extends_default": true,
"directories": {"add": ["20_资料库/10_主题知识/40_扩展主题"], "remove": []},
"files": {
"add": [
{"path": "20_资料库/10_主题知识/40_扩展主题/AGENTS.md", "mode": "create_only", "content": "# 规则\n"}
]
}
}
- All targets must be vault-relative paths; absolute paths,
..and symlink escapes fail immediately. mode: create_only: skip if it exists;managed: report content drift during check, but still do not overwrite automatically.- When a custom config adds a
20_资料库/semantic directory, a unique numeric prefix must be used; do not use20_资料库/主题unnumbered paths like this. Renaming an existing directory should be converted to a lifecycle manifest, and after completion refresh the map and verify the Base. - CLI > custom config > bundled defaults. Config extension does not require changing public scripts.
- schema v1 can still be read for one compatibility cycle and, after merging, executes with v2 behavior.
Boundaries with other skills
- Obsidian settings,
.baseviews, Bases core plugins and CSS →soia-pkm-bootstrap-vault-obsidian。 - Health check/map →
soia-pkm-maintain-vault-health。 - Workbench/Inbox/archive migration →
soia-pkm-manage-vault-lifecycle。 - Session log hook →
soia-pkm-log-agent-sessions(confirmation is required before changing user configuration). - Read-only search/answer →
soia-pkm-query-vault。 - Extract attachments such as PDF, Word, and spreadsheets before retrieval →
soia-pkm-clip-drive→soia-pkm-query-vault; image body text requires explicit OCR, and a filename match must not be treated as body text. - Distill long-term knowledge from logs, reports, or historical corpora →
soia-pkm-extract-vault-knowledge。
Acceptance
Do a forward test in two temporary directories:
- The default invocation only outputs a plan and the directory does not exist.
--applycreates the skeleton, but.obsidian/。- After modifying a create-only file, run
--applyagain, and the content remains unchanged. --checkcan report missing items and managed drift.../escape, absolute paths, and target type conflicts all fail.