A public routing layer that turns an article into different deliverables: PDF, PPT, images/long images, infographics, exam papers, mind maps, podcasts, flashcards, reports, WeChat Official Account HTML, Xiaohongshu cards, etc.
It orchestrates clip-* -> transform -> publish/maintain, and does not replace clip, publish, NotebookLM, Open Design, or the current agent's file capabilities.
Client-readable explanation
What this skill can do
A public routing skill that converts X/WeChat Official Account/web page/Markdown articles into deliverables such as PDF, PPT, images/long images, exam papers, mind maps, podcasts, flashcards, reports, etc. Configuration is externalized, and it can call Obsidian, NotebookLM, Open Design, Codex file capabilities, and publish
| 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 the 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 that need 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
- Describe the goal in natural language, and provide the necessary inputs: file, URL, repo, workspace, proposal, vault, 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 client for confirmation first.
- After execution, verify the real output, and do not substitute "looks successful" for evidence.
- 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-transform -y
Configuration conventions:
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-transform/config.yml
SOIA_PKM_TRANSFORM_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 be placed in private
config.yml, process environment, or the provider's own login state, and 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.mdsubsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, add the description first or ask the client, and do not guess. - Third-party skills may only declare dependencies and installation methods, and must 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 / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>
Hold these boundaries first
- Do not hard-code personal vault paths, accounts, tokens, keys, cookies, family information, or personal directories.
- Configuration comes only from the user's current-turn instructions, config files, or environment variables; the public defaults must work on someone else's machine.
- Secrets and login state belong only in the provider's own private locations, e.g.
NOTEBOOKLM_HOME, the WeChat Official Account privateconfig.yml, agent key flows; do not write them into the vault or open-source skills. - Do not read
私有数据.md, browser cookies, or account config files unless the user explicitly requests it and the provider's official flow requires it. - The default is conversion, not summarization. Only compress content when the user explicitly says "summarize/summary/TL;DR".
- Before generating, first extract the source's chapters, concepts, case chains, and key judgments; the deliverable must cover most of this checklist.
- A file existing does not mean it is done; page count, information density, coverage, style, and media completeness are accepted per quality-gates.md .
After triggering, first determine
- Source: URLs go through the corresponding clip skill first; local Markdown/vault notes are read directly; PDF/Word/PPT are first extracted into an article packet.
- Target：
pdf | ppt | image | long_image | infographic | quiz | mindmap | podcast | video | cinematic-video | flashcards | data_table | report | wechat | x_thread | xhs。 - Content mode：
preserve: PDF, full-text report, courseware; preserve chapters, examples, checklists, and key wording.learning: PPT, exam paper, flashcards, course modules.visual_dense: long image, infographic, poster; explain it clearly in one image.synthesize: grounded report / NotebookLM synthesis.summarize: used only when the user explicitly requests a summary.
- provider: user-specified > config > default routing. When a provider is missing, enter bootstrap; do not just say "not installed" and stop.
Config discovery
Config is optional; when there is no config, follow default routing. Priority:
- the provider / output directory / format / parameters explicitly specified by the user this turn
SOIA_PKM_TRANSFORM_CONFIG~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-transform/transform.config.yml(or.yaml/.json）
See examples at assets/transform.config.example.yml。
Routing table
| Target | Default provider | Needs to read |
|---|---|---|
Obsidian native export (vault Markdown,preserve) or local PDF |
provider-soia-local.md | |
| PPT/PPTX | local presentation / HTML deck | prompt-ppt.md, optionally Open Design / NotebookLM |
| Long image/infographic | local HTML/CSS screenshot | prompt-infographic.md, optionally Open Design / NotebookLM |
| Cover/illustration | imagegen / Codex image | prompt-codex-image.md |
| quiz/flashcards/mindmap/report | NotebookLM or local markdown | prompt-notebooklm.md or provider-soia-local.md |
| podcast/video/cinematic-video/data-table | NotebookLM | provider-notebooklm.md |
| WeChat Official Account/X/Xiaohongshu | soia-pkm-publish |
publish skill |
The main provider entry point is at providers.md. Open Design is an enhancement provider, not a hard dependency; see provider-open-design.md。
Target-specific prompts
Different deliverables must use different prompts; do not use generalized prompts like "summarize into a PPT/generate an image".
- PPT / courseware:prompt-ppt.md
- Long image / infographic / poster:prompt-infographic.md
- Codex image / imagegen：prompt-codex-image.md
- Open Design handoff：prompt-open-design.md
- Visual report:prompt-report.md
- NotebookLM master routing:prompt-notebooklm.md, then read per artifact
prompt-notebooklm-*.md
Reproducibility and no tracing text
Before generating visual deliverables such as PPTs / long images / covers, first save the final prompt to the prompts/ subdirectory in the same directory as the deliverable (e.g. outputs/transform/<年>/<文章stem>/prompts/NN-<类型>.md), ensuring every generation can be traced back and rerun with a different provider, without relying on "how it was written at the time" in memory.
When text errors appear in bitmap images (typos, garbled characters, cramped layout),the only legal fix is to change the prompt and regenerate, and keep the old version for comparison; it is forbidden to use code (PIL/Canvas/ImageMagick/OCR overlay, etc.) to trace text, paste patches, or cut out and redraw on an already generated image—that is covering up the problem, not fixing it.
Directly runnable script
python3 scripts/resolve_config.py
python3 scripts/resolve_route.py --target ppt --provider notebooklm --json
python3 scripts/notebooklm_health.py --ensure-home --json
python3 scripts/notebooklm_artifact_matrix.py --article <article.md> --out-dir <out> --targets all --run --json
python3 scripts/local_artifact_smoke.py --article <article.md> --out-dir <out> --strict --json
python3 scripts/validate_artifact_quality.py --article <article.md> --out-dir <out> --strict --json
The script only handles generic paths and common provider flows; do not write personal vault paths into the script.
Workflow
- Parse the request: source, target, format, audience, whether to archive first.
- Fetch the article: URLs go through clip; local files form an article packet.
- Choose the mode and recipe: first decide
content_mode, then runresolve_route.pyor read output-recipes.md。 - Check the provider: run health checks first for NotebookLM, Open Design, Obsidian, and the publishing pipeline; if unavailable, follow the corresponding provider bootstrap.
- Generate the artifact: write only to the user-specified directory, the current project, or the vault's
outputs/transform/<YYYY>/<文章stem>/。 - Verify: first run
validate_artifact_quality.pyor an equivalent check, then follow quality-gates.md for human review of coverage, page count/information block count, openability, readability, parseability, and absence of obvious garbled text/overlap/blank areas. - Write back the link: when the source article is in the vault and the configuration allows it, only append the
## 转化产物link, without modifying the original text. - Receipt: list the source, content_mode, provider, output files, verification results, and failure/degradation reasons.
Acceptance gate
- PDF: can be opened, page count is reasonable; when visual inspection is needed, extract pages and render them.
- PPT/PPTX: can be opened or rendered for preview; check for text overflow, overlap, and blank pages.
- Images/long images: reasonable dimensions, Chinese text is readable, no truncation.
- quiz/flashcards: the number of questions, answers, and explanations matches.
- mindmap: JSON / Mermaid / Markdown is parseable.
- NotebookLM: record the notebook id and artifact id/download path; failed targets must also be recorded item by item.
- Open Design: distinguish plugin apply, artifact create, and export; when the desktop renderer is missing, you must not claim that it has been exported.
For public anonymous use cases, see examples.md。