PPTX：PowerPoint 演示文稿创作

一句话总结

pptx 是 PowerPoint 演示文稿处理的完整方案——通过 PptxGenJS 创建新演示文稿，通过 XML 编辑修改现有文件，包含缩略图预览、幻灯片添加和设计指南。

核心能力

🎨 使用 PptxGenJS（JavaScript）创建演示文稿，支持字体配对、调色板、布局多样化
🔧 使用”拆包-编辑-XML”流水线编辑现有 PPTX
👁️ 缩略图网格预览——快速视觉分析幻灯片结构
➕ 幻灯片添加（从模板或复制现有幻灯片）
🧹 清理和优化
📝 文本提取（markitdown）
📐 丰富的设计指南——配色方案、字体搭配、间距规则

触发场景

用户提及 .pptx 文件、幻灯片、演示文稿、deck、需要创建或编辑演示文件。

文件清单

One-Line Summary

pptx is a complete PowerPoint presentation processing solution — creating presentations via PptxGenJS, editing existing files through XML manipulation, with thumbnail preview, slide addition, and design guidance.

Core Capabilities

🎨 Create presentations with PptxGenJS (JavaScript), supporting font pairings, color palettes, varied layouts
🔧 Edit existing PPTX via “unpack-edit-XML” pipeline
👁️ Thumbnail grid preview — rapid visual analysis of slide structure
➕ Slide addition (from template or duplicate existing)
🧹 Cleaning and optimization
📝 Text extraction (markitdown)
📐 Rich design guidelines — color schemes, font pairings, spacing rules

Trigger Scenarios

User mentions .pptx files, slides, presentations, decks, or needs to create or edit presentation files.

File Inventory

pptx
- SKILL.md 主入口 · PPTX 处理指南
- pptxgenjs.md PptxGenJS 创建参考
- editing.md XML 编辑参考
- LICENSE.txt 许可证
- scripts
  - thumbnail.py 缩略图网格生成
  - add_slide.py 幻灯片添加
  - clean.py PPTX 清理
  - __init__.py 包初始化
  - office 共享 Office 核心包
    - pack.py
    - unpack.py
    - validate.py
    - soffice.py
    - validators/ Schema 验证器
    - helpers/ XML 工具
    - schemas/ XSD Schema

目录结构分析

pptx 的结构属于**“双路径”（Dual Path）型**——一条路径用 PptxGenJS 从零创建，另一条通过 XML 编辑修改现有文件。

SKILL.md 结构解析

SKILL.md 的核心包含：

Quick Reference：三条路径——读取用 markitdown、编辑用 XML、创建用 PptxGenJS
Reading Content：文本提取和缩略图视觉预览
Editing Workflow：分析模板 → 拆包 → 操作幻灯片 → 编辑内容 → 清理 → 打包
Creating from Scratch：指向 pptxgenjs.md 使用 PptxGenJS
Design Ideas：配色方案（10 套预设）、字体配对、布局指南、常见设计错误
QA：严格的视觉验证流程——转换 → 检查 → 修复 → 复查循环
Converting to Images：通过 LibreOffice + Poppler 将 PPTX 转换为幻灯片图像

YAML Frontmatter 分析

TRIGGER 条件覆盖面极广——“任何涉及 .pptx 文件的操作”，包括创建、读取、编辑、合并、拆分、模板使用。关键词触发包括”deck”、“slides”、“presentation”等。

参考文档关系

设计模式分类

pptx 是典型的**“双路径”（Dual Path）** 型 Skill：

Directory Structure Analysis

The pptx skill follows a “Dual Path” pattern — one path uses PptxGenJS for creation from scratch, another uses XML editing for modifying existing files.

SKILL.md Structure Analysis

Core sections of SKILL.md:

Quick Reference: Three paths — reading with markitdown, editing with XML, creating with PptxGenJS
Reading Content: Text extraction and thumbnail visual preview
Editing Workflow: Analyze template → unpack → manipulate slides → edit content → clean → pack
Creating from Scratch: Points to pptxgenjs.md for PptxGenJS usage
Design Ideas: Color palettes (10 presets), font pairings, layout guidance, common mistakes
QA: Strict visual verification process — convert → inspect → fix → re-verify loop
Converting to Images: PPTX to slide images via LibreOffice + Poppler

