soia-pkm-organize-article-moc

The PKM closed loop'sorganizing step: turn messy collections into structured, searchable, aggregatable knowledge. Specifically addresses "a big pile of archives sitting in a black hole, never 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, and add bidirectional links. Under the hood it calls scripts such as rebuild_moc.py / backfill; at the upper layer it uses an LLM to determine categorization. Used to activate existing collections and organize new archives

The client wants	The skill will do	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 minimal reliable steps	The client will see Obsidian/vault file changes, terminal logs, generated artifact paths, and a final receipt.
Missing dependencies, permissions, configuration, or keys	Stop actions that require external state and clearly state what is missing	Install commands, application addresses, configuration paths, or questions requiring client 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 client uses it

State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek client confirmation first.
After execution, verify the real output; do not substitute "looks successful" for evidence.
The final reply must give the client a visible summary: what was done, a 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-article-moc -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-organize-article-moc/config.yml
SOIA_PKM_ORGANIZE_ARTICLE_MOC_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 may only go into a 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.
Hard dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md 's subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly stated, add the description first or ask the client—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)

For any task of "organizing / restructuring a 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 structure/conventions/templates, and when similar items are found, merge them in rather than starting a new set) → then propose the minimal plan for the user to decide → only execute in bulk after confirmation。

The procedure isexternal configuration, decoupled from this skill— to change the procedure, change that yml; do not hardcode it in this document. Core red lines: acting without first investigating will inevitably cause rework; starting a new set when a mature existing structure already exists is reinventing the wheel; empty templates / guessing at categories / generating everything in one bulk pass and then having the user pick out errors are all wasted effort.

What to do

Fill in frontmatter: fill in missing topics / captured_at / author .
Topic categorization: read the article content and determine which topics(bidirectional links) it should be attached to;prioritize reusing existing topics(check _MOC/), to avoid creating duplicate topics.
Create / update MOC: run rebuild_moc.py to rebuild the two-level topic map (first-level category → second-level topic).
File by month：clip natively lands in <年>/, file articles into <年>/<月>/。
Add bidirectional links: associations between articles, and article ↔ book ↔ journal.

Underlying scripts (mechanical layer, called by organize)

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

organize = LLM determines categorization / summary + mechanical-layer scripts execute in bulk. Scripts handle deterministic batch 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/); do not create new topics lightly.
The mapping is hardcoded in rebuild_moc.py 's category table (do not rely on AI guessing each 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 brings things in (possibly messy, landing in the year root directory);organize organizes; downstream distill distills on the organized vault.

Report back after completion

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

What was done — a one-sentence summary of the completed work.
File changes — list the created / modified / moved files (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).