soia-pkm-transform-article-ppt

Convert one source into a presentable, editable, and re-verifiable PPT media package. The default official master iseditable .pptx; visual assets, infographics, and NotebookLM decks are used to enhance understanding and presentation, not to replace content editability.

Customer-readable description

What this skill can do

Artifact	Default role	Delivery requirement
Editable PPTX	Official master	Text, structure, and main graphics are editable; fully covers the source main line
Cover image / illustration / background	PPT visual asset	No dense Chinese text; generated by imagegen or equivalent image capability
Infographic / long image	Standalone communication asset, optional	Chinese text is laid out by HTML/CSS or PPT; image models only provide visual components
NotebookLM PPTX	Visual comparison version, optional	source-grounded; clearly marked as usually one image per page and not easily editable
Preview and QA	Acceptance evidence	Render all pages, montage, overflow check, manual page-by-page review
Planning and review contract	Quality evidence	Claim Ledger, content/design plan, Contract Card, Signature Proof, dual-Lens review, and host acceptance
`media-manifest.json`	Generation manifest	Record source, provider, expected files, and actual verification; do not write login credentials

When the user only says "PPT", deliver by default .pptx. Only additionally convert .pptwhen the user explicitly requests compatibility with older versions of PowerPoint, and verify the conversion result; do not mistake the colloquial PPT request for a requirement to output the old binary format.

How customers use it

Provide any one type of input: article path, URL, Markdown, outline, data table, or topic. It is best to also provide the audience, purpose, page count, style, and whether NotebookLM is needed.

把 <article.md> 做成给小白讲的 16 页 PPT，生成 3 张无字插画素材
把这个 URL 归档后做成可编辑 PPTX，并用 NotebookLM 再做一版对比
把这篇技术文章做成分享课件，同时给一张 1080x1600 的重点简图
把这篇复杂技术文章做成 16 页中文 PPTX，thorough 审稿，并用 PowerPoint 做最终中文验收

When the provider is unspecified and the current session is interactive, ask only one multiple-choice question:

需要可编辑本地版、NotebookLM 视觉版，还是两版对比？

When the user does not answer or the task cannot wait, default to local_editable; when the user says "try them all", "make it prettier", or "make courseware and compare", prioritize hybrid。

Dependencies and installation

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

claude plugin install soia-pkm-vault@soia

When 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 a 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-transform-article-ppt -y

local_editable: Prefer the host's native presentations / PowerPoint capabilities; in the Codex environment, prefer its Presentations runtime, rather than writing python-pptx as the sole default implementation.
imagegen: When the host provides image generation capabilities, call them directly; when unavailable, use user assets, icons, or pure layout, and do not falsely claim that images were generated.
notebooklm: Requires NotebookLM CLI and login state, see references/provider-notebooklm.md。
open_design: Optional enhancement; once selected, hard-depends on soia-dev-open-design-ops, see references/provider-open-design.md。
officecli: Optional Office file operation and re-verification layer; suitable for inspecting, precisely modifying, and verifying existing PPTX, does not replace design generation, see references/provider-officecli.md。

Private configuration is placed in:

~/.config/soia-skills/soia-open-pkm-vault-skills/soia-pkm/soia-pkm-transform-article-ppt/config.yml

The configuration file selection order is --config > SOIA_PKM_ARTICLE_PPT_CONFIG_FILE > the above default paths; field values are resolved as "explicit CLI > private config > built-in default". For configuration examples, see assets/config.example.yml。

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

logs and completion receipts

完成：<一句话说明正式母版与辅助版本>。

- source: <路径或 URL>
- provider: local_editable | notebooklm | hybrid | open_design
- office_execution: host | officecli | host+officecli
- editable_pptx: <路径、页数、是否可编辑>
- notebooklm_pptx: <路径、页数、是否为图片页；未生成则省略>
- visual_assets: <数量与路径>
- infographic: <路径与尺寸；未生成则省略>
- manifest: <路径>
- planning: <内容计划、设计计划和 Contract Card 路径>
- review: <standard/thorough、content/design Lens 轮次与结论>
- signature_proof: <页码与预览路径；明确跳过则写原因>
- host_validation: <PowerPoint/Keynote/LibreOffice、渲染页数与 CJK 结果>

验证：
- PPTX 实际打开并渲染全部页面
- 预览页数与 PPTX 页数一致
- 无空白页、越界、重叠、乱码和占位符
- source 时间、作者、数字与声明已核对
- 人工逐页检查已完成
- Claim Ledger、双 Lens 审稿和宿主验收已完成

限制：<未验证事实、provider 降级或编辑性限制>

hard boundaries