YAML Frontmatter Analysis

TRIGGER conditions cover an extremely broad scope — “any operation involving .pptx files”, including creation, reading, editing, merging, splitting, template usage. Keyword triggers include “deck”, “slides”, “presentation”.

Reference Document Relationships

Design Pattern Classification

pptx is a typical “Dual Path” Skill:

文档	用途
`SKILL.md`	总入口：快速参考、设计指南、QA 流程
`pptxgenjs.md`	PptxGenJS 创建演示文稿的完整参考
`editing.md`	XML 编辑的详细参考（对应 docx 提供的内联 XML 参考）

Document	Purpose
`SKILL.md`	Main entry: quick reference, design guide, QA process
`pptxgenjs.md`	Complete PptxGenJS creation reference
`editing.md`	Detailed XML editing reference

特征	说明
创建路径	PptxGenJS（高层 JavaScript API）
编辑路径	拆包 → XML 编辑 → 打包（底层控制）
脚本层	thumbnail / add_slide / clean + 共享 office/ 包
设计指南	内置于 SKILL.md 中，10 套配色方案、字体配对
QA 流程	转换 → 图像检查 → 修复 → 复查的完整循环

Feature	Description
Creation Path	PptxGenJS (high-level JavaScript API)
Editing Path	Unpack → XML edit → Pack (low-level control)
Script Layer	thumbnail / add_slide / clean + shared office/ package
Design Guide	Built into SKILL.md, 10 color palettes, font pairings
QA Process	Full loop: convert → image inspection → fix → re-verify

脚本清单

pptx 的脚本按层次分组：

pptx 专用脚本

Office 核心（共享包）

详细分析

thumbnail.py

这是 pptx 最独特的脚本——提供视觉预览能力，让 Claude 能在不直接查看 PPTX 二进制文件的情况下理解幻灯片布局。

核心处理流程：

获取幻灯片信息：遍历 ZIP 中的 ppt/presentation.xml 和 ppt/_rels/presentation.xml.rels，提取每张幻灯片的文件名和隐藏状态
PDF 转换：调用 LibreOffice 将 PPTX 转为 PDF
图像转换：使用 pdftoppm 将 PDF 每页转为 JPEG
创建缩略图网格：使用 Pillow 将多张幻灯片图像排列为网格布局，每张带有文件名标签
隐藏幻灯片处理：隐藏的幻灯片显示为带斜线的占位图

关键设计点：

支持 --cols 参数控制网格列数（默认 3 列，最多 6 列）
自动分页——幻灯片超过 1 个网格时创建多个网格图像
每张幻灯片标签显示其 XML 文件名（slide1.xml），便于定位编辑目标

这个脚本的输出被用于”分析模板”阶段——在编辑前先查看演示文稿的视觉结构和幻灯片数量。

Script Inventory

pptx scripts are grouped by layer:

PPTX-Specific Scripts

Office Core (Shared Package)

Detailed Analysis

thumbnail.py

The most distinctive script in pptx — providing visual preview capability, allowing Claude to understand slide layout without directly viewing the PPTX binary.

Core processing flow:

Get slide info: Traverses ZIP’s ppt/presentation.xml and ppt/_rels/presentation.xml.rels, extracting each slide’s filename and hidden state
PDF conversion: Calls LibreOffice to convert PPTX to PDF
Image conversion: Uses pdftoppm to convert each PDF page to JPEG
Create thumbnail grid: Uses Pillow to arrange multiple slide images in a grid layout, each with filename label
Hidden slide handling: Hidden slides display as placeholder images with diagonal lines

Key design points:

--cols parameter controls grid columns (default 3, max 6)
Auto-pagination — creates multiple grid images when slides exceed one grid
Each slide labeled with its XML filename (slide1.xml) for easy editing targeting

This script’s output is used in the “analyze template” phase — to preview the presentation’s visual structure and slide count before editing.

