pptx-generator

What this skill does

# 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
- **Workflows** - Pre-defined presentation patterns for common use cases (QA reports, RCA reports)

**IMPORTANT:** Plugin resources (cookbook, workflows, template brand) are at `${CLAUDE_PLUGIN_ROOT}/skills/pptx-generator/`. User brands are at `.claude/brands/`. Always use the correct base path.

---

## ⚠️ 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/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_PLUGIN_ROOT}/skills/pptx-generator/brands/template/README.md
Read: ${CLAUDE_PLUGIN_ROOT}/skills/pptx-generator/brands/template/brand.json
Read: ${CLAUDE_PLUGIN_ROOT}/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/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 `.claude/brands/{brand-name}/assets/`

### Step 4: Verify

After creating the brand, verify with:
```
Glob: .claude/brands/{brand-name}/*
```

Then proceed to slide generation.

---

## Skill Modes

This skill operates in four 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 4: Use Workflow Templates
User wants to generate slides from a specific report type (QA report, RCA report, etc.).
→ Follow: Workflow Discovery → Read Workflow → Extract Data → Generate Slides
→ Workflows in: `workflows/*.md`

---

## Mode 4: Use Workflow Templates

Workflows are pre-defined presentation patterns for common use cases. They specify:
- Which layouts to use
- How to extract data from reports
- Recommended slide structure
- Color and formatting guidance

### Step 1: Workflow Discovery

When user mentions a workflow or provides a report that matches a workflow type:

```
Glob: ${CLAUDE_PLUGIN_ROOT}/skills/pptx-generator/workflows/*.md
```

**Available Workflows:**

| Workflow | Triggers | Use Case |
|----------|----------|----------|
| `qa-report` | "QA report", "smoke test", "gate validation", "environment health" | QA test analysis reports |
| `rca-report` | "RCA", "root cause", "incident", "postmortem", "pipeline failure" | Root cause analysis reports |

### Step 2: Read Workflow Definition

```
Read: ${CLAUDE_PLUGIN_ROOT}/skills/pptx-generator/workflows/{workflow-name}.md
```

The workflow file contains:
- **Slide Structure** - Recommended slides for different scenarios
- **Data Extraction Guide** - How to map report sections to slide content
- **Layout Selection Logic** - Decision tree for choosing layouts
- **Color Mapping** - Report terms to brand colors
- **Example Prompts** - How users might invoke the workflow

### Step 3: Extract Data from Report

Follow the workflow's "Data Extraction Guide" to identify:
1. **Report type** - Healthy environment? Critical failure? Multi-environment?
2. **Key sections** - Executive summary, test results, root cause, actions
3. **Data for each slide** - Map report tables/sections to slide content

### Step 4: Select Slide Structure

Use the workflow's "Slide Structure" section to choose the appropriate template:
- **QA Report:** Different structures for healthy vs critical environments
- **RCA Report:** Different structures for simple fix vs complex investigation

### Step 5: Generate Slides

Follow Mode 1 (Generate Presentation Slides) using:
- Layouts specified by the workflow
- Data extracted from the report
- Colors mapped per workflow guidance

### Workflow Example: QA Report

**User Input:**
```
Create slides for azure-engineering brand from this QA report:

[paste report with environment status, test results, actions]

Use the qa-report workflow.
```

**Process:**
1. Read `workflows/qa-report.md`
2. Identify report type (e.g., HEALTHY single environment)
3. Select slide structure for healthy environment
4. Extract: environment data, test categories, service versions, act