The official master is editable by default. NotebookLM often renders each page as a single full-page image; unless verified by actual testing, it must not be called an editable PPTX.
Image models do not lay out dense Chinese text. imagegen is used for covers, illustrations, backgrounds, and visual metaphors; titles, terminology, numbers, tables, and sources are typeset later by PPT/HTML.
Each page has only one main judgment. Pages can be dense, but must have a clear visual focus and reading order.
Do not fabricate metadata. The source page uses only the authors, links, and publication times verified in the source; do not write guessed model names, generation times, notebook ids, artifact ids, download paths, or placeholders.
Keep external facts separate from the original text's viewpoints. Time-sensitive predictions, performance numbers, and enterprise cases, if not independently verified, must be labeled "original viewpoint/unverified".
File existence does not equal completion. Without full rendering and manual visual review, it must not be delivered as complete.
Prompts, assets, and intermediate manifests are written only to the user-specified output directory; login state, cookies, and account information never enter the output or receipts.
Planning evidence must not be fabricated after the fact. The Claim Ledger, design plan, Signature Proof, and critic results must come from actual execution; do not merely modify JSON to make validation turn green.
Chinese decks do not treat LibreOffice as the sole source of truth. Final priority is to open and render in PowerPoint/Keynote; when only LibreOffice can be used, CJK glyphs and line breaks must actually be checked and recorded.
Confidential content is closed-loop locally by default. confidential must network=deny, intermediate evidence is written to private state, and final deliverables are written to an independent absolute directory; templates, state, and delivery directories must not be located in a Git checkout.
Private templates are only referenced, not copied. When strictly following a template, first verify the alias and SHA-256; the manifest does not record the template's absolute path, and public fixtures may only use fictional organizations and data.

Workflow

1. Establish the content contract

Read the complete source and extract:main_verdict, audience tasks, sections, concepts, case chains, key judgments, easily confused points, risks, and facts to be verified. URLs are archived first or stable sources are saved; when there is only a topic, first form a content outline.

Run the planning script to generate an auditable checklist:

python3 scripts/media_bundle.py plan \
  --article <article.md> \
  --out-dir <output-dir> \
  --provider hybrid \
  --image-count 3 \
  --purpose "<用途>" \
  --delivery-context "<现场讲解、自读或混合>" \
  --language "zh-Hans" \
  --review-mode standard \
  --main-verdict "<一句主判断>"

For the path and manifest contract, see references/media-bundle-contract.md. The command also creates planning and QA templates that will not overwrite existing content; for fields and state flow, see references/planning-and-review-contracts.md。

2. Select provider and delivery scope

Decide by "explicit user specification > private config > interactive selection > default local_editable". For specific selection rules, see references/provider-selection.md。

For fixed enterprise templates or sensitive materials, first read references/template-and-privacy-contract.md. Template mode and privacy level are decided separately;confidential overrides ordinary provider preferences and only allows execution layers in the local allowlist.

hybrid 's responsibilities are fixed:

The local version handles content completeness, editorial quality, and formal delivery.
The NotebookLM version handles rapid visual storytelling and comparative experiments.
imagegen only handles visual assets with a clear page purpose.

3. Separate the content plan from the design plan

Read references/prompt-ppt.md and references/planning-and-review-contracts.md. First complete content-plan.json: the main judgment, Claim Ledger, narrative arc, and page-by-page content; after confirming the content, complete design-plan.json: design language, semantic colors, page outlines, rhythm, and one signature move tied to the content structure. Do not decide visuals at the same time as the content plan, to avoid visual preferences distorting the original meaning in reverse.

Use contract-card.json to lock down the source, audience, purpose, usage scenario, language, editorial quality, review mode, and delivery scope. For low-risk tasks, default to standard; for public speaking, formal teaching master decks, bids, or high-risk facts, use thorough. Both tiers require independent content/design Lenses; the difference lies only in the review ceiling and the depth of fact spot-checks.

4. Generate purposeful image assets

Read references/prompt-image-assets.mdwhen a visual anchor is needed. Usually generate 2-4: a cover key visual, a core mechanism diagram, and key case/scene images. Each image must be tied to a specific page number or infographic area; do not generate purely decorative stock images.

After generating an image, view the original image first, then place it into the PPT. If the direction, object relationships, text, or numbers are wrong, modify the prompt and regenerate; do not use overlay layers to conceal semantic errors.

5. Do the Signature Proof first, then generate the formal editable PPTX

Generate using the host presentations capability or Open Design. Follow the current host's presentation skills and runtime instructions. Chinese text, process arrows, tables, page numbers, and sources in the PPTX should remain editable; bitmaps should only be used for photos, illustrations, textures, and necessary complex visuals.

OfficeCLI is not the default creation provider. When there is an existing master deck, a need for precise refinement of stable element paths, three or more atomic batches, OpenXML schema revalidation, or built-in screenshots, you may call soia-dev-officecli-opsafter generation. By default, modify on a copy; do not use OfficeCLI to bypass the host presentations' hard implementation requirements.