脚本	功能	依赖
`thumbnail.py`	生成缩略图网格	Pillow, LibreOffice, Poppler
`add_slide.py`	添加幻灯片（从模板或复制）	defusedxml
`clean.py`	PPTX 清理优化	defusedxml

Script	Function	Dependency
`thumbnail.py`	Generate thumbnail grids	Pillow, LibreOffice, Poppler
`add_slide.py`	Add slides (from template or duplicate)	defusedxml
`clean.py`	PPTX cleaning and optimization	defusedxml

模块	功能
`office/unpack.py`	PPTX → XML 拆包
`office/pack.py`	XML → PPTX 打包
`office/validate.py`	验证入口
`office/soffice.py`	LibreOffice 封装
`office/validators/pptx.py`	PPTX Schema 验证器

Module	Function
`office/unpack.py`	PPTX → XML unpacking
`office/pack.py`	XML → PPTX packaging
`office/validate.py`	Validation entry point
`office/soffice.py`	LibreOffice wrapper
`office/validators/pptx.py`	PPTX Schema validator

thumbnail.py — 缩略图网格生成核心逻辑 ↗ 源文件

1 def main(): 2 # ...argument parsing... 3 4 slide_info = get_slide_info(input_path) 5 6 with tempfile.TemporaryDirectory() as temp_dir: 7 temp_path = Path(temp_dir) 8 visible_images = convert_to_images(input_path, temp_path) 9 10 slides = build_slide_list(slide_info, visible_images, temp_path) 11 12 grid_files = create_grids(slides, cols, THUMBNAIL_WIDTH, output_path) 13 14 print(f"Created {len(grid_files)} grid(s):") 15 for grid_file in grid_files: 16 print(f" {grid_file}") 17 18 def get_slide_info(pptx_path): 19 with zipfile.ZipFile(pptx_path, "r") as zf: 20 # Parse presentation.xml.rels for slide mapping 21 rels_dom = defusedxml.minidom.parseString( 22 zf.read("ppt/_rels/presentation.xml.rels")) 23 rid_to_slide = {} 24 for rel in rels_dom.getElementsByTagName("Relationship"): 25 if "slide" in rel.getAttribute("Type"): 26 rid_to_slide[rel.getAttribute("Id")] = rel.getAttribute("Target").replace("slides/", "") 27 28 # Parse presentation.xml for slide order 29 pres_dom = defusedxml.minidom.parseString( 30 zf.read("ppt/presentation.xml")) 31 slides = [] 32 for sld_id in pres_dom.getElementsByTagName("p:sldId"): 33 hidden = sld_id.getAttribute("show") == "0" 34 slides.append({"name": rid_to_slide[sld_id.getAttribute("r:id")], 35 "hidden": hidden}) 36 return slides

代码解读

L1 main() 入口：解析参数 → 获取幻灯片信息 → 转换为图像 → 构建幻灯片列表 → 创建网格。整体架构清晰、线性。 L8 关键步骤：convert_to_images() 通过 LibreOffice (PDF) + Poppler (JPEG) 两步转换。每一步都可能失败，需要健壮的错误处理。 L12 create_grids() 自动分页：超过 MAX_COLS*(MAX_COLS+1) 张幻灯片时创建多个网格图像文件。 L19 get_slide_info()：从 ZIP 中解析 presentation.xml 和关系文件，重建幻灯片顺序——这是 PPTX 的核心元数据。 L24 RID 到文件名映射：关系文件的 Target 属性（如 "slides/slide2.xml"）需要去掉前缀得到纯文件名（slide2.xml）。 L35 隐藏幻灯片检测：通过 p:sldId 元素的 show 属性判断——show="0" 表示隐藏。

add_slide.py

幻灯片添加工具，支持两种添加方式：

复制现有幻灯片：python add_slide.py unpacked/ slide2.xml —— 复制 slide2 的所有内容和关系，自动分配新编号
从布局模板创建：python add_slide.py unpacked/ slideLayout2.xml —— 使用空白布局创建全新幻灯片

两种方式都会自动：

