One sentence to start from scratch a AI-native Obsidian knowledge base—PARA skeleton + AGENTS routing + Bases + AI integration + PKM closed-loop skills, ready to use out of the box.
This is the PKM system'smeta-skill (setup): solidify the best practices of a mature vault into an initialization process that anyone can replicate.
Customer-readable description
What this skill can do
Initialize AI-native Obsidian PKM: create PARA directories, AGENTS rules, templates, Bases, CSS, multiple AI entry points, and connect the soia-pkm-* closed-loop skills
| Customer wants | Skill will do | Customer can see |
|---|---|---|
| Complete the work covered by this skill | Read the user request, necessary context, and this skill's main workflow, and execute the minimal reliable steps | The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt. |
| Missing dependencies, permissions, configuration, or key | Stop actions that require external state, and clearly state what is missing | Install commands, application addresses, configuration paths, or questions requiring customer confirmation |
| Execution complete | Summarize successes, skips, failures, file changes, and verification results | A completion receipt that can be copied into a ticket/log |
How the customer uses it
- State the goal in natural language, and provide the necessary inputs: files, URL, repo, workspace, proposal, vault, or platform account status.
- The Agent first determines whether this skill is triggered, then checks dependencies, configuration, permissions, and risky actions.
- For actions that can be dry-run or previewed, provide a preview first; when deletion, overwriting, sending, publishing, or writing remote state is involved, ask the customer for confirmation first.
- After execution, verify the real output; do not substitute "looks successful" for evidence.
- The final reply must give the customer a visible summary: what was done, log summary, file changes, issues, and next steps.
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-bootstrap -y
Configuration conventions:
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-bootstrap/config.yml
SOIA_PKM_BOOTSTRAP_CONFIG_FILE=<custom-config-path>
- If this skill does not need private configuration, you may skip creating
config.yml。 - If an API key, cookie, session, provider home, or local path is needed, it can only be placed in private
config.yml, the process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs. - Strong dependencies, optional dependencies, and third-party skill relationships must be based on this
SKILL.mdThe subsequent "dependencies / prerequisites / resources / boundaries" description shall prevail; if it is not clearly written, first supplement the description or ask the customer, do not guess. - Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.
Logs and completion receipt
Every execution must let the customer see the process and results. Minimum receipt format:
完成：<一句话说明本次完成了什么>。
日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>
文件变化：
- <绝对路径或“未改动文件”>
验证：
- <运行过的检查、命令或人工核对点>
问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>
Initialization process (5 steps + 1 optional)
Step 1 — Install Obsidian and necessary configuration
- Download (free):https://obsidian.md/download
- Version requirement: 1.9+ (built-in Bases Database functionality, the core of this system)
- Enable: Settings → Core plugins → Confirm Bases is available
Step 2 — Build the vault skeleton
python3 scripts/init_vault.py <目标 vault 路径>
python3 scripts/init_vault.py <目标 vault 路径> --config <你的配置.json>
Idempotently create: directory skeleton, each area's AGENTS.md, article templates,.obsidian/snippets/wide-page.css, user manual, multi-AI entry files. Existing files are not overwritten by default.
Directories and seed files come from scripts/default_config.json, do not modify the script to hardcode personal needs. When customization is needed:
python3 scripts/init_vault.py --print-default-config > my-vault-config.json
# 修改 my-vault-config.json 后：
python3 scripts/init_vault.py <目标 vault 路径> --config my-vault-config.json
Configuration supports JSON (zero dependencies) and YAML (requires PyYAML installed locally).scripts/example_custom_config.json demonstrates how to add/remove directories and replace a seed file.
Step 3 — Connect multiple AIs
AGENTS.md is the single source of rules; other entries only adapt, they do not establish a separate set of specifications.
| AI | Entry | 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 gemini skills or shared ~/.agents/skills/ |
| Antigravity CLI | AGENTS.md / GEMINI.md |
Keeps existing rule files; global skills are located in ~/.gemini/antigravity-cli/skills/, workspace skills are located in .agents/skills/ |
| opencode | OPENCODE.md / opencode system prompt |
Reads back AGENTS.md, suitable for collaboration within Obsidian/CLI |
| workbuddy | WORKBUDDY.md / .workbuddy/memory/ |
Memory only stores long-term facts, it does not replace vault body text |
skill cross-agent installation conventions:
- Claude Code →
~/.claude/skills/ - Codex →
~/.codex/skills/ - Antigravity CLI → global
~/.gemini/antigravity-cli/skills/；workspace.agents/skills/ - Gemini / opencode / workbuddy etc. → prefer shared
~/.agents/skills/
AI directly reads and writes the vault's .md files,does not depend on Obsidian plugins。
Obsidian embedded AI plugins(for people not used to the terminal)
- Tars(community plugin): connects to Kimi / Claude / OpenAI API, in-note
#Kimi :triggers inline generation - Terminal(polyipseity): runs AI CLI inside Obsidian, directly operates on vault files
Step 4 — Install the PKM closed-loop skills
npx skills add soia-team/soia-open-skills # soia-pkm-clip-x / distill / maintain / …（自建）
npx skills add Tencent/WeChatReading # weread（读书线，可选）
Third-party skill integration guidelines:
| Third-party skill | Relationship to bootstrap |
|---|---|
weread-skills (Tencent/WeChatReading) |
Optional integration: only install when the user wants to enable WeChat Reading sync / reading data enhancement |
huashu-weread-advisor |
Optional upper-layer advisor: not a dependency for initializing the vault |
book-to-skill |
Non-dependency: can be used independently to convert books/documents into skills |
find-skills |
Non-dependency: can be used independently to discover/install skills |
bootstrap itself is only responsible for initializing the vault skeleton and installing the self-built SOIA skill; it must not modify third-party skill files.
Closed loop:clip-*(收) → organize(整理) → distill(点) → compose(写) → publish(发)
Support:soia-pkm-maintain(weekly maintenance lint + briefing; automatic session log integration see Step 6, optional)
Step 5 — Verify
Tell the AI 归档这条 X：<URL>, confirm it lands in the article excerpt directory in your configuration; then say 给这篇补我的看法 to run a distillation. Once the closed loop works, initialization is complete.
Step 6 — Integrate session logs (optional)
After installing the PKM skills, ask the user whether to integrate AI session logs—automatically append a snapshot of each session's changes to your configured log directory:
- Must obtain user consent first, do not silently change the configuration
- Claude Code scenario: add to
.claude/settings.jsonAddSessionEndhook - Codex scenario: modify
config.toml's notify wrapper - For specific steps see the
soia-pkm-maintainskill'sreferences/session-log-setup.md
Obsidian Plugins / Configuration Checklist
| Type | Plugin / Feature | Required? | Purpose |
|---|---|---|---|
| Core | Obsidian 1.9+ | ✅ | — |
| Core | Bases | ✅ | Database views (book library / article library) |
| CSS | wide-page.css(bundled with this skill) |
Recommended | Fill the editor width |
| AI CLI | Codex / Claude Code / Gemini CLI / Antigravity CLI / opencode / workbuddy | Recommended | Multiple AIs operate directly on the vault |
| AI | Tars (community) | Choose one of the two | Connect to AI within Obsidian |
| Version | Obsidian Git (community) | Optional | vault version control |
This system does not use Dataview(uses Bases),does not strongly depend on Templater(the built-in templates are sufficient).
Reference Implementation
The reference implementation of this skill should use a sanitized example vault; for local verification you can use init_vault.py to run a minimal skeleton, and do not write personal vault names or local paths in the open-source documentation.
Workflow from Zero to Publishing
After initialization is complete, the full path is:
clip-*(收集) → organize(清洗/归类/MOC) → distill(用户观点) → compose(草稿) → publish(平台适配/发布留底) → vault 周维护
Prompt Template Principles:
- Have the user provide the vault path, GitHub private repository, research field, output platform, and available AI.
- Check the environment first, then create directories; do not skip verification.
- Explicitly require the AI to establish
AGENTS.md+ multi-AI adapters, rather than scattering the rules across various tools. - Require that materials retain the original text and sources, and that opinions contain only the user's own.
- The final output should include what is completed, what is not completed, what the user needs to do manually, a knowledge map, weak areas, and next-step suggestions.
Deliverables
A usable vault + integrated multi-AI + PKM closed-loop skill. Afterward, just tell the AI "archive this X", "organize the topic map", "add my views to this piece", "write these views into an article", or "publish this piece" to run the closed loop.
Completion Receipt
After execution,you mustoutput to the user (do not silently finish):
- What was done — a one-sentence summary of the completed work.
- File changes — list the files created / modified / moved (full paths); if no files were changed, state "no files changed".
- Next steps — optional follow-up suggestions (such as the next skill to connect to).