PPT Page Recognition to JSON Converter

Problem Background

PPT files are widely used for presentations and documentation, but their content is stored in an unstructured format, making programmatic analysis, data extraction, or integration with other systems difficult. Manual conversion to structured formats like JSON is time-consuming and error-prone, especially with multi-page presentations, complex layouts, or image-heavy pages, where hierarchy, semantics, and connections can be lost.

Core Workflow

This skill automates the recognition of PPT page structures and content to generate structured JSON files that faithfully restore original semantics. Key steps include:

• Pre-identification Check: Before running, it checks for a PDF file with the same name in the target .pptx directory. If missing, it prompts the user to either provide the PDF or continue with PPT only. It also verifies if the current model supports vision capabilities; if not, it reminds the user to switch models to avoid silently skipping critical steps.

• Native Structure Recognition: Executes scripts/recognize_ppt_deck.py --vision-mode off to prioritize extracting the native OOXML structure from the PPT, generating an initial JSON. This step focuses on text, hierarchy, and layout, outputting fields like page types (timeline, logo-wall, etc.).

• Vision Enhancement: If vision_tasks are produced (e.g., slide_visual_recovery for low-text pages) and the model supports vision, it automatically uses screenshots exported from the PDF (stored in output/screenshots/) for supplementation. Visual tasks focus on recovering text, metrics, and connections in image-heavy areas.

• Merge and Cleanup: Combines vision task results into the initial JSON via scripts/apply_vision_tasks.py to produce the final merged JSON. After success, runs scripts/cleanup_intermediate_outputs.py to delete intermediate files like task result JSON and audit reports, ensuring only one delivery result remains in the workspace.

The skill supports various page families such as people-matrix, metrics, peer-panels, and uses missing_risk fields to honestly flag areas that cannot be reliably recovered.

Caveats

• Applicability Boundaries: The skill works best with editable .pptx files where text is retained in the OOXML structure. If the PPT consists mainly of screenshots, flat diagrams, or scanned pages, text coverage may decrease, and connector inference relies more on visual judgment, but multimodal supplementation is still required.

• Hard Rules: Must prioritize native structure over OCR; defaults to visual enhancement for image-heavy pages without additional user confirmation; cannot silently skip PDF or model checks; final output is a single JSON, with intermediate artifacts like vision_task_results.json cleaned up.

• Avoided Pitfalls: Does not flatten structures (e.g., timelines or logo walls) into plain lists; retains small labels, footers, or side columns with semantic value; explicitly preserves conflicting data sets instead of selecting one version. These rules ensure the completeness and accuracy of the converted data.