创建幻灯片 XML 文件
复制或创建关系文件（.rels）
更新 [Content_Types].xml
更新 presentation.xml.rels
输出需要添加到 presentation.xml 的 <p:sldId> 片段

clean.py 简要分析

清理脚本用于移除 PPTX 文件中的冗余数据，包括未使用的关系、空白段落、不必要的元数据。在”编辑 → 打包”流程中作为优化步骤使用。

validators/pptx.py 简要分析

PPTX 的 Schema 验证器，继承自 validators/base.py 的 BaseSchemaValidator。检查内容与 docx 验证器类似但针对 PPTX 格式：幻灯片命名空间一致性、关系引用完整性、内容类型声明正确性。

共享 office/ 包的复用

pptx 和 docx 共享同一套 scripts/office/ 包。这意味着：

相同的 unpack/pack/validate/soffice 代码
相同的 helpers（merge_runs、simplify_redlines）
相同的 XSD Schema 文件
验证器有共享基础（base.py）和各自特化（docx.py / pptx.py）

这种复用模式使得添加新的 Office 格式支持（如 xlsx）变得简单——核心流水线已经就绪，只需添加格式特有的脚本和验证器。

add_slide.py

A slide addition tool supporting two methods:

Duplicate existing slide: python add_slide.py unpacked/ slide2.xml — copies all content and relationships from slide2, auto-assigns new number
Create from layout template: python add_slide.py unpacked/ slideLayout2.xml — creates a brand new slide from a blank layout

Both methods automatically:

Create slide XML file
Copy or create relationship files (.rels)
Update [Content_Types].xml
Update presentation.xml.rels
Output the <p:sldId> fragment to add to presentation.xml

clean.py Brief Analysis

The cleaning script removes redundant data from PPTX files, including unused relationships, empty paragraphs, unnecessary metadata. Used as an optimization step in the “edit → pack” workflow.

validators/pptx.py Brief Analysis

PPTX Schema validator, inheriting from BaseSchemaValidator in validators/base.py. Checks are similar to docx validator but PPTX-specific: slide namespace consistency, relationship reference integrity, content type declaration correctness.

Shared office/ Package Reuse

pptx and docx share the same scripts/office/ package. This means:

Same unpack/pack/validate/soffice code
Same helpers (merge_runs, simplify_redlines)
Same XSD Schema files
Validators share a base (base.py) with format-specific extensions (docx.py / pptx.py)

This reuse pattern makes adding new Office format support (e.g., xlsx) simple — the core pipeline is ready, just need format-specific scripts and validators.

设计亮点

“双路径”模式：明确区分”从零创建”和”编辑现有”两条路径，分别使用最适合的工具（PptxGenJS vs XML 编辑）
视觉预览流水线：thumbnail.py 提供了”先看后改”的能力——在编辑前先通过缩略图网格理解演示文稿结构
严格 QA 流程：PPTX 是唯一在 SKILL.md 中内嵌完整 QA 规程的文档 skill——包括子代理审查、修复-复查循环
设计指南内嵌：10 套配色方案、9 种字体搭配、布局范例——这些设计知识直接编码在 SKILL.md 中，使 Claude 能创建非 AI 风格的幻灯片
共享 office/ 包复用：与 docx 共享核心代码，验证器通过继承机制扩展

可复用模式

移植思路

“如果你想为演示文稿或其他视觉格式创建类似的 Skill…”

实现视觉预览：最优先的功能——让 Claude 能在编辑前”看到”内容。对于演示文稿，thumbnail.py 的模式可直接复用
建立双路径：选择合适的高层创建库（PptxGenJS、python-pptx 等）和底层编辑方式
嵌入设计指南：配色方案、字体配对、布局规则——这些需要直接编码在 SKILL.md 中
定义 QA 流程：视觉格式的测试不能自动化——需要明确的子代理审查协议
寻找共享机会：如果你的技能处理同系列格式，提取共享包可以大幅减少维护成本

常见坑

⚠️ 缩略图覆盖不完整： 缩略图展示的是 PDF 转换结果，可能与 PPTX 最终渲染在某些细节上有差异（字体替代、透明效果）

