SuperAPI AI Directory

soia-pkm-bootstrap-vault-base

General & other

View repository

Updated 10-16 08:46

About this skill

soia-pkm-bootstrap-vault-base

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 as 10_主题知识、20_规范与手册、30_学习指南, historical imports use 90_历史导入。
  • The default metadata directory is consistent with the current SOIA vault conventions, using 00_Obsidian系统/; the workspace inbox uses 10_工作台/00_Inbox/. The old name 00_知识库系统/、00_收件箱/ is no longer created by the default configuration; existing vaults with different naming should be explicitly preserved via custom config.
  • Establish AGENTS.md as 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

  1. Provide the target directory, language/naming preferences, and whether to inherit the default structure.
  2. First run plan, and review create/skip/conflict/drift item by item.
  3. After client confirmation, add --apply; existing files are skipped by default.
  4. 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 use 10_保险、20_读书、30_工作、40_技术、50_日记、60_生活、70_写作、80_学习、90_资源. Existing old 10_融合分类/ 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 use 20_资料库/主题 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,.base views, 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:

  1. The default invocation only outputs a plan and the directory does not exist.
  2. --apply creates the skeleton, but .obsidian/。
  3. After modifying a create-only file, run --applyagain, and the content remains unchanged.
  4. --check can report missing items and managed drift.
  5. ../escape, absolute paths, and target type conflicts all fail.