soia-pkm-distill

soia-pkm-distill

Turn "saved items" into "viewpoints." This is the PKM loop 收→整理→点→写→发 from input to outputlifeline link (point)—specifically addresses "save a ton, nothing settles in your head, and the我的看法section stays empty forever."

Customer-readable description

What this skill can do

Refine articles saved in your Obsidian vault into your own viewpoints. Read the original text → Socratic-style, ask one question at a time → you answer aloud → the AI organizes your answers into a "My Take" paragraph (the content is yours; the AI only helps put it into words, and will never think for you or write for you), then gives you a receipt when done. Also supports topic aggregation: distill the viewpoints of multiple articles under one MOC into a single review

What the customer wants	What the skill will do	What the customer can see
Complete the work covered by this skill	Read the user request, necessary context, and this skill's main workflow, then 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 success, 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, URLs, repos, workspaces, proposals, vaults, 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 actual 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-distill -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-distill/config.yml
SOIA_PKM_DISTILL_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 repo, vault text, or logs.
Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, add the description first or ask the customer, and do not guess.
Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.

Logging and completion receipt

Every execution must let the customer see the process and results. Minimum receipt format:

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

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

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

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

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

Core principles (non-negotiable)

The content belongs to the user; AI only helps them ask it out and put it into words—never thinks or writes for them.

AI's responsibility: understand the original text, pose good questions, and organize the user's spoken answers into fluent first-person text.
AI does not: fabricate opinions, take a stance on the user's behalf, or add judgments the user never made.
User didn't answer → don't write. Better to leave it blank than to make things up.

Mode A: Single-article distillation (default)

Triggers: "add my take to this one", "how do I see this one", "distill this one"

Process:

Locate the article. If the user says "this one" = the article involved in the current conversation; otherwise use the filename / title under <vault-articles-dir>/ to find it via Glob/Grep.
Read the original text(read ## 原文 / body paragraphs).
Align on the skeleton: restate the article's core argument in 1–2 sentences so the user can confirm you understood it (and give them a starting point for thinking).
Throw only one question at a time(go through the "three angles" below one by one, and only throw the next after getting an answer): target this article's specific argument, useplain language, and givea one-sentence example answerto lower the barrier.
- ⚠️ Practical lessons (must be followed)：Never throw 3 questions + a table at once—it will directly overwhelm the user, and they won't know where to start answering. One at a time, with examples, and only then can the user answer.
Stop and wait for the user to answer. It's fine if the user is colloquial, answers only one or two sentences, or says "no thoughts" and skips.
After the three angles are asked (or the user says it's enough),organize into text: organize the user's answers into a fluent first-person "My Take". Preserve their views, judgments, and tone; only polish and structure,don't add filler。
Write in: Edit the article's ## 我的看法 section. Empty section / placeholder comment → fill directly; existing content → don't overwrite, ask "append or replace".
Give a receipt(see §A receipt must be given to the user after execution).

Three-angle questioning method (ask one at a time)

Angle	What to ask	Purpose
① Stance	Do youbuythe author's core argument? Does it get to the essence, or is it overstated for traffic?	Force out a clear attitude
② Experience test	Which onematches your experience/observations? Which one is exaggerated/inaccurate?	Test with personal experience
③ Meaning to you	This onechanged what judgment of yours, or made you want to do what？	Move from "read it" to "how do I use it"

Mode B: Topic aggregation

Triggers: "distill topic X into an opinion", "how do I see Agent development as a whole"

Read _MOC/<分类>/<主题>.md to get the article list.
Read each article's ## 我的看法(already-distilled single-article opinions).
Most are empty → Tip: "Only M of the N notes in this topic have had viewpoints distilled; it is recommended to first run Mode A on a few." Let them choose which notes to distill first.
Once you have the material, synthesize it intoan overall judgment(your core view + each note as supporting evidence).
Save to <vault-drafts-dir>/YYYY-MM-DD-<主题>-观点综述.md，tags:[草稿]。
This draft is the input for soia-pkm-compose .

Write boundaries

Only touch ## 我的看法(Mode A) orcreate a newdraft (Mode B). Never touch ## 原文 / ## 摘要 / frontmatter。
Contentmust come from the user's answers; the AI does not make things up.
## 我的看法 is usually left blank for the user; distill is auser-initiated requestto help put words down, and what is written down is still the user's own words.

After execution, you must give the user a receipt

Writing is not the end point. After writing, you must output the result to the user; do not complete it silently:

Where it was written: which note's ## 我的看法(give the filename / path).
Viewpoint summary: restate the view you just wrote in 1–2 sentences so the user can confirm at a glance.
Invite fine-tuning: prompt "This is your viewpoint; tell me which sentence to change."

The topic aggregation mode is the same: tell where the draft was saved and what the core argument is.

Position in the loop

clip-*(收) → organize(整理) → ★distill(点：收藏→观点) → compose(写) → publish(发)

Upstream:soia-pkm-clip-* archives the notes in.
Downstream:soia-pkm-compose turns the viewpoints produced by distill into a finished piece.
MethodologyReference huashu-weread-advisor 's alchemy (the reading line's highlighting → note distillation) — distill is its counterpart on thenote line. Only borrow the method; do not modify its files (third-party skill).

Relationship with third-party skills

Third-party skill	Relationship to `soia-pkm-distill` relationship
`huashu-weread-advisor` (`alchaincyf/huashu-weread`)	Method reference: borrows alchemy's questioning and distillation approach, but this skill does not call it or require it to be installed
`weread-skills` (`Tencent/WeChatReading`)	Non-dependency: this skill processes vault notes and does not directly read the WeRead API
`book-to-skill`	Non-dependency
`find-skills`	Non-dependency