After the design plan is approved, first produce the core page specified by the signature move and render it for review; after it passes, record it in qa/signature-proof.json, then expand to the full set. Only conservative designs or very small tasks of 1-2 pages may explicitly skip this and write down the reason.

Fixed design requirements:

Medium-to-long documents default to 14-18 pages; short documents 8-12 pages; when the user specifies otherwise, comply and record the compression risk.
At least 4 types of page outlines: cover, map, process, comparison/matrix, full quick reference, case, exercise, sources, etc.
Do not use the same card grid consecutively; do not make page sections into floating cards.
Titles express judgments; body text provides structure and evidence; do not write empty titles like "Background Introduction" or "Core Viewpoints".
Colors carry semantics; do not cover the entire set with a single blue-purple or decorative gradient.

6. Optionally generate a NotebookLM comparison version

Read references/provider-notebooklm.md and references/prompt-notebooklm-ppt.md. After generation, you must download by artifact id to prevent grabbing the wrong version when the same notebook has multiple decks.

NotebookLM failure, queuing, or missing login does not affect the local formal master deck; but the receipt must state the true status. If the output contains placeholders, runtime metadata, erroneous Chinese, or facts outside the source, modify the prompt and regenerate.

7. Generate an optional infographic

Read when you need "one image to explain it clearly" references/prompt-infographic.md. First generate text-free visual components, then use HTML/CSS or PPT to lay out the Chinese, keeping the main judgment, process direction, and terminology hierarchy consistent.

8. Dual-Lens Review and Two-Layer Acceptance

After full rendering, perform two separate reviews: the content Lens checks against the complete source and Claim Ledger; the design Lens checks against the design plan, Signature Proof, and full preview. When the host supports independent agents, hand them to different agents; when it does not, still perform two separate independent checks. Only when both Lenses consent and blocker/major issues are cleared do you proceed to final host acceptance.

For final delivery, prioritize opening and rendering the official master with PowerPoint or Keynote, and record the actual host, number of rendered pages, and CJK check results. If only LibreOffice can be used, you must actually check CJK glyphs and line breaks, and clearly state this limitation in the host record and delivery receipt.

Then run mechanical checks and manual visual checks:

python3 scripts/media_bundle.py validate \
  --manifest <output-dir>/media-manifest.json \
  --visual-reviewed \
  --source-facts-reviewed \
  --strict \
  --json

See detailed standards in references/quality-gates.md. If any page fails, return to the corresponding source file, HTML, or prompt to fix it, then re-render; you cannot just modify the completion receipt.

When OfficeCLI is available, use it as additional mechanical evidence: run validate、view issues, and generate full screenshots as needed. It cannot replace the editorial checks of media_bundle.py and manual page-by-page visual review.

9. Delivery and Backlinks

For ordinary tasks, place the official master, auxiliary versions, images, and manifest in the same output directory.confidential For tasks, keep the prompt, planning, preview, QA, and manifest in private state, and write only the final PPTX and delivery files explicitly requested by the user into the independent final output. If the source is in a writable knowledge base and already has a "related/derived artifacts" section, update the links; do not copy the same artifact list across multiple files.

Read as needed

Output directory and manifest:references/media-bundle-contract.md
Provider selection:references/provider-selection.md
Editable PPT plan and prompts:references/prompt-ppt.md
imagegen assets:references/prompt-image-assets.md
Infographics:references/prompt-infographic.md
NotebookLM：references/provider-notebooklm.md、references/prompt-notebooklm-ppt.md
Open Design：references/provider-open-design.md、references/prompt-open-design.md
OfficeCLI operations and re-verification:references/provider-officecli.md
Quality gates:references/quality-gates.md
Planning, Signature Proof, dual-Lens review, and host acceptance:references/planning-and-review-contracts.md
External templates, SHA-256, confidential isolation, and path hard gates:references/template-and-privacy-contract.md
Typical invocation:references/examples.md

Private information and intermediate data

Private configuration goes only in ~/.config/soia-skills/soia-open-pkm-vault-skills/soia-pkm/soia-pkm-transform-article-ppt/config.yml, or use SOIA_PKM_ARTICLE_PPT_CONFIG_FILE to point to the user's own files.
Credentials for NotebookLM, Office, or other providers stay in the provider's official login storage or the system keychain; they must not be written into config, prompt, manifest, PPTX, previews, or receipts.
For ordinary tasks, write the prompt, planning JSON, QA JSON, previews, and temporary assets into the media package directory.confidential Tasks must be written to private state and must not be included in version control.
Use the operating system temporary directory for rebuildable temporary conversion files and clean them up after success or failure; do not treat the repository checkout as a runtime cache.
The retention period for the official PPTX, PDF, images, and media packages explicitly requested by the user to be kept is controlled by the user; confirm the target before deleting or overwriting.