Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks
Add this skill
npx mdskills install sickn33/pptx-officialComprehensive presentation toolkit with three distinct workflows and excellent design guidance
1---2name: pptx3description: "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks"4license: Proprietary. LICENSE.txt has complete terms5---67# PPTX creation, editing, and analysis89## Overview1011A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.1213## Reading and analyzing content1415### Text extraction16If you just need to read the text contents of a presentation, you should convert the document to markdown:1718```bash19# Convert document to markdown20python -m markitdown path-to-file.pptx21```2223### Raw XML access24You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.2526#### Unpacking a file27`python ooxml/scripts/unpack.py <office_file> <output_dir>`2829**Note**: The unpack.py script is located at `skills/pptx/ooxml/scripts/unpack.py` relative to the project root. If the script doesn't exist at this path, use `find . -name "unpack.py"` to locate it.3031#### Key file structures32* `ppt/presentation.xml` - Main presentation metadata and slide references33* `ppt/slides/slide{N}.xml` - Individual slide contents (slide1.xml, slide2.xml, etc.)34* `ppt/notesSlides/notesSlide{N}.xml` - Speaker notes for each slide35* `ppt/comments/modernComment_*.xml` - Comments for specific slides36* `ppt/slideLayouts/` - Layout templates for slides37* `ppt/slideMasters/` - Master slide templates38* `ppt/theme/` - Theme and styling information39* `ppt/media/` - Images and other media files4041#### Typography and color extraction42**When given an example design to emulate**: Always analyze the presentation's typography and colors first using the methods below:431. **Read theme file**: Check `ppt/theme/theme1.xml` for colors (`<a:clrScheme>`) and fonts (`<a:fontScheme>`)442. **Sample slide content**: Examine `ppt/slides/slide1.xml` for actual font usage (`<a:rPr>`) and colors453. **Search for patterns**: Use grep to find color (`<a:solidFill>`, `<a:srgbClr>`) and font references across all XML files4647## Creating a new PowerPoint presentation **without a template**4849When creating a new PowerPoint presentation from scratch, use the **html2pptx** workflow to convert HTML slides to PowerPoint with accurate positioning.5051### Design Principles5253**CRITICAL**: Before creating any presentation, analyze the content and choose appropriate design elements:541. **Consider the subject matter**: What is this presentation about? What tone, industry, or mood does it suggest?552. **Check for branding**: If the user mentions a company/organization, consider their brand colors and identity563. **Match palette to content**: Select colors that reflect the subject574. **State your approach**: Explain your design choices before writing code5859**Requirements**:60- ✅ State your content-informed design approach BEFORE writing code61- ✅ Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact62- ✅ Create clear visual hierarchy through size, weight, and color63- ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment64- ✅ Be consistent: repeat patterns, spacing, and visual language across slides6566#### Color Palette Selection6768**Choosing colors creatively**:69- **Think beyond defaults**: What colors genuinely match this specific topic? Avoid autopilot choices.70- **Consider multiple angles**: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)71- **Be adventurous**: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy72- **Build your palette**: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)73- **Ensure contrast**: Text must be clearly readable on backgrounds7475**Example color palettes** (use these to spark creativity - choose one, adapt it, or create your own):76771. **Classic Blue**: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)782. **Teal & Coral**: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)793. **Bold Red**: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)804. **Warm Blush**: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)815. **Burgundy Luxury**: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)826. **Deep Purple & Emerald**: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)837. **Cream & Forest Green**: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)848. **Pink & Purple**: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)859. **Lime & Plum**: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)8610. **Black & Gold**: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)8711. **Sage & Terracotta**: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)8812. **Charcoal & Red**: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)8913. **Vibrant Orange**: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)9014. **Forest Green**: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)9115. **Retro Rainbow**: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)9216. **Vintage Earthy**: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)9317. **Coastal Rose**: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)9418. **Orange & Turquoise**: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)9596#### Visual Details Options9798**Geometric Patterns**:99- Diagonal section dividers instead of horizontal100- Asymmetric column widths (30/70, 40/60, 25/75)101- Rotated text headers at 90° or 270°102- Circular/hexagonal frames for images103- Triangular accent shapes in corners104- Overlapping shapes for depth105106**Border & Frame Treatments**:107- Thick single-color borders (10-20pt) on one side only108- Double-line borders with contrasting colors109- Corner brackets instead of full frames110- L-shaped borders (top+left or bottom+right)111- Underline accents beneath headers (3-5pt thick)112113**Typography Treatments**:114- Extreme size contrast (72pt headlines vs 11pt body)115- All-caps headers with wide letter spacing116- Numbered sections in oversized display type117- Monospace (Courier New) for data/stats/technical content118- Condensed fonts (Arial Narrow) for dense information119- Outlined text for emphasis120121**Chart & Data Styling**:122- Monochrome charts with single accent color for key data123- Horizontal bar charts instead of vertical124- Dot plots instead of bar charts125- Minimal gridlines or none at all126- Data labels directly on elements (no legends)127- Oversized numbers for key metrics128129**Layout Innovations**:130- Full-bleed images with text overlays131- Sidebar column (20-30% width) for navigation/context132- Modular grid systems (3×3, 4×4 blocks)133- Z-pattern or F-pattern content flow134- Floating text boxes over colored shapes135- Magazine-style multi-column layouts136137**Background Treatments**:138- Solid color blocks occupying 40-60% of slide139- Gradient fills (vertical or diagonal only)140- Split backgrounds (two colors, diagonal or vertical)141- Edge-to-edge color bands142- Negative space as a design element143144### Layout Tips145**When creating slides with charts or tables:**146- **Two-column layout (PREFERRED)**: Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.147- **Full-slide layout**: Let the featured content (chart/table) take up the entire slide for maximum impact and readability148- **NEVER vertically stack**: Do not place charts/tables below text in a single column - this causes poor readability and layout issues149150### Workflow1511. **MANDATORY - READ ENTIRE FILE**: Read [`html2pptx.md`](html2pptx.md) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.1522. Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)153 - Use `<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>` for all text content154 - Use `class="placeholder"` for areas where charts/tables will be added (render with gray background for visibility)155 - **CRITICAL**: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML156 - **LAYOUT**: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability1573. Create and run a JavaScript file using the [`html2pptx.js`](scripts/html2pptx.js) library to convert HTML slides to PowerPoint and save the presentation158 - Use the `html2pptx()` function to process each HTML file159 - Add charts and tables to placeholder areas using PptxGenJS API160 - Save the presentation using `pptx.writeFile()`1614. **Visual validation**: Generate thumbnails and inspect for layout issues162 - Create thumbnail grid: `python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4`163 - Read and carefully examine the thumbnail image for:164 - **Text cutoff**: Text being cut off by header bars, shapes, or slide edges165 - **Text overlap**: Text overlapping with other text or shapes166 - **Positioning issues**: Content too close to slide boundaries or other elements167 - **Contrast issues**: Insufficient contrast between text and backgrounds168 - If issues found, adjust HTML margins/spacing/colors and regenerate the presentation169 - Repeat until all slides are visually correct170171## Editing an existing PowerPoint presentation172173When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.174175### Workflow1761. **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.1772. Unpack the presentation: `python ooxml/scripts/unpack.py <office_file> <output_dir>`1783. Edit the XML files (primarily `ppt/slides/slide{N}.xml` and related files)1794. **CRITICAL**: Validate immediately after each edit and fix any validation errors before proceeding: `python ooxml/scripts/validate.py <dir> --original <file>`1805. Pack the final presentation: `python ooxml/scripts/pack.py <input_directory> <office_file>`181182## Creating a new PowerPoint presentation **using a template**183184When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.185186### Workflow1871. **Extract template text AND create visual thumbnail grid**:188 * Extract text: `python -m markitdown template.pptx > template-content.md`189 * Read `template-content.md`: Read the entire file to understand the contents of the template presentation. **NEVER set any range limits when reading this file.**190 * Create thumbnail grids: `python scripts/thumbnail.py template.pptx`191 * See [Creating Thumbnail Grids](#creating-thumbnail-grids) section for more details1921932. **Analyze template and save inventory to a file**:194 * **Visual Analysis**: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure195 * Create and save a template inventory file at `template-inventory.md` containing:196 ```markdown197 # Template Inventory Analysis198 **Total Slides: [count]**199 **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**200201 ## [Category Name]202 - Slide 0: [Layout code if available] - Description/purpose203 - Slide 1: [Layout code] - Description/purpose204 - Slide 2: [Layout code] - Description/purpose205 [... EVERY slide must be listed individually with its index ...]206 ```207 * **Using the thumbnail grid**: Reference the visual thumbnails to identify:208 - Layout patterns (title slides, content layouts, section dividers)209 - Image placeholder locations and counts210 - Design consistency across slide groups211 - Visual hierarchy and structure212 * This inventory file is REQUIRED for selecting appropriate templates in the next step2132143. **Create presentation outline based on template inventory**:215 * Review available templates from step 2.216 * Choose an intro or title template for the first slide. This should be one of the first templates.217 * Choose safe, text-based layouts for the other slides.218 * **CRITICAL: Match layout structure to actual content**:219 - Single-column layouts: Use for unified narrative or single topic220 - Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts221 - Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts222 - Image + text layouts: Use ONLY when you have actual images to insert223 - Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis224 - Never use layouts with more placeholders than you have content225 - If you have 2 items, don't force them into a 3-column layout226 - If you have 4+ items, consider breaking into multiple slides or using a list format227 * Count your actual content pieces BEFORE selecting the layout228 * Verify each placeholder in the chosen layout will be filled with meaningful content229 * Select one option representing the **best** layout for each content section.230 * Save `outline.md` with content AND template mapping that leverages available designs231 * Example template mapping:232 ```233 # Template slides to use (0-based indexing)234 # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72235 # Mapping: slide numbers from outline -> template slide indices236 template_mapping = [237 0, # Use slide 0 (Title/Cover)238 34, # Use slide 34 (B1: Title and body)239 34, # Use slide 34 again (duplicate for second B1)240 50, # Use slide 50 (E1: Quote)241 54, # Use slide 54 (F2: Closing + Text)242 ]243 ```2442454. **Duplicate, reorder, and delete slides using `rearrange.py`**:246 * Use the `scripts/rearrange.py` script to create a new presentation with slides in the desired order:247 ```bash248 python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52249 ```250 * The script handles duplicating repeated slides, deleting unused slides, and reordering automatically251 * Slide indices are 0-based (first slide is 0, second is 1, etc.)252 * The same slide index can appear multiple times to duplicate that slide2532545. **Extract ALL text using the `inventory.py` script**:255 * **Run inventory extraction**:256 ```bash257 python scripts/inventory.py working.pptx text-inventory.json258 ```259 * **Read text-inventory.json**: Read the entire text-inventory.json file to understand all shapes and their properties. **NEVER set any range limits when reading this file.**260261 * The inventory JSON structure:262 ```json263 {264 "slide-0": {265 "shape-0": {266 "placeholder_type": "TITLE", // or null for non-placeholders267 "left": 1.5, // position in inches268 "top": 2.0,269 "width": 7.5,270 "height": 1.2,271 "paragraphs": [272 {273 "text": "Paragraph text",274 // Optional properties (only included when non-default):275 "bullet": true, // explicit bullet detected276 "level": 0, // only included when bullet is true277 "alignment": "CENTER", // CENTER, RIGHT (not LEFT)278 "space_before": 10.0, // space before paragraph in points279 "space_after": 6.0, // space after paragraph in points280 "line_spacing": 22.4, // line spacing in points281 "font_name": "Arial", // from first run282 "font_size": 14.0, // in points283 "bold": true,284 "italic": false,285 "underline": false,286 "color": "FF0000" // RGB color287 }288 ]289 }290 }291 }292 ```293294 * Key features:295 - **Slides**: Named as "slide-0", "slide-1", etc.296 - **Shapes**: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.297 - **Placeholder types**: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null298 - **Default font size**: `default_font_size` in points extracted from layout placeholders (when available)299 - **Slide numbers are filtered**: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory300 - **Bullets**: When `bullet: true`, `level` is always included (even if 0)301 - **Spacing**: `space_before`, `space_after`, and `line_spacing` in points (only included when set)302 - **Colors**: `color` for RGB (e.g., "FF0000"), `theme_color` for theme colors (e.g., "DARK_1")303 - **Properties**: Only non-default values are included in the output3043056. **Generate replacement text and save the data to a JSON file**306 Based on the text inventory from the previous step:307 - **CRITICAL**: First verify which shapes exist in the inventory - only reference shapes that are actually present308 - **VALIDATION**: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory309 - If you reference a non-existent shape, you'll get an error showing available shapes310 - If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist311 - All validation errors are shown at once before the script exits312 - **IMPORTANT**: The replace.py script uses inventory.py internally to identify ALL text shapes313 - **AUTOMATIC CLEARING**: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them314 - Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")315 - Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically316 - Paragraphs with bullets will be automatically left aligned. Don't set the `alignment` property on when `"bullet": true`317 - Generate appropriate replacement content for placeholder text318 - Use shape size to determine appropriate content length319 - **CRITICAL**: Include paragraph properties from the original inventory - don't just provide text320 - **IMPORTANT**: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically321 - **ESSENTIAL FORMATTING RULES**:322 - Headers/titles should typically have `"bold": true`323 - List items should have `"bullet": true, "level": 0` (level is required when bullet is true)324 - Preserve any alignment properties (e.g., `"alignment": "CENTER"` for centered text)325 - Include font properties when different from default (e.g., `"font_size": 14.0`, `"font_name": "Lora"`)326 - Colors: Use `"color": "FF0000"` for RGB or `"theme_color": "DARK_1"` for theme colors327 - The replacement script expects **properly formatted paragraphs**, not just text strings328 - **Overlapping shapes**: Prefer shapes with larger default_font_size or more appropriate placeholder_type329 - Save the updated inventory with replacements to `replacement-text.json`330 - **WARNING**: Different template layouts have different shape counts - always check the actual inventory before creating replacements331332 Example paragraphs field showing proper formatting:333 ```json334 "paragraphs": [335 {336 "text": "New presentation title text",337 "alignment": "CENTER",338 "bold": true339 },340 {341 "text": "Section Header",342 "bold": true343 },344 {345 "text": "First bullet point without bullet symbol",346 "bullet": true,347 "level": 0348 },349 {350 "text": "Red colored text",351 "color": "FF0000"352 },353 {354 "text": "Theme colored text",355 "theme_color": "DARK_1"356 },357 {358 "text": "Regular paragraph text without special formatting"359 }360 ]361 ```362363 **Shapes not listed in the replacement JSON are automatically cleared**:364 ```json365 {366 "slide-0": {367 "shape-0": {368 "paragraphs": [...] // This shape gets new text369 }370 // shape-1 and shape-2 from inventory will be cleared automatically371 }372 }373 ```374375 **Common formatting patterns for presentations**:376 - Title slides: Bold text, sometimes centered377 - Section headers within slides: Bold text378 - Bullet lists: Each item needs `"bullet": true, "level": 0`379 - Body text: Usually no special properties needed380 - Quotes: May have special alignment or font properties3813827. **Apply replacements using the `replace.py` script**383 ```bash384 python scripts/replace.py working.pptx replacement-text.json output.pptx385 ```386387 The script will:388 - First extract the inventory of ALL text shapes using functions from inventory.py389 - Validate that all shapes in the replacement JSON exist in the inventory390 - Clear text from ALL shapes identified in the inventory391 - Apply new text only to shapes with "paragraphs" defined in the replacement JSON392 - Preserve formatting by applying paragraph properties from the JSON393 - Handle bullets, alignment, font properties, and colors automatically394 - Save the updated presentation395396 Example validation errors:397 ```398 ERROR: Invalid shapes in replacement JSON:399 - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4400 - Slide 'slide-999' not found in inventory401 ```402403 ```404 ERROR: Replacement text made overflow worse in these shapes:405 - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")406 ```407408## Creating Thumbnail Grids409410To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:411412```bash413python scripts/thumbnail.py template.pptx [output_prefix]414```415416**Features**:417- Creates: `thumbnails.jpg` (or `thumbnails-1.jpg`, `thumbnails-2.jpg`, etc. for large decks)418- Default: 5 columns, max 30 slides per grid (5×6)419- Custom prefix: `python scripts/thumbnail.py template.pptx my-grid`420 - Note: The output prefix should include the path if you want output in a specific directory (e.g., `workspace/my-grid`)421- Adjust columns: `--cols 4` (range: 3-6, affects slides per grid)422- Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42423- Slides are zero-indexed (Slide 0, Slide 1, etc.)424425**Use cases**:426- Template analysis: Quickly understand slide layouts and design patterns427- Content review: Visual overview of entire presentation428- Navigation reference: Find specific slides by their visual appearance429- Quality check: Verify all slides are properly formatted430431**Examples**:432```bash433# Basic usage434python scripts/thumbnail.py presentation.pptx435436# Combine options: custom name, columns437python scripts/thumbnail.py template.pptx analysis --cols 4438```439440## Converting Slides to Images441442To visually analyze PowerPoint slides, convert them to images using a two-step process:4434441. **Convert PPTX to PDF**:445 ```bash446 soffice --headless --convert-to pdf template.pptx447 ```4484492. **Convert PDF pages to JPEG images**:450 ```bash451 pdftoppm -jpeg -r 150 template.pdf slide452 ```453 This creates files like `slide-1.jpg`, `slide-2.jpg`, etc.454455Options:456- `-r 150`: Sets resolution to 150 DPI (adjust for quality/size balance)457- `-jpeg`: Output JPEG format (use `-png` for PNG if preferred)458- `-f N`: First page to convert (e.g., `-f 2` starts from page 2)459- `-l N`: Last page to convert (e.g., `-l 5` stops at page 5)460- `slide`: Prefix for output files461462Example for specific range:463```bash464pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide # Converts only pages 2-5465```466467## Code Style Guidelines468**IMPORTANT**: When generating code for PPTX operations:469- Write concise code470- Avoid verbose variable names and redundant operations471- Avoid unnecessary print statements472473## Dependencies474475Required dependencies (should already be installed):476477- **markitdown**: `pip install "markitdown[pptx]"` (for text extraction from presentations)478- **pptxgenjs**: `npm install -g pptxgenjs` (for creating presentations via html2pptx)479- **playwright**: `npm install -g playwright` (for HTML rendering in html2pptx)480- **react-icons**: `npm install -g react-icons react react-dom` (for icons)481- **sharp**: `npm install -g sharp` (for SVG rasterization and image processing)482- **LibreOffice**: `sudo apt-get install libreoffice` (for PDF conversion)483- **Poppler**: `sudo apt-get install poppler-utils` (for pdftoppm to convert PDF to images)484- **defusedxml**: `pip install defusedxml` (for secure XML parsing)
Full transparency — inspect the skill content before installing.