⚠️ 幻灯片编号崩溃： 手动编辑幻灯片时，presentation.xml 中的 <p:sldId> 顺序必须与文件系统中的 slide*.xml 一致——编号错位会导致打开失败

⚠️ 设计过度指导： SKILL.md 中的设计指南非常详细（10 套配色、9 种字体），但如果 Claude 严格遵循每条规则，可能产生”模板化”的结果。指南应该作为灵感而非约束

⚠️ Q A 的边际收益递减： 修正 2-3 轮后，剩余问题通常是字体/布局细微差异，与用户预期相关而非真正的 bug——需要判断何时停止

⚠️ LibreOffice 渲染差异： 通过 LibreOffice 生成的 PDF/图像可能与 PowerPoint 最终渲染有差异。缩略图仅作为参考，不是精确的最终效果

Design Highlights

“Dual Path” Pattern: Clearly separates “create from scratch” and “edit existing” paths, each using the best tool (PptxGenJS vs XML editing)
Visual Preview Pipeline: thumbnail.py provides “see before editing” capability — understand presentation structure through thumbnail grids before editing
Strict QA Process: PPTX is the only document skill with a complete QA procedure embedded in SKILL.md — including sub-agent review, fix-reverify cycles
Embedded Design Guide: 10 color palettes, 9 font pairings, layout examples — design knowledge encoded directly in SKILL.md to help Claude create non-AI-style slides
Shared office/ Package Reuse: Shares core code with docx, validators extended through inheritance

Reusable Patterns

Porting Guide

“If you want to create a similar Skill for presentations or other visual formats…”

Implement visual preview: Highest priority feature — let Claude “see” content before editing. For presentations, thumbnail.py pattern is directly reusable
Establish dual path: Choose appropriate high-level creation library (PptxGenJS, python-pptx, etc.) and low-level editing approach
Embed design guide: Color palettes, font pairings, layout rules — these need to be encoded directly in SKILL.md
Define QA process: Visual format testing cannot be automated — needs clear sub-agent review protocols
Find sharing opportunities: If your skills process related formats, extracting a shared package significantly reduces maintenance costs

Common Pitfalls

⚠️ Thumbnail coverage incomplete: Thumbnails show PDF conversion results, which may differ from PPTX final rendering in details (font substitution, transparency effects)

⚠️ Slide numbering corruption: When manually editing slides, <p:sldId> order in presentation.xml must match slide*.xml file system order — misalignment causes open failures

⚠️ Over-design guidance: SKILL.md’s design guide is very detailed (10 palettes, 9 fonts) — if Claude follows every rule strictly, results may feel “template-like”. Guide should inspire, not constrain

⚠️ QA diminishing returns: After 2-3 fix rounds, remaining issues are usually font/layout nuances, more about user expectation than bugs — need judgment on when to stop

⚠️ LibreOffice rendering differences: PDF/images generated via LibreOffice may differ from PowerPoint final rendering. Thumbnails are reference only, not exact final results

模式	说明	适用于...
双路径	两个独立路径：高层 API 建新 + 底层编辑	既需要从零创建又需要编辑现有的场景
视觉预览	在编辑前先查看内容的视觉表现	处理视觉格式（PPTX、图像、视频编辑）
设计指南编码	将设计原则和范例直接写入指令	需要创造性输出但又要避免 AI 风格的场景
QA 子代理	用子代理审查视觉输出	需要"新鲜视角"检验的图像密集型任务
共享核心包	多个 skill 共享基础代码	处理同系列格式的 skill 组

Pattern	Description	Applies to...
Dual Path	Two independent paths: high-level API for new + low-level editing	Scenarios needing both creation and editing
Visual Preview	View visual representation before editing	Visual formats (PPTX, image, video editing)
Design Guide Encoding	Write design principles and examples into instructions	Creative output scenarios needing non-AI-style results
QA Sub-agent	Use sub-agents to review visual output	Image-intensive tasks needing "fresh eyes"
Shared Core Package	Multiple skills sharing base code	Skill groups processing related formats