pptx-generator — Автоматизированное создание презентаций и слайдов

--- name: pptx-generator description: | Generate and edit presentation slides as PPTX files. Also create LinkedIn carousels and manage reusable slide layouts. TRIGGERS - Use this skill when user says: - "create slides for [brand]" / "generate presentation for [brand]" / "make slides for [brand]" - "create a carousel for [brand]" / "linkedin carousel" / "make a carousel about [topic]" - "edit this pptx" / "update the slides" / "modify this presentation" - "create a new layout" / "add a layout to the cookbook" / "make a [type] layout template" - "edit the [name] layout" / "update the cookbook" / "improve the [name] template" - Any request mentioning slides, presentations, carousels, PPTX, or layouts with a brand name Creates .pptx files compatible with PowerPoint, Google Slides, and Keynote. Creates PDF carousels for LinkedIn (square 1:1 format). --- # PPTX Slide Generator Generate professional, on-brand presentation slides using python-pptx. This skill supports: - **Slide Generation** - Create presentations for any brand in `brands/` - **Carousel Generation** - Create LinkedIn carousels (square format, exports to PDF) - **Slide Editing** - Modify existing PPTX files - **Layout Management** - Create, edit, update cookbook layouts **IMPORTANT:** All skill resources are in `.claude/skills/pptx-generator/`. Always use Glob patterns starting with `.claude/skills/pptx-generator/` to find files. --- ## ⚠️ CRITICAL: Batch Generation Rules **NEVER generate more than 5 slides at once.** | Rule | Details | |------|---------| | Max slides per batch | **5** (can be 1, 2, 3, 4, or 5) | | After each batch | **STOP and validate output** | | Validation required | Check: no duplicate titles, proper spacing, correct colors | | Continue when | Validation passes | | **After ALL batches** | **COMBINE into single file and DELETE part files** | This prevents token limit errors and catches quality issues early. **CRITICAL: Always clean up part files after combining.** The user should only see ONE final PPTX file, not multiple part files. --- ## ⚠️ PREREQUISITE: Brand Check **Before generating slides, check if any brands exist.** ``` Glob: .claude/skills/pptx-generator/brands/*/brand.json ``` **If NO brands found (only `template/` exists):** 1. **STOP** - Do not proceed with slide generation 2. **Ask the user:** > "No brands are configured yet. Would you like me to help you create a brand first? > I'll need your brand colors, fonts, and style guidelines to set this up." 3. **If user wants to create a brand**, follow the **Creating a New Brand** section below. 4. **If user declines**, explain that slides require a brand configuration and offer to use generic styling as a fallback. --- ## Creating a New Brand When no brands exist or user requests a new brand: ### Step 1: Read the Template ``` Read: .claude/skills/pptx-generator/brands/template/README.md Read: .claude/skills/pptx-generator/brands/template/brand.json Read: .claude/skills/pptx-generator/brands/template/config.json ``` ### Step 2: Gather Brand Information Ask the user for (or extract from provided materials): | Required | Description | |----------|-------------| | **Brand name** | Folder name (lowercase, no spaces) | | **Colors** | Background, text, accent colors (hex codes) | | **Fonts** | Heading font, body font, code font | | Optional | Description | |----------|-------------| | Output directory | Where to save generated files (default: `output/{brand}`) | | Logo | Path to logo file (PNG/SVG) | | Brand guidelines | Existing style guide or website to reference | | Tone of voice | Writing style, vocabulary preferences | ### Step 3: Create Brand Files 1. **Create the brand folder:** ```bash mkdir -p .claude/skills/pptx-generator/brands/{brand-name} ``` 2. **Create brand.json** with the gathered values: ```json { "name": "Brand Name", "description": "One-line description", "colors": { "background": "hex-without-hash", "background_alt": "hex-without-hash", "text": "hex-without-hash", "text_secondary": "hex-without-hash", "accent": "hex-without-hash", "accent_secondary": "hex-without-hash", "accent_tertiary": "hex-without-hash", "code_bg": "hex-without-hash", "card_bg": "hex-without-hash", "card_bg_alt": "hex-without-hash" }, "fonts": { "heading": "Font Name", "body": "Font Name", "code": "Monospace Font" }, "assets": { "logo": "assets/logo.png", "logo_dark": null, "icon": null } } ``` 3. **Create config.json** with output settings: ```json { "output": { "directory": "output/{brand}", "naming": "{name}-{date}", "keep_parts": false }, "generation": { "slides_per_batch": 5, "auto_combine": true, "open_after_generate": false }, "defaults": { "slide_width_inches": 13.333, "slide_height_inches": 7.5 } } ``` 4. **Create brand-system.md** - Copy from template and fill in brand guidelines 5. **Create tone-of-voice.md** - Copy from template and fill in voice guidelines 6. **Add assets** - Copy logo/images to `brands/{brand-name}/assets/` ### Step 4: Verify After creating the brand, verify with: ``` Glob: .claude/skills/pptx-generator/brands/{brand-name}/* ``` Then proceed to slide generation. --- ## Skill Modes This skill operates in three modes: ### Mode 1: Generate Presentation Slides User wants presentation slides (16:9) created using a brand's styling. → Follow: Brand Discovery → Layout Selection → Content Adaptation → Execute → Layouts in: `cookbook/*.py` ### Mode 2: Generate LinkedIn Carousels User wants a LinkedIn carousel (square 1:1 format) for social media. → Follow: Brand Discovery → Carousel Planning → Generate → Export PDF → Layouts in: `cookbook/carousels/*.py` ### Mode 3: Manage Cookbook Layouts User wants to create, edit, or improve layout templates. → Follow: Layout CRUD Operations section --- ## Mode 1: Generate Presentation Slides ### Step 1: Brand Discovery 1. **List available brands:** ``` Glob: .claude/skills/pptx-generator/brands/*/brand.json ``` Extract unique brand names from paths (e.g., `brands/rasmus/...` → "rasmus") 2. **Read the brand configuration files:** ``` Read: .claude/skills/pptx-generator/brands/{brand-name}/brand.json Read: .claude/skills/pptx-generator/brands/{brand-name}/config.json ``` - `brand.json` - Colors, fonts, assets - `config.json` - Output directory, generation settings 3. **Read supporting markdown files for context:** ``` Glob: .claude/skills/pptx-generator/brands/{brand-name}/*.md ``` These provide voice, tone, and design philosophy. 4. **Extract from brand files:** - **From brand.json:** Colors (hex without #), fonts, asset paths - **From config.json:** Output directory, slides per batch, naming convention - **From markdown:** Voice, tone, vocabulary, visual principles If brand not found, list available brands and ask user to choose. ### Step 2: Layout Discovery (READ ALL FRONTMATTERS) **⚠️ MANDATORY: Read ALL layout frontmatters before selecting any layout.** This step is critical for making informed layout decisions. You must understand what ALL layouts offer before choosing. **Step 2a: Discover all layouts:** ``` Glob: .claude/skills/pptx-generator/cookbook/*.py ``` **Step 2b: Read EVERY layout file** (not just one or two): For each `.py` file found, read the first 40 lines to extract the `# /// layout` frontmatter block. Build a mental map of: - What each layout is for (`purpose`, `best_for`) - What each layout should NOT be used for (`avoid_when`) - Limits and constraints (`max_*`, `min_*`, `*_max_chars`) **The frontmatter block** looks like this: ```python # /// layout # name = "floating-cards-slide" # purpose = "Feature highlights, process steps, multiple equal items with depth" # best_for = [ # "Exactly 3 related features or concepts", # "Process with 3 steps", # ] # avoid_when = [ # "More than 3 items - use multi-card-slide instead", # "Long card titles (over 15 characters)", # ] # max_cards = 3 # card_title_max_chars = 15 # instructions = [ # "EXACTLY 3 cards required - no more, no less", # "Card titles must be SHORT: 1-2 words, max 15 characters", # ] # /// ``` **Key frontmatter fields:** | Field | Description | |-------|-------------| | `name` | Layout identifier | | `purpose` | What this layout is for | | `best_for` | Ideal use cases (array) | | `avoid_when` | When NOT to use this layout (array) | | `max_*` / `min_*` | Item limits (cards, bullets, stats) | | `instructions` | Specific tips for using this layout | **Step 2c: Select layouts** (only AFTER reading all frontmatters): Now that you know all available layouts and their constraints: 1. User specifies layout → Use that layout (but verify it fits the content) 2. User describes content → Match to best-fitting `best_for` criteria 3. **Check `avoid_when`** → Don't use a layout in situations it warns against 4. **Respect limits** → If content exceeds `max_*`, use a different layout 5. Multiple slides needed → Select appropriate layout for each 6. No good fit → Create a custom layout (see Mode 2) **Example selection process:** - User wants "5 pillars of AI infrastructure" - You've read all frontmatters and know: - `floating-cards-slide`: `max_cards = 3` → Won't work - `multi-card-slide`: `max_cards = 5` → Perfect fit - Select `multi-card-slide` **Why read ALL frontmatters?** - Layouts reference each other in `avoid_when` (e.g., "use multi-card-slide instead") - You can't make the right choice without knowing all options - Prevents backtracking when a layout doesn't fit ### Step 2d: Visual-First Layout Selection (CRITICAL FOR VARIETY) **🎨 DEFAULT TO VISUAL LAYOUTS. Content-slide is the LAST RESORT, not the default.** #### The Variety Problem The biggest mistake in presentation generation is **defaulting to content-slide** (title + bullets) whenever you have information to convey. This creates repetitive, boring presentations. **Common failure pattern:** - 11 out of 30 slides = content-slide (37% repetition) - User says "this lacks variety" - You think "but I used 11 different layout types!" - Reality: Layout variety exists, but distribution is terrible #### Variety Enforcement Rules **HARD LIMITS:** 1. **Never use the same layout more than 2-3 times consecutively** 2. **Content-slide should be <25% of total slides** (not 35-40%) 3. **Visual layouts (cards, stats, columns, hero, diagonal) should be 50%+ of slides** 4. **Section breaks are NOT variety** - they're structural (don't count toward variety) #### Decision Tree: "Should I Use content-slide?" Ask these questions IN ORDER before defaulting to content-slide: ``` Do I have 3-5 equal items? YES → Use multi-card-slide (not content-slide) Do I have 2-4 big numbers/metrics? YES → Use stats-slide (not content-slide) Am I comparing two things? YES → Use two-column-slide (not content-slide) Do I have a central concept with surrounding items? YES → Use circular-hero-slide (not content-slide) Do I have exactly 3 related items? YES → Use floating-cards-slide (not content-slide) Do I have 1-3 words I want to emphasize dramatically? YES → Use giant-focus-slide or bold-diagonal-slide (not content-slide) Do I have a powerful quote or principle? YES → Use quote-slide (not content-slide) Is this the ONLY way to present this information? YES → NOW you can use content-slide NO → Go back through the decision tree ``` #### Transforming Bullets Into Visual Layouts **Example 1: "Validation Patterns"** ❌ **BAD (content-slide):** ``` Title: Validation Patterns Bullets: - Run comprehensive test suites - Type checking and linting - Code review by humans and AI - Deployment previews ``` ✅ **GOOD (multi-card-slide):** ``` Title: Validation Patterns Cards: 1. Testing | Run comprehensive test suites after every change 2. Linting | Type checking and formatting as guardrails 3. Review | Human and AI code review process 4. Preview | Deployment previews for visual regression ``` **Example 2: "Why PIV Works"** ❌ **BAD (content-slide):** ``` Title: Why PIV Works Bullets: - Forces planning before implementation - Validation catches issues immediately - Iterative improvements compound - System gets smarter with every bug ``` ✅ **GOOD (floating-cards-slide with 3 cards):** ``` Title: Why PIV Works Cards: 1. Plan First | Forces architectural thinking before coding 2. Fast Feedback | Validation catches issues immediately 3. Compounds | System improves with every bug ``` (Note: Reduced from 4 to 3 items to fit floating-cards-slide `max_cards` limit) **Example 3: "Human-in-the-Loop Strategy"** ❌ **BAD (content-slide):** ``` Title: Human-in-the-Loop Strategy Bullets: - In-the-loop: Human approves before execution - On-the-loop: Human reviews after completion - Code review remains critical - AI generates, humans validate ``` ✅ **GOOD (two-column-slide):** ``` Title: Human-in-the-Loop Strategy Left: In-the-Loop - Human approves before execution - Critical for production changes - Quality gateway Right: On-the-Loop - Human reviews after completion - Faster iteration cycles - AI generates, human validates ``` #### Active Visual Thinking Before planning any slide, ask yourself: 1. **"Can this be more visual?"** - The answer is almost always YES 2. **"Have I used content-slide in the last 2 slides?"** - If yes, use something else 3. **"Does this slide look like the previous slide?"** - If yes, change the layout 4. **"Am I falling into a pattern?"** - Break it immediately 5. **"Would this be more engaging as cards/columns/stats?"** - Usually yes #### When content-slide IS Appropriate Use content-slide ONLY when: - You've genuinely tried all other layouts and they don't fit - The information is inherently linear and textual (rare) - You need a "breather" slide between two complex visuals - You're at your layout distribution limits (already used all the visual ones recently) **Never use content-slide as your default thinking.** #### Quick Reference: Content Type → Best Layout | Content Type | Best Layout | Why | |--------------|-------------|-----| | 3-5 equal features/steps | multi-card-slide | Cards create visual hierarchy | | Exactly 3 featured items | floating-cards-slide | Elevated cards add depth | | 2-4 metrics/KPIs | stats-slide | Big numbers grab attention | | Before/after comparison | two-column-slide | Side-by-side shows contrast | | Hub concept with types | circular-hero-slide | Radiating pattern shows relationships | | Dramatic emphasis (1-3 words) | giant-focus-slide | Scale creates impact | | High-energy warning | bold-diagonal-slide | Dynamic shapes convey urgency | | Powerful quote/principle | quote-slide | Attribution adds authority | | List of related items | multi-card-slide | Better than bullets | | Process with steps | floating-cards-slide | Visual flow beats text | | Technical comparison | two-column-slide | Structured comparison | **Only use content-slide when:** - None of the above fit - Information is truly linear - Need a text-heavy breather between visual slides - Already hit variety limits ### Step 3: Slide Planning (ALWAYS DO THIS) **Before generating ANY slides, create a written plan.** This applies to single slides, batches, and full presentations. Planning prevents: - Duplicate content across slides - Wrong layout choices - Missing key information - Poor flow and structure **Create a slide plan table:** ```markdown | # | Layout | Title | Key Content | Notes | |---|--------|-------|-------------|-------| | 1 | title-slide | [Title] | [Subtitle, author] | Opening slide | | 2 | content-slide | [Title] | [3-4 bullet points] | Main concepts | | 3 | stats-slide | [Title] | [2-3 metrics] | Impact data | | ... | ... | ... | ... | ... | ``` **For each slide, specify:** - **Slide number** - Position in presentation - **Layout** - Which cookbook layout to use - **Title** - Exact title text (check for duplicates!) - **Key content** - Bullet points, stats, quotes, etc. - **Notes** - Any special considerations **Planning checklist:** - [ ] No duplicate titles across slides - [ ] Logical flow from slide to slide - [ ] Appropriate layout for each content type - [ ] Content fits the chosen layout - [ ] Batches are logically grouped (5 slides max each) - [ ] **VARIETY CHECK: Content-slide used <25% of total slides** - [ ] **VARIETY CHECK: No more than 2-3 consecutive slides with same layout** - [ ] **VARIETY CHECK: Visual layouts (cards, stats, columns, hero) are 50%+ of slides** - [ ] **VARIETY CHECK: Each content-slide was evaluated against decision tree first** **After planning, briefly present the plan before generating.** **Example of good variety distribution for 30-slide presentation:** - Content-slide: 6-7 slides (20-23%) - Section breaks: 5 slides (17%) - Visual layouts: 15-16 slides (50-53%) - Multi-card: 3-4 slides - Two-column: 2-3 slides - Stats: 1-2 slides - Floating-cards: 2-3 slides - Circular-hero: 1-2 slides - Giant-focus/Bold-diagonal: 2-3 slides - Quote: 1 slide - Title/Closing: 2-3 slides (7-10%) ### Step 4: Content Adaptation **For each slide in your plan:** #### Presentation Text Formatting Rules **IMPORTANT: Follow these rules for ALL slide text.** | Element | Rule | Example | |---------|------|---------| | Titles | No trailing periods or commas | "Why AI Matters" not "Why AI Matters." | | Subtitles | No trailing punctuation | "The future of coding" not "The future of coding." | | Bullet points | No trailing periods (unless full sentences) | "Faster development" not "Faster development." | | Headlines | Minimal punctuation, no ellipsis | "What's Next" not "What's Next..." | | Stats/Numbers | Clean format, no trailing punctuation | "50%" not "50%." | | CTAs | No trailing punctuation | "Get Started" not "Get Started." | | Labels | Short, no punctuation | "Step 1" not "Step 1:" | **Avoid:** - Trailing periods on titles, bullets, labels - Ellipsis (...) in headlines - Excessive commas in short phrases - Colons at end of labels/headers - Semicolons in bullet points **Exception:** Full sentence descriptions or quotes may use appropriate punctuation. #### Brand Value Mapping 1. **Map brand.json values to layout placeholders:** | Layout Placeholder | brand.json Path | |--------------------|-----------------| | `BRAND_BG` | `colors.background` | | `BRAND_BG_ALT` | `colors.background_alt` | | `BRAND_TEXT` | `colors.text` | | `BRAND_TEXT_SECONDARY` | `colors.text_secondary` | | `BRAND_ACCENT` | `colors.accent` | | `BRAND_ACCENT_SECONDARY` | `colors.accent_secondary` | | `BRAND_ACCENT_TERTIARY` | `colors.accent_tertiary` | | `BRAND_CODE_BG` | `colors.code_bg` | | `BRAND_CARD_BG` | `colors.card_bg` | | `BRAND_CARD_BG_ALT` | `colors.card_bg_alt` | | `BRAND_HEADING_FONT` | `fonts.heading` | | `BRAND_BODY_FONT` | `fonts.body` | | `BRAND_CODE_FONT` | `fonts.code` | **Note:** All color values in brand.json are hex WITHOUT the `#` prefix. 2. **Write content in brand's voice** (from tone-of-voice.md) 3. **Preserve layout structure** (decorative elements, spacing, hierarchy) ### Step 5: Batch Generation (CRITICAL) **MAXIMUM 5 SLIDES PER BATCH. This is a hard limit.** When generating multiple slides: 1. Generate 1-5 slides in a single PPTX file 2. **STOP and review the output** before generating more 3. Only after validation passes, continue with the next batch 4. Repeat until all slides are generated **Why batching matters:** - Prevents token limit errors - Allows quality checks between batches - Catches issues early before they propagate **⚠️ CRITICAL BACKGROUND BUG FIX:** **EVERY slide MUST have its background explicitly set.** If you don't set `slide.background.fill.solid()` and `slide.background.fill.fore_color.rgb`, the slide will use PowerPoint's default WHITE background, making text unreadable on dark-themed brands. **Mandatory for every slide:** ```python slide = prs.slides.add_slide(prs.slide_layouts[6]) slide.background.fill.solid() # ← REQUIRED slide.background.fill.fore_color.rgb = hex_to_rgb(BRAND_BG) # ← REQUIRED ``` This is especially critical when: - Generating multiple batches (each batch is a new Presentation object) - Using helper functions to create slides - Combining separate PPTX files **Execution:** **PREFERRED: Use heredoc (no files created):** ```bash uv run --with python-pptx==1.0.2 python << 'EOF' # [Adapted code with brand values and content] EOF ``` **IF heredoc fails (Windows issues): Use temp directory:** ```bash # Create temp directory if needed mkdir -p .claude/skills/pptx-generator/.tmp # Write script to temp directory # (create file at .claude/skills/pptx-generator/.tmp/gen.py) # Execute uv run --with python-pptx==1.0.2 python .claude/skills/pptx-generator/.tmp/gen.py # MANDATORY: Clean up immediately after execution rm .claude/skills/pptx-generator/.tmp/gen.py ``` **CRITICAL: Never create Python files in the repository root.** Always use heredoc or temp directory within the skill folder. ### Step 6: Quality Validation (MANDATORY) **After EVERY batch, validate before continuing:** 1. **Open the generated PPTX** and visually inspect it 2. **Check for these common issues:** | Issue | What to Look For | Fix | |-------|------------------|-----| | White background | Slide has white background instead of brand color | Add slide.background.fill.solid() and set fore_color.rgb | | Duplicate titles | Same title text appearing twice on a slide | Remove duplicate text boxes | | Spacing problems | Title too close to subtitle/content | Increase Y position of lower elements | | Text overflow | Content extending beyond slide bounds | Reduce font size or split content | | Missing elements | Decorative elements not rendering | Check shape positions and colors | | Wrong colors | Colors not matching brand | Verify hex values (no # prefix in code) | | Bad punctuation | Trailing periods/commas on titles/bullets | Remove unnecessary punctuation | 3. **If issues found:** - Fix the current batch before continuing - Note the issue to avoid repeating in future batches 4. **If validation passes:** - Continue to next batch of slides ### Step 7: Output **Use the output settings from config.json:** | Config Setting | Default | Description | |----------------|---------|-------------| | `output.directory` | `output/{brand}` | Where to save files | | `output.naming` | `{name}-{date}` | File naming pattern | | `output.keep_parts` | `false` | Keep part files after combining | **Resolve placeholders:** - `{brand}` → Brand folder name - `{name}` → Presentation name from user request - `{date}` → Current date (YYYY-MM-DD) ```bash # Create output directory from config mkdir -p {resolved-output-directory} ``` **Batched generation workflow:** 1. Generate each batch as `{name}-part1.pptx`, `{name}-part2.pptx`, etc. 2. Validate each batch before continuing 3. After ALL batches complete, **combine into final file** (if `auto_combine` is true) 4. Delete part files (if `keep_parts` is false) ### Step 8: Combine Batches (for multi-batch presentations) **🚨 CRITICAL BUG WARNING: BACKGROUND MUST BE SET WHEN COMBINING 🚨** When combining presentations, `add_slide()` creates slides with **DEFAULT WHITE BACKGROUNDS**. Shape copying does NOT copy the slide background property. You MUST explicitly set the background immediately after creating each new slide. **This is the most common source of white slides in combined presentations.** After all batches are validated, combine them into a single PPTX: ```bash uv run --with python-pptx==1.0.2 python << 'SCRIPT' from pptx import Presentation from pptx.dml.color import RGBColor from pathlib import Path import shutil def hex_to_rgb(hex_color: str) -> RGBColor: h = hex_color.lstrip("#") return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)) # Brand background color (get from brand.json) BRAND_BG = "REPLACE_WITH_BRAND_BACKGROUND" # e.g., "07090F" # List all part files in order output_dir = Path("output/{brand-name}") part_files = sorted(output_dir.glob("{name}-part*.pptx")) if len(part_files) > 1: # Start with first part as base combined = Presentation(part_files[0]) # Add slides from remaining parts for part_file in part_files[1:]: part_prs = Presentation(part_file) for slide in part_prs.slides: # Copy slide layout and add to combined blank_layout = combined.slide_layouts[6] new_slide = combined.slides.add_slide(blank_layout) # 🚨 CRITICAL: Set background IMMEDIATELY after creating slide # PowerPoint defaults to WHITE background - this MUST be set before copying shapes new_slide.background.fill.solid() new_slide.background.fill.fore_color.rgb = hex_to_rgb(BRAND_BG) # Copy all shapes from source slide for shape in slide.shapes: # Clone shape to new slide el = shape.element new_slide.shapes._spTree.insert_element_before( el, 'p:extLst' ) # Save combined file combined.save(output_dir / "{name}-final.pptx") print(f"Combined {len(part_files)} parts into {name}-final.pptx") # MANDATORY: Clean up part files - user should only see final file for part_file in part_files: part_file.unlink() print(f"Deleted {part_file.name}") else: # Single part, just rename shutil.move(part_files[0], output_dir / "{name}-final.pptx") SCRIPT ``` **Final output:** `output/{brand-name}/{name}-final.pptx` **Why this bug happens:** - `combined.slides.add_slide()` creates a NEW slide object with PowerPoint's default white background - `shapes._spTree.insert_element_before()` copies shapes (text, rectangles, images) but NOT the background - The background is a slide property, not a shape, so it must be set separately - Without explicit background setting, slides 6-30 (or however many are added after the base) will be white **Testing checklist after combining:** - [ ] Open the combined PPTX - [ ] Scroll through ALL slides (not just the first few) - [ ] Verify EVERY slide has the correct background color - [ ] If any white slides found, the combination code is missing the background setting --- ## Mode 2: Generate LinkedIn Carousels LinkedIn carousels are multi-page PDFs in square (1:1) format. Each page is a swipeable slide. ### Carousel vs Presentation | Aspect | Presentation | Carousel | |--------|--------------|----------| | Dimensions | 16:9 (13.333" × 7.5") | 1:1 (7.5" × 7.5") | | Layouts | `cookbook/*.py` | `cookbook/carousels/*.py` | | Output | PPTX | PDF (via PPTX conversion) | | Slides | 10-50+ typical | 5-10 optimal | | Text size | Standard | Larger (mobile readable) | | Content | Detailed | One idea per slide | ### Step 1: Brand Discovery Same as Mode 1 - read brand.json, config.json, and tone-of-voice.md. ### Step 2: Carousel Layout Discovery **Discover carousel-specific layouts:** ``` Glob: .claude/skills/pptx-generator/cookbook/carousels/*.py ``` **Available carousel layouts:** | Layout | Purpose | Best For | |--------|---------|----------| | `hook-slide` | Opening attention-grabber | First slide only | | `single-point-slide` | One key point with explanation | Body content | | `numbered-point-slide` | Numbered list item with big number | Listicles, steps | | `quote-slide` | Quote with attribution | Social proof, insights | | `cta-slide` | Call to action | Last slide only | Read frontmatters to understand limits and constraints for each. ### Step 3: Carousel Planning **Typical carousel structure (5-10 slides):** ```markdown | # | Layout | Content | |---|--------|---------| | 1 | hook-slide | Attention-grabbing hook | | 2-8 | single-point or numbered-point | Body content | | 9/10 | cta-slide | Call to action | ``` **Carousel content rules:** - **One idea per slide** - Don't cram multiple points - **Large text** - Must be readable on mobile - **Short copy** - Max 50 chars for headlines, 150 for body - **Clear flow** - Each slide should make sense if viewed alone - **Strong hook** - First slide stops the scroll - **Clear CTA** - Last slide tells them what to do ### Step 4: Generate Carousel **Carousel dimensions (square 1:1):** ```python prs.slide_width = Inches(7.5) prs.slide_height = Inches(7.5) ``` Generate all slides as a single PPTX file (carousels are typically 5-10 slides, so batching rarely needed). **Execution:** ```bash uv run --with python-pptx==1.0.2 python << 'SCRIPT' # Carousel generation code with 7.5" x 7.5" dimensions SCRIPT ``` ### Step 5: Export to PDF LinkedIn requires PDF for carousel posts. Convert the PPTX to PDF: **Option A: Using LibreOffice (recommended)** ```bash libreoffice --headless --convert-to pdf --outdir output/rasmus output/rasmus/carousel.pptx ``` **Option B: Using soffice** ```bash soffice --headless --convert-to pdf output/rasmus/carousel.pptx ``` **Note:** LibreOffice must be installed. On macOS: `brew install --cask libreoffice` ### Step 6: Output Save both files: - `output/{brand}/{name}-carousel.pptx` - Editable source - `output/{brand}/{name}-carousel.pdf` - LinkedIn-ready ### Carousel Checklist - [ ] Read brand configuration - [ ] Read carousel layout frontmatters from `cookbook/carousels/` - [ ] Plan carousel structure (hook → body → CTA) - [ ] Keep text SHORT (check character limits in frontmatter) - [ ] Use 7.5" × 7.5" dimensions - [ ] Generate PPTX - [ ] Validate output - [ ] Export to PDF - [ ] Test PDF in LinkedIn preview --- ## Mode 3: Layout CRUD Operations ### Creating New Layouts When user requests a new layout type: 1. **Study existing layouts for patterns:** ``` Glob: .claude/skills/pptx-generator/cookbook/*.py ``` Read 2-3 layouts to understand: - Code structure and imports - How brand variables are used - Decorative element patterns - Positioning conventions 2. **Design with these quality standards:** **MUST be production-ready:** - Professional, polished appearance - Visually engaging (not plain or generic) - Distinctive decorative elements - Strong visual hierarchy - Proper use of whitespace **Use appropriate elements:** - **Charts** - Pie, doughnut, bar, column for data visualization - **Images** - Placeholder shapes for screenshots, photos - **Shapes** - Circles, rectangles, parallelograms for visual interest - **Cards** - Floating cards with shadows for depth - **Geometric patterns** - Bold shapes anchored to corners/edges **Avoid:** - Plain text-only layouts - Generic bullet points without styling - Tiny decorative elements that don't make impact - Centered-everything boring compositions 3. **Write the layout file with detailed frontmatter:** **⚠️ CRITICAL: The frontmatter is documentation for future AI agents.** Every layout MUST include comprehensive frontmatter that teaches future AI agents: - WHEN to use this layout (and when NOT to) - HOW to use it correctly - WHAT limits and constraints exist - WHY certain choices matter ```python #!/usr/bin/env -S uv run # /// script # requires-python = ">=3.11" # dependencies = [ # "python-pptx==1.0.2", # ] # /// # /// layout # name = "layout-name" # purpose = "When to use this layout - be specific" # best_for = [ # "Ideal use case 1", # "Ideal use case 2", # ] # avoid_when = [ # "Situation to avoid 1 - and what to use instead", # "Situation to avoid 2 - and what to use instead", # ] # max_items = 5 # or other relevant limits # instructions = [ # "Specific tip 1", # "Specific tip 2", # ] # /// """ LAYOUT: [Name] PURPOSE: [When to use this layout - be specific] CUSTOMIZE: - [List customizable elements] """ # ... implementation ``` **Required frontmatter fields (be DETAILED and SPECIFIC):** | Field | Description | Example | |-------|-------------|---------| | `name` | Layout identifier (matches filename) | `"multi-card-slide"` | | `purpose` | Clear one-line description | `"Multiple items as cards in a row, 3-5 cards"` | | `best_for` | **Detailed** array of ideal scenarios | `["Exactly 3 related features", "Process with 3 steps"]` | | `avoid_when` | **Specific** situations with alternatives | `["More than 3 items - use multi-card-slide instead"]` | | `instructions` | **Actionable** tips for correct usage | `["Card titles must be SHORT: 1-2 words, max 15 chars"]` | **Optional but recommended fields:** | Field | Description | Example | |-------|-------------|---------| | `max_*` / `min_*` | Hard limits on items | `max_cards = 3`, `min_surrounding_items = 4` | | `*_max_chars` | Character limits for text | `card_title_max_chars = 15` | **Writing good frontmatter:** ✅ **DO:** Be specific and actionable ```python # avoid_when = [ # "More than 3 items - use multi-card-slide instead", # "Long card titles (over 15 characters) - abbreviate or use content-slide", # ] # instructions = [ # "EXACTLY 3 cards required - no more, no less", # "Card titles must be SHORT: 1-2 words, max 15 characters", # "If titles are too long, abbreviate or use different layout", # ] ``` ❌ **DON'T:** Be vague or unhelpful ```python # avoid_when = ["Too many items", "Wrong content"] # instructions = ["Use correctly", "Follow the pattern"] ``` **Think of frontmatter as teaching a colleague** - what would they need to know to use this layout correctly without asking you questions? 4. **Save to cookbook:** ``` .claude/skills/pptx-generator/cookbook/{layout-name}-slide.py ``` 5. **Test by generating** a sample with the new layout ### Editing Existing Layouts 1. **Find the layout:** ``` Glob: .claude/skills/pptx-generator/cookbook/*{name}*.py ``` 2. **Read and understand current structure** including the frontmatter 3. **Make modifications** while preserving: - The script header format - Brand variable naming conventions - Docstring format (LAYOUT, PURPOSE, CUSTOMIZE) 4. **Update the frontmatter** if your changes affect: - What the layout is best for (`best_for`) - When to avoid it (`avoid_when`) - Item limits (`max_*`, `min_*`) - Usage instructions (`instructions`) 5. **Save back to the same file** 6. **Test the modified layout** ### Updating/Improving Layouts When asked to improve layout quality: 1. **Analyze current weaknesses:** - Is it visually engaging? - Does it have enough decorative elements? - Is there good visual hierarchy? - Does it use space well? 2. **Apply improvements:** - Add bold geometric shapes - Improve color usage - Add depth (shadows, overlapping) - Better typography sizing - More distinctive decorative elements 3. **Preserve functionality** - Don't break what works 4. **Review and enhance frontmatter:** - Are `best_for` and `avoid_when` still accurate? - Do `instructions` reflect any new constraints? - Add any lessons learned from the improvements - Update limits if element sizes/counts changed ### Deleting Layouts Simply remove the file: ```bash rm .claude/skills/pptx-generator/cookbook/{layout-name}.py ``` --- ## Editing Existing PPTX Files When user provides an existing PPTX: 1. **Read the file:** ```python from pptx import Presentation prs = Presentation("path/to/existing.pptx") ``` 2. **Analyze:** Number of slides, styling, content structure 3. **Apply changes:** Add/remove slides, update content, modify styling 4. **Save to output directory** (don't overwrite original unless requested) --- ## Technical Reference **Slide dimensions (16:9):** - Width: 13.333 inches - Height: 7.5 inches - Safe margins: 0.5 inches **Always use:** - Blank layout: `prs.slide_layouts[6]` - python-pptx version: 1.0.2 **Common imports:** ```python from pptx import Presentation from pptx.chart.data import CategoryChartData from pptx.dml.color import RGBColor from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION from pptx.enum.shapes import MSO_SHAPE from pptx.enum.text import PP_ALIGN, MSO_ANCHOR from pptx.util import Inches, Pt ``` **Chart types available:** - `XL_CHART_TYPE.PIE` - Pie chart - `XL_CHART_TYPE.DOUGHNUT` - Doughnut chart - `XL_CHART_TYPE.BAR_CLUSTERED` - Horizontal bars - `XL_CHART_TYPE.COLUMN_CLUSTERED` - Vertical columns - `XL_CHART_TYPE.LINE` - Line chart **Adding charts:** ```python chart_data = CategoryChartData() chart_data.categories = ["A", "B", "C"] chart_data.add_series("Values", [10, 20, 30]) slide.shapes.add_chart( XL_CHART_TYPE.DOUGHNUT, Inches(x), Inches(y), Inches(width), Inches(height), chart_data ) ``` **Adding images:** ```python slide.shapes.add_picture( "path/to/image.png", Inches(x), Inches(y), width=Inches(w) # Height auto-calculated ) ``` --- ## Preview All Layouts To see all available layouts: ```bash uv run .claude/skills/pptx-generator/generate-cookbook-preview.py ``` This generates `cookbook-preview.pptx` with every layout. --- ## Checklist **For Slide Generation:** - [ ] Read brand.json for colors/fonts - [ ] Read config.json for output directory and settings - [ ] Read markdown files for voice/tone - [ ] **Read ALL cookbook layout frontmatters** (first 40 lines of each .py): - [ ] Glob all `.claude/skills/pptx-generator/cookbook/*.py` - [ ] Read every file to extract `# /// layout` blocks - [ ] Build understanding of all `best_for`, `avoid_when`, limits - [ ] **Then select layouts** based on complete knowledge: - [ ] Match content to `best_for` criteria - [ ] Respect `avoid_when` warnings - [ ] Check `max_*` / `min_*` limits - [ ] Follow `instructions` for chosen layouts - [ ] **Create slide plan table BEFORE generating:** - [ ] List all slides with layout, title, content - [ ] Check for duplicate titles - [ ] Verify logical flow - [ ] Group into batches (max 5 per batch) - [ ] **VARIETY CHECK: Content-slide <25% of total** - [ ] **VARIETY CHECK: No 3+ consecutive same-layout slides** - [ ] **VARIETY CHECK: Visual layouts 50%+ of presentation** - [ ] **VARIETY CHECK: Used decision tree to evaluate each content-slide** - [ ] Present plan briefly before proceeding - [ ] Apply brand colors and fonts - [ ] Write content in brand's voice - [ ] **Generate MAX 5 slides per batch** (or `slides_per_batch` from config) - [ ] Execute via UV REPL - [ ] **Validate output before continuing:** - [ ] No duplicate titles - [ ] Proper spacing between elements - [ ] Content fits within bounds - [ ] Colors match brand - [ ] No trailing punctuation on titles/bullets - [ ] Save batch to output directory from config - [ ] Repeat for next batch if needed - [ ] **Combine all batches into final PPTX** (if `auto_combine` is true) - [ ] Clean up part files (if `keep_parts` is false) **For Creating Layouts:** - [ ] Study existing layouts for patterns - [ ] Design with production-ready quality - [ ] Include distinctive decorative elements - [ ] Use charts/images/shapes appropriately - [ ] **Add TOML-style frontmatter** with: - [ ] `name`, `purpose` - [ ] `best_for`, `avoid_when` arrays - [ ] `instructions` array with usage tips - [ ] `max_*` / `min_*` limits as needed - [ ] Write proper docstring (LAYOUT, PURPOSE, CUSTOMIZE) - [ ] Test the new layout