soia-pkm-transform-article-learning

soia-pkm-transform-article-learning

Convert archived or specified articles into learning-oriented or interactive outputs: quizzes, flashcards, mind maps, podcast scripts, and study notes, prioritizing NotebookLM and falling back to local Markdown.

Customer-readable description

What this skill can do

Convert Markdown / vault articles or URLs into learning outputs:

• Quiz: multiple-choice questions + short-answer questions + answer explanations
• Flashcards: Anki-compatible two-sided cards
• Mind map: Mermaid / Markdown hierarchical structure
• Podcast script: conversational audio script
• Study notes: NotebookLM comprehensive summary

Customer wants	Skill will do	Customer can see
Generate quiz	Local Markdown or NotebookLM quiz artifact	Number of questions, question type distribution, file path
Make flashcards	Anki-compatible Markdown or NotebookLM flashcards	Number of cards, file path
Mind map / podcast	Mermaid mind map / dialogue script Markdown	File path, number of nodes / word count
Upload to NotebookLM	Upload source files, record notebook id	notebook id / artifact path
Execution complete	Acceptance: output structure is complete, and the number of questions and answers matches	Completion receipt

How customers use it

1. Specify the source (URL / vault path / local Markdown) and target type (quiz/flashcards/mind map/podcast, optional).
2. Optional: specify provider (local / notebooklm), number of questions, number of cards, difficulty.
3. For URL sources, clip and archive first, then convert.

Dependencies and installation

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-transform-article-learning -y

• Local solution: no additional dependencies (generates Markdown)
• NotebookLM (optional): see references/provider-notebooklm.md

Logs and completion receipt

完成：<一句话>。

日志摘要：
- source: <路径或 URL>
- artifact_type: quiz | flashcards | mindmap | podcast | notes
- provider: local | notebooklm
- content_mode: learning
- output: <文件路径或 notebook id>
- count: <题数 / 卡片数 / 节点数>

验证：
- 文件存在且可读
- 题目数 == 答案数（quiz/flashcards）
- 脑图 Mermaid 可解析（mindmap）
- prompt 已落盘可重跑

问题与下一步：
- <无 / provider 降级原因 / NotebookLM 失败目标列表>

Boundaries

• Default learning mode: structural reorganization, extraction of core knowledge points, without compressing core key points.
• quiz/flashcards: number of questions == number of answers == number of explanations; acceptance must ensure all three match.
• prompt is written to disk at outputs/transform/<YYYY>/<stem>/prompts/。
• NotebookLM is an optional provider; when missing, fall back to local Markdown generation and do not stop the task.
• Record each failed NotebookLM artifact item by item (must not silently skip).

Workflow

1. Confirm source → for URLs, clip first.
2. Determine artifact_type：quiz(default) / flashcards / mindmap / podcast / notes。
3. Select provider: user-specified > configuration > local Markdown.
4. NotebookLM path: run a health check first (references/provider-notebooklm.md), then upload source files, record notebook id, and generate the corresponding artifact.
5. Local path: read references/prompt-notebooklm.md corresponding section to generate the prompt, and output Markdown.
6. Generate output to outputs/transform/<YYYY>/<stem>/, prompt persisted to disk.
7. Acceptance: complete structure, consistent counts, Mermaid parseable (if applicable).
8. Receipt, NotebookLM failure targets listed item by item.

See references/prompt-notebooklm.md、references/notebooklm-test-matrix.md、references/quality-gates.md。