Editing Presentations

Path convention: All commands run from the session workspace. Never cd into the skill directory. Prefix all skill scripts with .opencode/skills/pptx/. All generated files go in outputs/.

Template-Based Workflow

When using an existing presentation as a template:

Preserve the template's design. Your job is to fill the template with the user's content, not to restyle it. Keep its fonts, colors, and layout language exactly. In particular, do not substitute fonts — a template often embeds fonts that aren't installed system-wide (check ppt/fonts/); they render correctly as-is, and replacing them with an "installed" font breaks the look. New text you add should reuse the fonts already on that slide.

1. Analyze existing slides:

   bashCopy

   python .opencode/skills/pptx/scripts/thumbnail.py template.pptx outputs/thumbnails
   python -m markitdown template.pptx
   

   Review outputs/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 .opencode/skills/pptx/scripts/office/unpack.py template.pptx outputs/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. First pack (do this EARLY): as soon as the structure is set and first-pass content is in, clean + pack so a viewable deck exists:

   bashCopy

   python .opencode/skills/pptx/scripts/clean.py outputs/unpacked/
   python .opencode/skills/pptx/scripts/office/pack.py outputs/unpacked/ outputs/output.pptx --original template.pptx
   

   A turn that ends with edits stranded in outputs/unpacked/ delivers nothing — the packed .pptx is the deliverable (SKILL.md → Build Order). Never do fine-grained restyling before the first pack exists.

6. Refine content: update text in each slide{N}.xml. Use subagents here if available — slides are separate XML files, so subagents can edit in parallel.

7. Re-clean + re-pack after each batch of edits (same commands as step 5) — the packed deck in outputs/ should always reflect your latest good state.

Scripts

unpack.py

python .opencode/skills/pptx/scripts/office/unpack.py input.pptx outputs/unpacked/

Extracts PPTX, pretty-prints XML, escapes smart quotes.

add_slide.py

python .opencode/skills/pptx/scripts/add_slide.py outputs/unpacked/ slide2.xml      # Duplicate slide
python .opencode/skills/pptx/scripts/add_slide.py outputs/unpacked/ slideLayout2.xml # From layout

Prints <p:sldId> to add to <p:sldIdLst> at desired position.

clean.py

python .opencode/skills/pptx/scripts/clean.py outputs/unpacked/

Removes slides not in <p:sldIdLst>, unreferenced media, orphaned rels.

pack.py

python .opencode/skills/pptx/scripts/office/pack.py outputs/unpacked/ outputs/output.pptx --original input.pptx

Validates, repairs, condenses XML, re-encodes smart quotes.

thumbnail.py

python .opencode/skills/pptx/scripts/thumbnail.py input.pptx outputs/thumbnails [--cols N]

Creates outputs/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 outputs/unpacked/ppt/presentation.xml → <p:sldIdLst>.

Reorder: Rearrange <p:sldId> elements.

Delete: Remove <p:sldId>, then run clean.py.

See available layouts: ls outputs/unpacked/ppt/slideLayouts/

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 — for chart placeholders produce deck-styled PNGs per charts.md; for icon placeholders render PNGs with .opencode/skills/pptx/scripts/icon.js (see pptxgenjs.md); insert either as slide media at the placeholder's size

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:

<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:

<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:

<a:t>the &#x201C;Agreement&#x201D;</a:t>

Other

• Whitespace: Use xml:space="preserve" on <a:t> with leading/trailing spaces
• XML parsing: Use defusedxml.minidom, not xml.etree.ElementTree (corrupts namespaces)