@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/pptx/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: pptx
+description: "Use this skill any time a .pptx file is involved — as input, output, or both. This includes creating slide decks, pitch decks, or presentations; reading or extracting text from .pptx files; editing or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments."
+license: MIT (Anthropic)
+compatibility: claude-code
+metadata:
+  source: anthropic/skills
+  imported: 2026-03-15
+  version: "3.0.0"
+  windows-setup: See references/windows-setup.md for Windows dependency installation
+  auto_activate: [powerpoint, pptx-file, pptx-export, slide-deck]
+  file_triggers: [*.pptx]
+---
+
+# PowerPoint Presentation Guide
+
+## Quick Reference
+
+| Task                         | Approach                                                         |
+| ---------------------------- | ---------------------------------------------------------------- |
+| Read/analyze content         | `python -m markitdown presentation.pptx`                         |
+| Edit or create from template | Unpack → manipulate slides → repack. See `references/editing.md` |
+| Create from scratch          | Use PptxGenJS. See `references/pptxgenjs.md`                     |
+| Visual QA                    | Convert to images, inspect with subagent                         |
+
+## Reading Content
+
+```bash
+python -m markitdown presentation.pptx
+```
+
+## Editing Existing Presentations
+
+See `references/editing.md` for the complete template-based workflow:
+
+1. **Analyze**: `python scripts/thumbnail.py template.pptx` + markitdown
+2. **Plan slide mapping**: Match content to varied layouts
+3. **Unpack**: `python scripts/office/unpack.py template.pptx unpacked/`
+4. **Build structure**: Add/delete/reorder slides (use `scripts/add_slide.py`)
+5. **Edit content**: Update text in each `slide{N}.xml` (use subagents for parallel editing)
+6. **Clean**: `python scripts/clean.py unpacked/`
+7. **Pack**: `python scripts/office/pack.py unpacked/ output.pptx --original template.pptx`
+
+**Note:** The shared office toolkit (`unpack.py`, `pack.py`, `validate.py`, `soffice.py`) lives in `../docx/scripts/office/`.
+
+## Creating from Scratch with PptxGenJS
+
+Install: `npm install -g pptxgenjs`
+
+See `references/pptxgenjs.md` for the complete API reference covering text, shapes, images, icons (react-icons → SVG → PNG), backgrounds, tables, charts, slide masters, and common pitfalls.
+
+## Design Principles
+
+**Don't create boring slides.** Every slide needs visual elements — images, charts, icons, or shapes.
+
+### Color Palettes
+
+Pick colors that match your topic — don't default to generic blue.
+
+| Theme              | Primary  | Secondary | Accent   |
+| ------------------ | -------- | --------- | -------- |
+| Midnight Executive | `1E2761` | `CADCFC`  | `FFFFFF` |
+| Forest & Moss      | `2C5F2D` | `97BC62`  | `F5F5F5` |
+| Coral Energy       | `F96167` | `F9E795`  | `2F3C7E` |
+| Warm Terracotta    | `B85042` | `E7E8D1`  | `A7BEAE` |
+| Ocean Gradient     | `065A82` | `1C7293`  | `21295C` |
+| Charcoal Minimal   | `36454F` | `F2F2F2`  | `212121` |
+
+### Typography
+
+Choose interesting font pairings — don't default to Arial.
+
+| Element        | Size          |
+| -------------- | ------------- |
+| Slide title    | 36-44pt bold  |
+| Section header | 20-24pt bold  |
+| Body text      | 14-16pt       |
+| Captions       | 10-12pt muted |
+
+### Layout Options
+
+- Two-column (text left, illustration right)
+- Icon + text rows
+- 2x2 or 2x3 grid
+- Half-bleed image with content overlay
+- Large stat callouts (60-72pt numbers)
+
+### Avoid
+
+- Don't repeat the same layout across slides
+- Don't center body text — left-align
+- Don't default to blue
+- Don't create text-only slides — add visuals
+- NEVER use accent lines under titles (hallmark of AI-generated slides)
+
+## QA (Required)
+
+**Assume there are problems. Your job is to find them.**
+
+1. Content QA: `python -m markitdown output.pptx`
+2. Visual QA: Convert to images, inspect with subagent
+3. Fix issues and re-verify
+
+```bash
+# Convert to images for inspection
+python scripts/office/soffice.py --headless --convert-to pdf output.pptx
+pdftoppm -jpeg -r 150 output.pdf slide
+```
+
+## Bundled Scripts
+
+| Script                       | Purpose                                            |
+| ---------------------------- | -------------------------------------------------- |
+| `scripts/add_slide.py`       | Duplicate slide or create from layout              |
+| `scripts/clean.py`           | Remove orphaned slides, media, rels                |
+| `scripts/thumbnail.py`       | Create visual grid of slides for template analysis |
+| `scripts/office/unpack.py`   | Extract and pretty-print PPTX XML (shared)         |
+| `scripts/office/pack.py`     | Validate, repair, and repack into .pptx (shared)   |
+| `scripts/office/validate.py` | Validate against ISO/ECMA schemas (shared)         |
+| `scripts/office/soffice.py`  | LibreOffice automation (shared)                    |
+
+## Bundled References
+
+- `references/editing.md` — Template-based editing workflow, slide operations, formatting rules, common pitfalls
+- `references/pptxgenjs.md` — Complete PptxGenJS API: text, shapes, images, icons, charts, tables, slide masters
+
+## Dependencies
+
+- `pip install "markitdown[pptx]"` — text extraction
+- `pip install Pillow` — thumbnail grids
+- `npm install -g pptxgenjs` — creating from scratch
+- LibreOffice — PDF conversion
+- Poppler (`pdftoppm`) — PDF to images

