soia-pkm-organize

soia-pkm-organize

of the PKM closed looporganizing step: turn messy collections into structured, searchable, aggregatable knowledge. Specifically addresses "a large pile of archives lying in a black hole that has never been activated."

Client-readable description

What this skill can do

Organize the Obsidian article library—fill in frontmatter (topics/captured_at/author), categorize by topic with bidirectional links, create/update two-level MOCs, file by month, add bidirectional links. The underlying layer calls scripts such as rebuild_moc.py / backfill, while the upper layer uses an LLM to determine classification. Used to activate existing collections and organize new archives

What the client wants	What the skill will do	What the client can see
Complete the work covered by this skill	Read the user request, necessary context, and this skill's main workflow, and execute the minimum reliable steps	The client 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	Installation commands, application addresses, configuration paths, or questions requiring client confirmation
Execution completed	Summarize successes, skips, failures, file changes, and verification results	A completion receipt that can be copied into a ticket/log

How the client uses it

1. State the goal in natural language and provide the necessary inputs: files, URL, repo, workspace, proposal, vault, or platform account status.
2. The Agent first determines whether this skill is triggered, then checks dependencies, configuration, permissions, and risky actions.
3. For actions that can be dry-run or previewed, provide a preview first; when deletion, overwriting, sending, publishing, or writing remote state is involved, seek client confirmation first.
4. After execution, verify the real output; do not substitute "looks successful" for evidence.
5. The final reply must give the client 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-organize -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-organize/config.yml
SOIA_PKM_ORGANIZE_CONFIG_FILE=<custom-config-path>

• If this skill does not require private configuration, you may skip creating config.yml。
• If an API key, cookie, session, provider home, or local path is required, 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.md and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, first supplement the description or ask the client, and 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 client see the process and results. Minimum receipt format:

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

⚠️ Pre-organizing protocol (required reading, external configuration)

Any task of "organizing / restructuring a certain part of the knowledge base" (not limited to the article library),before starting work, first load and strictly follow references/知识库整理规程.yml：First investigate the current state (read-only; understand the user's existing structures/conventions/templates, and when you find similar ones, merge into them rather than starting a new one) → then propose a minimal plan for the user to decide on → only execute in bulk after confirmation.。

The rules areexternally configured and decoupled from this skill—to change the rules, change that yml; do not hardcode them in this document. Core red lines: acting before investigating will definitely cause rework; starting a separate system when a mature structure already exists is reinventing the wheel; empty templates/guessed categories/one-off bulk generation and then having the user pick out mistakes are all wasteful.

What to do

1. Fill in frontmatter: add what is missing topics / captured_at / author .
2. Topic categorization: read the article content and determine which ones it should be attached to topics(bidirectional links);prioritize reusing existing topics(check _MOC/), and avoid creating duplicate topics.
3. Create / update MOC: run rebuild_moc.py to rebuild the two-level topic map (first-level category → second-level topic).
4. File by month：clip natively falls into <年>/, filing articles by filename date into <年>/<月>/。
5. Add bidirectional links: associations between articles, and between articles ↔ books ↔ logs.

Underlying scripts (mechanical layer, called by organize)

• scripts/rebuild_moc.py: scan topics of all articles and rebuild the _MOC/ two-level map. Supports --vault/OBSIDIAN_VAULT to specify the vault path; the category table can use _MOC/.categories.json to override defaults per vault (see script --help）。
• backfill_reading_records.py: book library → reading records completion (reading line).
• File by month:mv <年>/*.md <年>/<月>/(by filename date).

organize = LLM determines categorization / summarization + mechanical-layer scripts execute in bulk. Scripts handle deterministic bulk operations; the LLM handles "what topic does this belong to" and "what is the core judgment of this MOC".

Categorization principles

• Prefer reusing existing topics (check _MOC/), and do not create new topics lightly.
• Mappings are hardcoded in the category table of rebuild_moc.py (do not rely on AI guessing every time)—to change categorization, change the table and rerun.

Receipt

After organizing, report: how many articles were processed, which topics were added, the MOC update status, and how many files were filed.

Closed-loop position

clip(收) → ★organize(整理) → distill(点) → compose(写) → publish(发)

Upstream clip takes things in (possibly messy, landing in year root directories);organize tidies them up; downstream distill distills from the tidied vault.

---

Receipt after completion

After executionmustoutput to the user (do not silently finish):

1. What was done — summarize the completed work in one sentence.
2. File changes — list the files created / modified / moved (full paths); if no files were changed, state "no files changed".
3. Next steps — optional follow-up suggestions (such as the next skill to connect to).