ppt-skill

# PPT Skill Spec-driven PPT generation: extract design DNA from reference PPTX → gather content → generate natively editable slides with agent-loop style verification. ## Slash Commands | Command | Purpose | |---------|---------| | `/ppt-spec <file.pptx>` | Extract design spec from reference PPTX (cover/toc/content/end_page recognition + layout analysis) | | `/ppt-spec-vl <file.pptx>` | Extract VL-driven spec with element role analysis, layout dedup, JSON output (no text content) | | `/ppt-outline <content>` | Generate content outline using WPS model from prompt-ppt-content.md (titles + body only) | | `/ppt-diagram <type> <content>` | Generate diagram (architecture/flowchart/sequence) from description | | `/ppt <content or file>` | Generate PPT: gather content → confirm outline → generate PPTX → apply layout design | ## Quick Start ```bash # Extract design spec from a reference PPTX python scripts/ppt_cli.py extract-spec reference.pptx # Generate PPT from content (with agent-loop style verification) python scripts/ppt_cli.py generate-pptx --spec specs/my_spec/ --outline outline.yaml -o output.pptx --workers 4 # Direct SVG to PPTX conversion python scripts/ppt_cli.py convert slide1.svg slide2.svg -o output.pptx ``` ## Commands | Command | Description | |---------|-------------| | `extract-spec <pptx>` | Extract design spec → `specs/<name>/` directory (pages by type, assets, logic.yaml) | | `extract-vl-spec <pptx>` | Extract VL-driven spec → `specs/<name>/` JSON + slide images (no text, layout dedup) | | `generate-pptx` | Generate PPTX from spec + outline with agent-loop eval (--spec --outline -o --workers) | | `convert <svg>... -o <pptx>` | Direct SVG→native-shape PPTX conversion | | `list-specs` | List available design specs | | `select-spec <name>` | Set active design spec | | `gather-content <text\|file>` | Content gathering → slide-by-slide outline (adaptive questioning, 8-question cap) | | `list-outlines` | List saved content outlines | All scripts run from the skill root directory. ## Workflow ### `/ppt-outline` — Generate Content Outline This command has two modes depending on input richness: **Mode A — Topic-only (input <= 30 words, no structure markers)** The user only provided a topic name (e.g. "AI in Healthcare 2024"). Do NOT proceed with outline generation directly. Instead: 1. **Detect sufficiency**: The skill outputs a structured JSON delegation signal: ```json { "type": "delegate", "skill": "deerflow-skill", "query": "<topic>", "context": "Research this presentation topic comprehensively. Gather key sections, trends, data points, examples, case studies, and supporting evidence needed for a professional slide deck." } ``` 2. **Call deerflow-skill**: The outer agent reads this signal and invokes `deerflow-skill` with the query to research the topic thoroughly. 3. **Return enriched content**: After deerflow-skill returns comprehensive research, call `ppt-skill` again with the enriched content. 4. **Apply prompt-ppt-content.md**: When the content is received (now rich), apply `prompt-ppt-content.md` WPS rules to optimize the content into a structured outline: - Each slide gets **W (What)**: Navigation label - **P (Point)**: Core conclusion (bold, prominent) - **S (Support)**: Evidence (data, cases, quotes) 5. **Output**: Markdown outline ready for `/ppt` generation **Mode B — Rich content (detailed input with structure)** The user provided sufficient detail (bullets, sections, or extensive text). 1. **Apply WPS model**: Use `prompt-ppt-content.md` principles directly - Analyze input → extract sections and key points - Structure each slide with W (What) / P (Point) / S (Support) - Validate outline completeness 2. **Output**: Markdown outline ready for `/ppt` generation ### `/ppt-diagram` — Generate Diagram 1. **Classify diagram type**: architecture, data-flow, flowchart, sequence, class, er-diagram, network-topology 2. **Extract structure**: identify nodes, edges, containers from description 3. **Apply layout rules**: - Architecture: horizontal layers (Client → Gateway → Services → Data) - Flowchart: top-to-bottom, diamond for decisions - Sequence: vertical lifelines with horizontal messages 4. **Generate SVG** using 7 visual styles: - Style 1: Flat Icon (default, white bg) - Style 2: Dark Terminal (monospace, dark bg) - Style 3: Blueprint (cyan on navy) - Style 4: Notion Clean (minimal) - Style 5: Glassmorphism (translucent) - Style 6: Claude Official (warm cream) - Style 7: OpenAI (green accent) 5. **Export**: SVG + PNG via rsvg-convert ### `/ppt-spec` — Extract Design Spec Two extraction modes: **Mode A — Standard (`extract-spec`) — preserves text content** 1. Read the reference PPTX with `python-pptx` + `lxml` 2. Extract color palette (12 HEX values from theme1.xml), fonts, backgrounds 3. Classify each page: cover / toc / transition / content / end_page 4. For content pages, identify layout sub-type: left_right, top_bottom, etc. 5. If `VL_ENABLED=true` in `config.txt`, use VL model for enhanced layout description 6. Extract reusable assets (backgrounds, images) 7. Analyze presentation logic (narrative, density rhythm, sections) 8. Save as directory: `specs/<name>/` with `spec.yaml`, `pages/`, `assets/`, `logic.yaml` **Mode B — VL-driven (`extract-vl-spec`) — no text content, layout dedup** 1. Read the reference PPTX with `python-pptx`, extract every element's properties: - Position, size (normalized 0-1) - Font family, size, weight, color, alignment - Fill color, stroke color/width, corner radius - Image dimensions - Z-order, shape name 2. Render each slide to PNG via macOS QuickLook 3. Send slide image + structured element properties to **VL model**: - VL compares the visual image with extracted element attributes - VL describes each element's ROLE: "Element 1 is the title bar", "Elements 3-6 form a flowchart in the content area" - VL identifies composite groups and design patterns 4. **Layout dedup**: group similar pages by element structure signature - Cover/end_page → one JSON file each - Content pages with same layout → merged into one JSON file 5. Output `specs/<name>/` with: - `spec.json` — master spec (palette, fonts, canvas, layout index) - `cover.json`, `end_page.json`, `content_*.json` — per-layout blueprints - `slides/` — slide PNG screenshots - Source PPTX copy for reference See [references/spec-format.md](references/spec-format.md). ### `/ppt` — Generate Presentation 1. **Assess sufficiency**: evaluate if user input has enough detail 2. **If insufficient (topic-only)**: call `deerflow-skill` to research the topic, gather comprehensive content, then apply `prompt-ppt-content.md` for outlined> 3. **If sufficient**: proceed directly with `prompt-ppt-content.md` WPS optimization 4. **User confirms** the outline before generation 5. **Phase 1: Spec Matching** (agent-loop, per slide, in parallel, using VL model): - Match slide to correct spec page type (cover→cover spec, content→matching layout spec, etc.) - Generate SVG with strict style constraints from spec - Evaluate: color match, font match, layout IoU, background, density - If score < 90% → add fix instructions, regenerate (max 5 iterations) - All slides generated in parallel via ThreadPoolExecutor 6. **Phase 2: Layout Design** (agent-loop, using `prompt-ppt-layout.md`): - Apply WPS hierarchy: W (navigation) small, P (point) large/bold, S (support) regular - Typography: sans-serif fonts, 1.5x line spacing, justified text - Color rules: single primary color, dark text (#333-#444) - Whitespace: 8-12% margins, breathing room - Visuals: Bootstrap Icons from `assets/bootstrap-icons-1.13.1/` - Validate layout checklist (max 3 iterations) 7. **Convert**: all SVGs → native-shape PPTX via SVG→DrawingML pipeline 8. Output: editable `.pptx` with real PowerPoint shapes ### Content Gathering Mode When the user just wants to prepare content without generating PPTX: 1. Assess content sufficiency (word count, structure markers) 2. If sufficient → directly apply `prompt-ppt-content.md` WPS optimization 3. If insufficient (topic-only) → call `deerflow-skill` to research, then apply WPS optimization 4. Output: `outlines/<name>.yaml` — ready for `/ppt` generation ## Configuration Copy `config.example.txt` to `config.txt` for VL model analysis in spec extraction: ```ini VL_ENABLED=true VL_PROVIDER=openai # openai | anthropic | gemini | ollama VL_MODEL=gpt-4o VL_API_KEY=sk-... ``` ## Resources | Directory/File | Contents | |----------------|----------| | `scripts/ppt_cli.py` | CLI entry point | | `scripts/ppt_skill/` | Python package (converter, spec, content, layout, diagram, finalize, evaluator) | | `references/spec-format.md` | Design spec schema | | `references/prompt-ppt-content.md` | Content generation principles (WPS model) | | `references/prompt-ppt-layout.md` | Layout design principles | | `references/diagram-styles/` | Diagram style references (7 styles + icons) | | `templates/diagram/` | Diagram SVG templates | | `assets/Illustration/` | **400 vector illustrations** (unDraw, MIT License) | | `assets/bootstrap-icons-1.13.1/` | 2000+ SVG icons for slides | | `assets/templates/icons/` | 11,600+ SVG icons (5 libraries) | | `assets/templates/charts/` | 70+ chart/infographic SVGs | | `config.example.txt` | Model configuration template | ## Illustration Library `assets/Illustration/` contains **283** open-source vector illustrations from unDraw: ### Categories | Category | Count | Examples | |----------|-------|----------| | **AI & Technology** | 10+ | `ai-chat`, `ai-code-assistant`, `coding-assistant` | | **Data Analytics** | 15+ | `analyze`, `data-table`, `analytics-setup` | | **Team & Collaboration** | 10+ | `collaboration`, `followers`, `eating-together` | | **Success & Achievement** | 10+ | `accomplishments`, `completed`, `goals` | | **Business & Marketing** | 15+ | `business-decisions`, `customer-survey`, `contract` | | **Learning & Education** | 10+ | `continuous-learning`, `exam-prep`, `five-year-plan` | | **Documents & Files** | 10+ | `document-ready`, `file-analysis`, `add-files` | ### Search Illustrations ```bash # Search for AI-related illustrations python3 scripts/ppt_skill/illustration_finder.py search "ai" # Search by category python3 scripts/ppt_skill/illustration_finder.py list --category data # Get random illustrations python3 scripts/ppt_skill/illustration_finder.py random --count 5 # List all categories python3 scripts/ppt_skill/illustration_finder.py list --categories ``` ### Use in PPT ```python from pptx import Presentation from pptx.util import Inches # Add illustration to slide prs = Presentation() slide = prs.slides.add_slide(prs.slide_layouts[6]) slide.shapes.add_picture( "assets/Illustration/undraw_ai-chat_ljb9.svg", Inches(1), Inches(1), Inches(4) ) ``` ### Customize Colors Edit SVG `fill` attributes to match your brand: ```xml <!-- Original orange --> <path fill="#f9a826" d="..." /> <!-- Change to brand blue --> <path fill="#0070C0" d="..." /> ``` ## Requirements Python 3.10+ with: ``` python-pptx>=0.6.21 Pillow>=9.0.0 PyYAML>=6.0 ``` Optional for VL analysis: `openai`, `anthropic`, or `google-generativeai`.