package/.merlin-core/skills/general/pptx/references/editing.md

@@ -0,0 +1,213 @@
+# Editing Presentations
+
+## Template-Based Workflow
+
+When using an existing presentation as a template:
+
+1. **Analyze existing slides**:
+
+   ```bash
+   python scripts/thumbnail.py template.pptx
+   python -m markitdown template.pptx
+   ```
+
+   Review `thumbnails.jpg` to see layouts, and markitdown output to see placeholder text.
+
+2. **Plan slide mapping**: For each content section, choose a template slide.
+
+   ⚠️ **USE VARIED LAYOUTS** — monotonous presentations are a common failure mode. Don't default to basic title + bullet slides. Actively seek out:
+   - Multi-column layouts (2-column, 3-column)
+   - Image + text combinations
+   - Full-bleed images with text overlay
+   - Quote or callout slides
+   - Section dividers
+   - Stat/number callouts
+   - Icon grids or icon + text rows
+
+   **Avoid:** Repeating the same text-heavy layout for every slide.
+
+   Match content type to layout style (e.g., key points → bullet slide, team info → multi-column, testimonials → quote slide).
+
+3. **Unpack**: `python scripts/office/unpack.py template.pptx unpacked/`
+
+4. **Build presentation** (do this yourself, not with subagents):
+   - Delete unwanted slides (remove from `<p:sldIdLst>`)
+   - Duplicate slides you want to reuse (`add_slide.py`)
+   - Reorder slides in `<p:sldIdLst>`
+   - **Complete all structural changes before step 5**
+
+5. **Edit content**: Update text in each `slide{N}.xml`.
+   **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.
+
+6. **Clean**: `python scripts/clean.py unpacked/`
+
+7. **Pack**: `python scripts/office/pack.py unpacked/ output.pptx --original template.pptx`
+
+---
+
+## Scripts
+
+| Script         | Purpose                               |
+| -------------- | ------------------------------------- |
+| `unpack.py`    | Extract and pretty-print PPTX         |
+| `add_slide.py` | Duplicate slide or create from layout |
+| `clean.py`     | Remove orphaned files                 |
+| `pack.py`      | Repack with validation                |
+| `thumbnail.py` | Create visual grid of slides          |
+
+### unpack.py
+
+```bash
+python scripts/office/unpack.py input.pptx unpacked/
+```
+
+Extracts PPTX, pretty-prints XML, escapes smart quotes.
+
+### add_slide.py
+
+```bash
+python scripts/add_slide.py unpacked/ slide2.xml      # Duplicate slide
+python scripts/add_slide.py unpacked/ slideLayout2.xml # From layout
+```
+
+Prints `<p:sldId>` to add to `<p:sldIdLst>` at desired position.
+
+### clean.py
+
+```bash
+python scripts/clean.py unpacked/
+```
+
+Removes slides not in `<p:sldIdLst>`, unreferenced media, orphaned rels.
+
+### pack.py
+
+```bash
+python scripts/office/pack.py unpacked/ output.pptx --original input.pptx
+```
+
+Validates, repairs, condenses XML, re-encodes smart quotes.
+
+### thumbnail.py
+
+```bash
+python scripts/thumbnail.py input.pptx [output_prefix] [--cols N]
+```
+
+Creates `thumbnails.jpg` with slide filenames as labels. Default 3 columns, max 12 per grid.
+
+**Use for template analysis only** (choosing layouts). For visual QA, use `soffice` + `pdftoppm` to create full-resolution individual slide images—see SKILL.md.
+
+---
+
+## Slide Operations
+
+Slide order is in `ppt/presentation.xml` → `<p:sldIdLst>`.
+
+**Reorder**: Rearrange `<p:sldId>` elements.
+
+**Delete**: Remove `<p:sldId>`, then run `clean.py`.
+
+**Add**: Use `add_slide.py`. Never manually copy slide files—the script handles notes references, Content_Types.xml, and relationship IDs that manual copying misses.
+
+---
+
+## Editing Content
+
+**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include:
+
+- The slide file path(s) to edit
+- **"Use the Edit tool for all changes"**
+- The formatting rules and common pitfalls below
+
+For each slide:
+
+1. Read the slide's XML
+2. Identify ALL placeholder content—text, images, charts, icons, captions
+3. Replace each placeholder with final content
+
+**Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability.
+
+### Formatting Rules
+
+- **Bold all headers, subheadings, and inline labels**: Use `b="1"` on `<a:rPr>`. This includes:
+  - Slide titles
+  - Section headers within a slide
+  - Inline labels like (e.g.: "Status:", "Description:") at the start of a line
+- **Never use unicode bullets (•)**: Use proper list formatting with `<a:buChar>` or `<a:buAutoNum>`
+- **Bullet consistency**: Let bullets inherit from the layout. Only specify `<a:buChar>` or `<a:buNone>`.
+
+---
+
+## Common Pitfalls
+
+### Template Adaptation
+
+When source content has fewer items than the template:
+
+- **Remove excess elements entirely** (images, shapes, text boxes), don't just clear text
+- Check for orphaned visuals after clearing text content
+- Run visual QA to catch mismatched counts
+
+When replacing text with different length content:
+
+- **Shorter replacements**: Usually safe
+- **Longer replacements**: May overflow or wrap unexpectedly
+- Test with visual QA after text changes
+- Consider truncating or splitting content to fit the template's design constraints
+
+**Template slots ≠ Source items**: If template has 4 team members but source has 3 users, delete the 4th member's entire group (image + text boxes), not just the text.
+
+### Multi-Item Content
+
+If source has multiple items (numbered lists, multiple sections), create separate `<a:p>` elements for each — **never concatenate into one string**.
+
+**❌ WRONG** — all items in one paragraph:
+
+```xml
+<a:p>
+  <a:r><a:rPr .../><a:t>Step 1: Do the first thing. Step 2: Do the second thing.</a:t></a:r>
+</a:p>
+```
+
+**✅ CORRECT** — separate paragraphs with bold headers:
+
+```xml
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 1</a:t></a:r>
+</a:p>
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" .../><a:t>Do the first thing.</a:t></a:r>
+</a:p>
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 2</a:t></a:r>
+</a:p>
+<!-- continue pattern -->
+```
+
+Copy `<a:pPr>` from the original paragraph to preserve line spacing. Use `b="1"` on headers.
+
+### Smart Quotes
+
+Handled automatically by unpack/pack. But the Edit tool converts smart quotes to ASCII.
+
+**When adding new text with quotes, use XML entities:**
+
+```xml
+<a:t>the &#x201C;Agreement&#x201D;</a:t>
+```
+
+| Character | Name               | Unicode | XML Entity |
+| --------- | ------------------ | ------- | ---------- |
+| `“`       | Left double quote  | U+201C  | `&#x201C;` |
+| `”`       | Right double quote | U+201D  | `&#x201D;` |
+| `‘`       | Left single quote  | U+2018  | `&#x2018;` |
+| `’`       | Right single quote | U+2019  | `&#x2019;` |
+
+### Other
+
+- **Whitespace**: Use `xml:space="preserve"` on `<a:t>` with leading/trailing spaces
+- **XML parsing**: Use `defusedxml.minidom`, not `xml.etree.ElementTree` (corrupts namespaces)