SuperAPI AI Directory

soia-pkm-bootstrap-vault-ima

General & other

View repository

Updated 10-16 08:49

About this skill

soia-pkm-bootstrap-vault-ima

Connect an existing local Markdown vault to Tencent ima (ima.qq.com) as the cloud consumer end. The sync direction is vault → ima; local Markdown, frontmatter, directories, and Git (if enabled) are the sole source of truth, and content in ima does not overwrite the vault in reverse.

Customer-readable explanation

What this skill can do

What the customer wants What the skill will do What the customer can see
Search vault content in ima Establish the sync scope and directory mapping, and connect to the specified ima knowledge base Mapping table, sync scope, and verification results
New articles automatically enter ima Guide the use of the official ima Skills local folder monitoring capability Monitored source directory, target knowledge base, and first sync receipt
Keep local content as the source of truth Clarify one-way sync and exclusions Will not perform ima → vault reverse sync

This skill is not responsible for creating a vault from scratch, nor does it fabricate button names, menu paths, or undocumented APIs of the ima client. The specific ima UI operations have not been tested in this session; on first execution, the actual client interface must prevail and this document must be corrected accordingly.

How the customer uses it

  1. Provide the existing vault path, the relative directories to sync, the target ima knowledge base, and the title of one article for verification.
  2. Install and log in to the ima client.
  3. First determineIt cannot be the vault root or the entire 20 zonedirectory allowlist, and complete the sensitivity-level precheck, then configure local folder monitoring in the official ima Skills.
  4. For the first sync, select only one article or a small directory, and expand the scope only after confirming the hierarchy, title, and body.
  5. Verify the article by searching in ima; in any conflict, local Markdown prevails, and do not write back from ima in reverse.

Dependencies and installation

Install this skill (the 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 have two indexes and each will drift, so it is recommended to choose only one:

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

Configuration conventions:

~/.config/soia-skills/soia-pkm-bootstrap-vault-ima/config.yml
SOIA_PKM_BOOTSTRAP_VAULT_IMA_CONFIG_FILE=<custom-config-path>

Official entry point:

  • ima official website and client download entry point:https://ima.qq.com/
  • ima's Skills, local folder monitoring, and knowledge base interface will change with the client version; untested parts are marked as “subject to the actual ima client interface, and this document will be corrected on first execution.”

WorkBuddy The loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and it needs to be installed separately, see docs/install/workbuddy.md。

Logs and completion receipt

The receipt must at least include: client login check, target knowledge base and local allowlist (write only relative directories), first sync scope, success/skipped/failed counts, retrieval verification results, and UI steps that still require manual correction by the user. Do not print accounts, tokens, private file contents, or local absolute paths.

Connection process

1. Install the client and log in

Open ima official entry point, install the desktop client and log in. The official website currently provides an "Open desktop version" and a client download entry; the specific installation prompts are subject to the official page and the local system.

2. Create a knowledge base and define the directory mapping

Create a knowledge base in the ima client for consuming vault content. The specific creation actions and field names have not been tested,and are subject to the actual ima client interface; correct this document on first execution。

Only allow a subdirectory allowlist that the user explicitly selects and that can continuously be guaranteed not to mix in sensitive notes. The entire vault, the entire 20_资料库/ or the historical import tree are not valid sync sources:

vault relative directory/category Default recommendation Reason
20_资料库/<精选子目录>/<明确云端范围>/ Conditional sync Every Markdown file in the directory has sensitivity: public or internal, and the user confirms it can be uploaded
20_资料库/、20_资料库/90_历史导入/, other historical import directories Prohibited The root scope is too broad; imported corpora may contain credentials, personal paths, and unverified content
40_图书视频馆/ Excluded by default May contain personal reading records, family information, or original text subject to copyright restrictions
Confirmed uploadable published archive subdirectory Optional sync Only sync content that the user explicitly selects and that has completed privacy/copyright review
00_Obsidian系统/、.obsidian/ Exclude Platform configuration is not knowledge body text
30_日志与思考/、10_工作台/ Excluded by default May contain conversations, drafts, and temporary private content
.git/、.env, configuration/credential files Must exclude Version data, keys, and local state should not be uploaded

Path allowed does not equal content allowed. Run the fail-closed precheck first; it only outputs relative paths, counts, and risk codes, not matched values:

python3 scripts/preflight_sync.py --vault <vault-path> \
  --path-prefix '20_资料库/<精选分类>/<明确云端范围>'

Missing/illegal sensitivity, value is private/restricted, suspected credentials/private absolute paths, symlinks, or unclassifiable attachments will all cause ready=false. Copyright and business authorization still require manual review. Pause when there is no clear scope or when it cannot be guaranteed that future newly added files follow the same rules; do not enable monitoring.

The mapping record must contain at least:

本地 vault/<相对目录>  →  ima/<知识库>/<对应目录>
同步方向:vault → ima
排除:.obsidian/、.git/、.env、私密目录、未确认的日志/草稿

3. Configure local folder monitoring for ima official Skills

In ima's official Skills capabilities, select the local folder monitoring/knowledge base import type capability, and map the local allowlist directory from the previous step to the target knowledge base. The specific Skill name, authorization prompt, monitoring switch, knowledge base selection, and directory mapping UI have not been tested and must be subject to the actual ima client interface; correct this document on first execution; do not guess buttons or menu paths based on this skill.

Hard gate for first configuration:

  1. Run the precheck and output the relative directory allowlist, file count, sensitivity level distribution, and rejected items; it must ready=true, and the report must not contain body text or secret values.
  2. Select only one test subdirectory that has passed the precheck, do not select the 20_资料库/ root directory.
  3. First import one Markdown file with sensitivity: public , then observe whether ima preserves the title, body text, relative hierarchy, and searchable text.
  4. Only after confirming the monitoring scope, target knowledge base, and sync direction, expand to the full allowlist; re-run the precheck when expanding.
  5. If the official Skills are unavailable in the current client, record the version and missing capabilities and stop automatic syncing; do not arbitrarily switch to a third-party watcher or build your own reverse sync.

4. Verify Retrieval

Select a local vault article, record its title and a non-sensitive unique phrase. After the first import/indexing completes, search for the title or phrase in the ima target knowledge base, and verify that the hit content matches the local Markdown. If there is no hit, troubleshoot in the order of "monitoring scope → target knowledge base → index wait → file format/permissions", and write untested UI differences into the receipt.

5. Boundaries and Conflict Handling

  • The local Markdown vault is the single source of truth; ima is only the cloud consumption end.
  • Only the vault → ima sync convention is allowed; this skill does not perform ima → vault reverse sync.
  • Summaries, tags, reordering, or AI-generated content in ima must not automatically overwrite the local body text.
  • Before changing the sync scope, pause monitoring first and review the exclusion list, especially .env, private directories, session logs, and unpublished drafts.
  • After directory monitoring is enabled, newly added notes will also enter the cloud scope; the most recent AGENTS.md of that directory must explicitly allow only public/internal, otherwise continuous monitoring must not be enabled.

Completion Receipt

After execution, output:

  1. Client login and target knowledge base status.
  2. The mapping from local relative directories to the ima knowledge base and exclusions.
  3. Whether the official Skills monitoring configuration is complete; mark each untested UI step item by item.
  4. The retrieval verification result of one article in ima.
  5. Residual risks: indexing delay, permissions, version differences, and reverse sync not performed; if none, write "none".