pptx-generator

# 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 | This prevents token limit errors and catches quality issues early. --- ## ⚠️ 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 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) **After planning, briefly present the plan before generating.** ### 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 |