soia-pkm-organize-article-moc

soia-pkm-organize-article-moc

PKM closed loop'sorganizing stage: turn messy collections into structured, searchable, aggregatable knowledge. Specifically cures "a big pile of archives lying in a black hole, never activated".

Client-readable description

What this skill can do

Organize the Obsidian article library—backfill frontmatter (topics/captured_at/author), classify by topic bidirectional links, create/update two-level MOCs, file by month, backfill bidirectional links. Under the hood it calls scripts like rebuild_moc.py / backfill; the upper layer uses an LLM to judge classification. Used to activate existing collections and normalize new archives

Client wants	Skill will do	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 key	Stop actions that require external state, and clearly state what is missing	Install command, application address, configuration path, 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

1. State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
2. For actions that can be dry-run or previewed, give a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask the client for confirmation first.

Dependencies and installation

Installation (recommended: install the entire domain plugin and set up all skills in this repo at once):

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

If 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 appear in two indexes and drift separately, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-organize-article-moc -y

Configuration conventions:

~/.config/soia-skills/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 it needs an API key, cookie, session, provider home, or local paths, it can only go into a private config.yml, process environment, or the provider's own login state; it must not be written into the repo, vault body text, or logs.
• Third-party skills can only declare dependencies and installation methods; they do not directly modify third-party skill files.

WorkBuddy loading unit is role-based experts rather than plugins,npx skills add -a '*' does not cover it; it needs separate installation, see docs/install/workbuddy.md。

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-organization protocol (required reading, external configuration)

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

The protocol isexternal configuration, decoupled from this skill——Change the process by editing that yml, do not hardcode it in this document. Core red lines: acting without first investigating will definitely cause rework; starting a separate system when a mature structure already exists is reinventing the wheel; empty templates / guessing categories / one-time batch generation and then having the user pick out errors are all a waste.

What to do

1. Fill in frontmatter: fill in missing topics / captured_at / author .
2. Topic categorization: read the article content and determine which topics(wikilinks) it should be attached to;prioritize reusing existing topics(check _MOC/), to 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 lands in <年>/; file articles into <年>/<月>/by the date in the filename; before executing, first generate a per-file source/target/SHA-256 manifest, and do not use bare mv to guess the target.
5. Add wikilinks: associations between articles, and between articles ↔ books ↔ journals.
6. Index sync: whenever a file/directory is created, moved, renamed, or deleted, rebuild the leaf-level map according to soia-pkm-maintain-vault-health/references/index-sync-contract.md ; when writing to 20_资料库/ , verify the related .base. Article content-only modifications do not refresh the statistics map, but the MOC itself still needs link verification.

Automatic organization contract after single-article archiving

clip-web、clip-wechat-article After archiving a single article, by default continue to invoke this skill to complete the minimal organization loop for that file:

1. Use only the just-archived file as the scope, and fill in the summary,topics、captured_at、author(if it cannot be verified, keep the empty value and report it).
2. Confirm the <年>/<月>/ location by the date in the filename, generate a source/target/SHA-256 manifest, and then move.
3. Rebuild the article MOC; if the path changes, immediately rebuild OB知识库地图, and verify the related Base when writing to zone 20.
4. In the receipt, also provide the archive path, organization path, MOC/map/Base verification, and incomplete items.

When the user explicitly says "archive only" or "do not organize," execute only clip; for batch account/cloud drive imports, by default first collect a manifest, and batch invocation of this skill must be done only after obtaining organization confirmation. Organization failure must not package "archived" as "organized."

Underlying scripts (mechanical layer, called by organize)

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

organize = LLM determines categorization / summary + mechanical-layer script batch execution. The script handles deterministic batch operations; the LLM handles "what topic does this belong to" and "what is the core judgment of this MOC."

Categorization principles

• topics should prioritize reusing existing ones (check _MOC/), and do not casually create new topics; when there is no corresponding MOC note, use plain-text categorization or include it in the unknown-topic report, and do not create empty placeholder notes.
• people is the source attribution glossary; use wikilink only when the person note actually exists; otherwise keep plain text and note that no person page has been created.
• Missing attachments must not be forged into files or patched with fake links: keep the original filename and the "attachment missing" evidence, and distinguish between missing body text, filename matches, and OCR/extraction matches.
• Filenames with dots are first parsed as the complete filename; only when duplicate names or path ambiguity need to be resolved should they be changed to a full-path wikilink with .md , and the alias should be preserved.
• The mapping is hardcoded in the rebuild_moc.py category table (not guessed by AI each time) — to change the categorization, change the table and rerun.

Receipt

After organizing, report: how many articles were processed, which topics were added, the MOC update status, how many files were put in place, and the map updated, statistics, and Base verification results.

Closed-loop position

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

Upstream clip brings them in (possibly messy, landing in the year root directory);organize organizes them; downstream distill distills from the organized library.

---

Receipt after completion

The receipt includes:

1. What was done — a one-sentence summary of the completed work.
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).