Skip to content

donaldfilimon/abi / .agents/skills/pptx

Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill.

FileKindSize
SKILL.mdskill md9.1 KB
references/creating.mdmarkdown18.8 KB
references/editing.mdmarkdown28.2 KB
references/template_taxonomy.jsonconfig112.3 KB
references/templates/activewear_collection_overview.jsscript31.4 KB
references/templates/africa_fmcg_value_chain_playbook.jsscript40.1 KB
references/templates/ag_trade_finance_pitch_deck.jsscript32.3 KB
references/templates/agri_commodities_trading_primer.jsscript31.9 KB
references/templates/agtech_seed_round_pitch_deck.jsscript36.9 KB
references/templates/ai_blockchain_market_briefing.jsscript47.6 KB
references/templates/ai_llm_technical_history.jsscript34.4 KB
references/templates/ai_robotics_startup_pitch_deck.jsscript70.8 KB
references/templates/ai_sports_media_partnership_pitch.jsscript38.4 KB
references/templates/ai_startup_series_a_pitch_deck.jsscript18.3 KB
references/templates/american_regional_pizza_guide.jsscript23.4 KB
references/templates/animation_studio_company_history.jsscript20.5 KB
references/templates/apothecary_brand_introduction.jsscript18.7 KB
references/templates/art_gallery_exhibition_presentation.jsscript92.5 KB
references/templates/auto_repair_company_profile.jsscript68.7 KB
references/templates/automotive_board_strategy_review.jsscript52.0 KB
references/templates/bagel_shop_menu_pitch_deck.jsscript32.3 KB
references/templates/bakery_business_pitch_deck.jsscript31.8 KB
references/templates/bakery_commercial_loan_pitch.jsscript32.9 KB
references/templates/bakery_concept_vision_board.jsscript31.6 KB
references/templates/biology_dissertation_proposal.jsscript37.4 KB
references/templates/biotech_cloud_rd_infrastructure_proposal.jsscript49.7 KB
references/templates/biotech_series_b_pitch_deck.jsscript53.4 KB
references/templates/biotech_startup_pitch_deck.jsscript23.7 KB
references/templates/cafe_concept_vision_pitch_deck.jsscript22.0 KB
references/templates/cfo_financial_performance_review.jsscript41.4 KB
references/templates/childcare_operator_partnership_pitch.jsscript32.2 KB
references/templates/coffee_franchise_prospectus.jsscript51.8 KB
references/templates/college_admissions_consulting_pitch.jsscript31.2 KB
references/templates/college_sports_policy_briefing.jsscript17.9 KB
references/templates/comedy_writing_guide.jsscript22.3 KB
references/templates/consumer_goods_annual_budget.jsscript15.9 KB
references/templates/cruise_itinerary_trade_portfolio.jsscript42.8 KB
references/templates/crypto_hedge_fund_pitch_deck.jsscript34.5 KB
references/templates/crypto_portfolio_management.jsscript25.6 KB
references/templates/crypto_quantum_risk_briefing.jsscript47.2 KB
references/templates/crypto_series_a_pitch_deck.jsscript51.2 KB
references/templates/destination_marketing_event_pitch.jsscript27.9 KB
references/templates/economic_consulting_prospectus.jsscript25.3 KB
references/templates/edinburgh_fringe_performer_guide.jsscript27.3 KB
references/templates/edtech_ai_product_pitch_deck.jsscript95.7 KB
references/templates/education_calculus_lecture.jsscript29.6 KB
references/templates/education_intro_chemistry_lecture.jsscript23.0 KB
references/templates/education_intro_to_piano_lecture.jsscript26.6 KB
references/templates/education_literature_canterbury_tales.jsscript18.9 KB
references/templates/education_music_theory_lesson.jsscript22.6 KB
references/templates/education_university_profile.jsscript48.6 KB
references/templates/education_visual_essay_presentation.jsscript25.4 KB
references/templates/education_water_polo_basics.jsscript22.8 KB
references/templates/electronic_music_promoter_field_report.jsscript38.9 KB
references/templates/energy_storage_vendor_assessment.jsscript36.4 KB
references/templates/entertainment_creative_pitch_deck.jsscript27.1 KB
references/templates/entertainment_film_pitch_deck.jsscript110.2 KB
references/templates/family_office_portfolio_review.jsscript52.9 KB
references/templates/fashion_apparel_lookbook.jsscript41.0 KB
references/templates/feature_film_pitch_deck.jsscript32.1 KB
references/templates/finance_10k_filing_analysis_guide.jsscript35.2 KB
references/templates/finance_ai_fixed_income_briefing.jsscript34.5 KB
references/templates/finance_ai_portfolio_analysis.jsscript21.5 KB
references/templates/finance_cockroach_portfolio_strategy.jsscript32.8 KB
references/templates/finance_crypto_fund_pitch_deck.jsscript27.1 KB
references/templates/finance_day_trading_primer.jsscript35.2 KB
references/templates/finance_digital_asset_custody_briefing.jsscript44.1 KB
references/templates/finance_employee_excellence_awards.jsscript24.4 KB
references/templates/finance_equity_investment_analysis.jsscript117.2 KB
references/templates/finance_equity_portfolio_performance_report.jsscript48.5 KB
references/templates/finance_equity_research_index_analysis.jsscript39.2 KB
references/templates/finance_equity_research_investment_thesis.jsscript42.2 KB
references/templates/finance_equity_research_stock_pitch.jsscript35.8 KB
references/templates/finance_hedge_fund_pitch_deck.jsscript29.6 KB
references/templates/finance_hedge_fund_primer.jsscript78.5 KB
references/templates/finance_ifrs_us_gaap_training.jsscript7.6 KB
references/templates/finance_investment_committee_memo.jsscript41.2 KB
references/templates/finance_investment_portfolio_brief.jsscript32.0 KB
references/templates/finance_lihtc_bond_portfolio_review.jsscript43.6 KB
references/templates/finance_nft_marketplace_pitch_deck.jsscript44.5 KB
references/templates/finance_portfolio_quarterly_review.jsscript40.7 KB
references/templates/finance_prediction_markets_investment_memo.jsscript28.9 KB
references/templates/finance_private_credit_primer.jsscript34.7 KB
references/templates/finance_quant_trading_desk_proposal.jsscript50.5 KB
references/templates/finance_rwa_tokenization_pitch.jsscript39.6 KB
references/templates/finance_spv_pre_ipo_pitch.jsscript50.0 KB
references/templates/finance_vc_investment_memo.jsscript32.8 KB
references/templates/finance_vc_investment_memo_2.jsscript43.9 KB
references/templates/finance_venture_capital_primer.jsscript31.5 KB
references/templates/fintech_ai_series_a_pitch_deck.jsscript44.5 KB
references/templates/fitness_franchise_qbr_performance.jsscript40.6 KB
references/templates/fitness_gym_summer_press_kit.jsscript32.0 KB
references/templates/fitness_personal_training_keynote.jsscript22.9 KB
references/templates/fixed_income_macro_outlook.jsscript145.9 KB
references/templates/flower_shop_company_profile.jsscript44.1 KB
references/templates/food_beverage_bakery_brand_profile.jsscript19.1 KB
references/templates/food_beverage_seed_pitch_deck.jsscript30.9 KB
references/templates/food_delivery_subscription_pitch.jsscript59.1 KB
references/templates/future_mobility_trends_keynote.jsscript44.2 KB
references/templates/game_design_character_brief.jsscript44.2 KB
references/templates/gaming_ai_startup_pitch_deck.jsscript41.9 KB
references/templates/gaming_product_portfolio_review.jsscript33.5 KB
references/templates/garyvee_content_strategy_framework.jsscript25.7 KB
references/templates/gelateria_seed_pitch_deck.jsscript26.6 KB
references/templates/geospatial_data_analysis_training.jsscript33.3 KB
references/templates/grocery_flash_sale_promotion.jsscript32.9 KB
references/templates/healthcare_ai_partnership_proposal.jsscript31.8 KB
references/templates/healthcare_ma_pitch_deck.jsscript52.0 KB
references/templates/healthcare_nursing_performance_review.jsscript33.7 KB
references/templates/healthcare_patient_accessibility_survey.jsscript37.4 KB
references/templates/healthcare_patient_forms_standardization.jsscript56.8 KB
references/templates/healthcare_promis57_patient_guide.jsscript43.3 KB
references/templates/healthcare_std_prophylaxis_grand_rounds.jsscript51.9 KB
references/templates/healthcare_tb_testing_clinical_training.jsscript23.9 KB
references/templates/hedge_fund_portfolio_strategy.jsscript26.7 KB
references/templates/hospitality_bed_and_breakfast_promo.jsscript41.9 KB
references/templates/indoor_golf_club_launch_deck.jsscript25.9 KB
references/templates/institutional_crypto_exchange_pitch_deck.jsscript63.0 KB
references/templates/interior_design_studio_portfolio.jsscript36.4 KB
references/templates/intro_to_guitar_lecture.jsscript33.0 KB
references/templates/italy_travel_destination_guide.jsscript49.5 KB
references/templates/japan_travel_destination_guide.jsscript35.3 KB
references/templates/jazz_bar_concept_pitch.jsscript34.5 KB
references/templates/k12_literacy_tutoring_pitch.jsscript26.0 KB
references/templates/kids_taekwondo_marketing.jsscript24.8 KB
references/templates/labor_economics_research_presentation.jsscript27.7 KB
references/templates/local_ai_consulting_pitch_deck.jsscript35.0 KB
references/templates/local_business_pitch_deck.jsscript28.1 KB
references/templates/local_city_history_overview.jsscript31.0 KB
references/templates/local_ice_cream_shop_pitch_deck.jsscript26.9 KB
references/templates/luxury_design_brand_story.jsscript17.9 KB
references/templates/luxury_eyewear_retail_seed_pitch.jsscript31.9 KB
references/templates/luxury_hospitality_brand_guidelines.jsscript25.2 KB
references/templates/luxury_interior_design_partnership_deck.jsscript22.5 KB
references/templates/luxury_nanny_placement_brochure.jsscript37.5 KB
references/templates/macro_research_yield_curve_report.jsscript42.5 KB
references/templates/mba_financial_crisis_lecture.jsscript55.7 KB
references/templates/mental_health_app_pitch_deck.jsscript42.4 KB
references/templates/middle_school_nutrition_lesson.jsscript26.8 KB
references/templates/mobile_pet_grooming_seed_pitch_deck.jsscript25.8 KB
references/templates/mobile_pet_grooming_service_overview.jsscript48.8 KB
references/templates/municipal_water_infrastructure_proposal.jsscript35.7 KB
references/templates/music_festival_seed_pitch_deck.jsscript27.6 KB
references/templates/music_label_pitch_deck.jsscript44.7 KB
references/templates/nonprofit_wildlife_conservation_prospectus.jsscript50.3 KB
references/templates/nursing_documentation_transformation_strategy.jsscript37.3 KB
references/templates/orbital_compute_investor_memo.jsscript45.1 KB
references/templates/paintball_arena_pitch_deck.jsscript31.5 KB
references/templates/paragliding_school_prospectus.jsscript37.6 KB
references/templates/pest_control_company_overview.jsscript33.6 KB
references/templates/pharma_product_launch_deck.jsscript42.3 KB
references/templates/photography_studio_portfolio.jsscript18.1 KB
references/templates/pressure_washing_company_profile.jsscript36.6 KB
references/templates/public_health_snus_field_guide.jsscript45.4 KB
references/templates/real_estate_development_pitch.jsscript29.7 KB
references/templates/real_estate_fund_investment_briefing.jsscript40.7 KB
references/templates/real_estate_investing_primer.jsscript43.4 KB
references/templates/real_estate_market_overview.jsscript18.0 KB
references/templates/real_estate_neighborhood_buyer_guide.jsscript27.8 KB
references/templates/real_estate_self_storage_community_pitch.jsscript62.0 KB
references/templates/regional_airport_pitch_deck.jsscript29.6 KB
references/templates/restaurant_concept_pitch_deck.jsscript20.8 KB
references/templates/restaurant_concept_vision_deck.jsscript24.4 KB
references/templates/restaurant_culinary_profile.jsscript25.1 KB
references/templates/restaurant_franchise_pitch_deck.jsscript39.2 KB
references/templates/restaurant_investor_pitch_deck.jsscript35.5 KB
references/templates/retail_bookstore_profile.jsscript29.4 KB
references/templates/retail_florist_business_profile.jsscript17.3 KB
references/templates/retail_pet_store_pitch_deck.jsscript23.2 KB
references/templates/retail_product_catalog_overview.jsscript27.4 KB
references/templates/retro_tech_cafe_pitch_deck.jsscript80.9 KB
references/templates/scuba_dive_operator_prospectus.jsscript37.7 KB
references/templates/seaborn_data_visualization_training.jsscript31.4 KB
references/templates/skateboarding_beginner_course_lesson.jsscript27.1 KB
references/templates/snowboard_school_prospectus.jsscript42.5 KB
references/templates/snowboarding_beginner_lesson.jsscript24.1 KB
references/templates/sports_betting_saas_pitch_deck.jsscript33.1 KB
references/templates/sports_market_expansion_strategy.jsscript93.5 KB
references/templates/sports_marketing_promo_calendar.jsscript21.3 KB
references/templates/sports_sponsorship_pitch_deck.jsscript30.2 KB
references/templates/student_transportation_company_overview.jsscript41.3 KB
references/templates/surf_school_intro_lesson.jsscript31.0 KB
references/templates/tech_hardware_expansion_strategy.jsscript41.1 KB
references/templates/tv_series_pitch_deck.jsscript38.5 KB
references/templates/university_giving_day_fundraising.jsscript25.0 KB
references/templates/urban_landscaping_service_proposal.jsscript28.9 KB
references/templates/us_history_student_presentation.jsscript38.1 KB
references/templates/vacation_rental_quarterly_financial_report.jsscript35.3 KB
references/templates/video_game_industry_history.jsscript32.0 KB
references/templates/video_game_pitch_deck.jsscript45.7 KB
references/templates/vintage_computer_cafe_pitch_deck.jsscript32.0 KB
references/templates/wakeboarding_coaching_prospectus.jsscript35.8 KB
references/templates/web3_defi_app_design_review.jsscript51.2 KB
references/templates/wellness_startup_seed_pitch_deck.jsscript57.6 KB
references/templates/wine_tourism_strategy_brief.jsscript33.8 KB
references/templates/youth_soccer_training_program.jsscript42.5 KB
references/templates/youtube_channel_media_kit.jsscript52.1 KB
scripts/__init__.pyscript0 B
scripts/add_slide.pyscript6.7 KB
scripts/check_overlaps.pyscript17.2 KB

references/editing.md

View on GitHub
# Editing Presentations

## When Given a Template — EDIT IT, NEVER Recreate

**If a template .pptx is attached, you MUST edit it directly using unpack/edit/pack. NEVER use pptxgenjs to create from scratch.** See [creating.md](creating.md) for the de novo workflow.

### Critical Rules

1. **ALWAYS edit the template file, even when the content doesn't match.** A quiz template used for a portfolio review? A Christmas template used for a skincare campaign? **It doesn't matter.** Unpack the template, replace the text, keep everything else. The visual style IS the template — backgrounds, shapes, media, colors, fonts — and you can only preserve that by editing in place.

2. **NEVER create from scratch with pptxgenjs when a template exists.** You cannot recreate a template's visual fidelity programmatically. Gradients, embedded images, custom shapes, theme colors, layout relationships — these are all lost when you start from an empty `new pptxgen()`. The result will always look worse than editing the original.

3. **NEVER use `sed`, `awk`, `perl`, or raw regex shell commands on XML files.** These tools break on XML escaping, shell quoting (e.g. apostrophes in content like "TWICE's"), and multi-line XML tags. Instead, use the provided Python scripts which handle all of this correctly:
   - `replace_text.py` — replace text in placeholder shapes (`--ph ctrTitle`, `--match "text"`)
   - `replace_nth_text.py` — replace specific substrings or duplicate text (`--find "OLD" --text "NEW"`)
   - For anything these scripts can't handle, use the Edit tool on the XML directly.

4. **Do NOT adapt the template's colors or fonts to "match" the topic.** If the template uses red (#DD3D4E) and the topic is "green energy", keep the red. The task is to follow the template's visual style exactly, not to pick colors that feel appropriate for the subject matter.

5. **Reuse, don't recreate.** Templates contain carefully designed assets — gradient backgrounds, decorative shapes, icons, logos. Use `inspect_slide.py --media` to see them. Copy and reference original media files directly — never approximate gradients with shapes or redraw icons.

6. **Content mismatch is expected.** The template might be a quiz, a Christmas card, or a restaurant menu. Your job is to replace ALL text with the new topic while preserving every visual element: backgrounds, shapes, images, colors, fonts, positions, sizes.

7. **Replace EVERY piece of template text, not just the obvious ones.** After replacing titles and body text, use `replace_nth_text.py --list` on each slide to find leftover text in footers, captions, subtitle shapes, grouped shapes, and text boxes. If it came from the template and isn't your content, replace it.

### Style Matching Rule

**When editing an existing presentation, always match its existing style** — colors, fonts, layout patterns, background treatment, and visual language. Do not impose a new theme unless the user explicitly asks to restyle or change the look. Analyze the existing slides first (thumbnails, color values, font choices) and replicate them faithfully.

### Font Preservation Rule

**Always preserve the original font declarations in the XML**, even if the font isn't installed in the current environment. The PPTX will render correctly when opened on the end user's machine (which likely has the font). Changing a `typeface="Calibri"` to `typeface="Liberation Sans"` just because Calibri isn't installed locally would break the presentation for the recipient.

- When **editing** slides: copy `<a:rPr>` font attributes from existing text runs. Never substitute fonts.
- When **adding** new text to an existing deck: use the same `typeface` as surrounding text on that slide.
- `detect_fonts.py` warnings about missing fonts are **informational for rendering QA** — they tell you the preview may look different, not that you should change the font.

### Workflow Summary

**unpack → overview → pick slides → delete extras → replace ALL text → verify no leftovers → fix overlaps → clean → pack**

```bash
python $SKILL_DIR/scripts/office/unpack.py template.pptx unpacked/
python $SKILL_DIR/scripts/inspect_slide.py unpacked/ --summary --theme --media   # compact overview
python $SKILL_DIR/scripts/inspect_slide.py unpacked/ppt/slides/slide1.xml       # detail for slides you keep
# Delete unwanted slides (by number or --keep the ones you want)
python $SKILL_DIR/scripts/delete_slide.py unpacked/ --keep 1 4 8
# Replace text in EVERY kept slide (see below for details)
python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --text "New Title"
# If duplicate text (e.g., multiple "Chapter Title" bullets), use replace_nth_text.py:
python $SKILL_DIR/scripts/replace_nth_text.py unpacked/ppt/slides/slide4.xml --find "Chapter Title" --nth 1 --text "2025 VISION"

# ── VERIFY: no template text remains ──
python $SKILL_DIR/scripts/replace_nth_text.py unpacked/ppt/slides/slide1.xml --list
python $SKILL_DIR/scripts/replace_nth_text.py unpacked/ppt/slides/slide2.xml --list
# ... repeat for every kept slide. If ANY original template text remains, replace it now.

# ── FIX OVERLAPS: auto-apply text shrink to overlapping shapes ──
python $SKILL_DIR/scripts/check_overlaps.py unpacked/ --fix
python $SKILL_DIR/scripts/clean.py unpacked/
python $SKILL_DIR/scripts/office/pack.py unpacked/ output.pptx --original template.pptx
```

**Common failure: leftover template text.** After replacing text, always run `--list` on every slide and scan the output. Template text like "Hello there", "Name Title or Position", "Elaborate on the featured statistic", "SlidesCarnival", or any text you didn't write must be replaced or removed.

---

## Template-Based Workflow (Detailed)

When using an existing presentation as a template:

1. **Unpack**: `python $SKILL_DIR/scripts/office/unpack.py template.pptx unpacked/`

2. **Get overview** — use `--summary` to avoid output truncation on large templates:
   ```bash
   # Compact overview (one line per slide with background colors, theme fonts)
   python $SKILL_DIR/scripts/inspect_slide.py unpacked/ --summary --theme --media

   # Visual overview — see what slides actually look like
   python $SKILL_DIR/scripts/thumbnail.py template.pptx

   # Visual media grid — see all images/icons/logos at a glance
   python $SKILL_DIR/scripts/media_grid.py unpacked/

   # Then inspect specific slides you plan to keep (detailed per-run formatting)
   python $SKILL_DIR/scripts/inspect_slide.py unpacked/ppt/slides/slide1.xml
   ```

   **Do NOT manually run `soffice` + `pdftoppm`** — use `thumbnail.py` and `media_grid.py` instead. They handle conversion, grid layout, and labeling automatically.

3. **Plan slide mapping** — decide which template slides to KEEP and what content goes on each.

   The template may have completely different content (quiz, menu, holiday card). **This is expected.** Your job: pick the best-looking slides from the template, delete the rest, and replace text.

   **Procedure:**
   1. Look at the `--summary` output to see what each slide contains
   2. For each section of YOUR content, pick a template slide with a suitable layout (title slide, content with cards, table, chart area, conclusion)
   3. Write down the mapping: "slide1 → my title, slide3 → agenda, slide9 → data table, slide12 → scoreboard, slide20 → conclusion"
   4. Delete everything else

   **Layout variety tips** — don't default to basic title + bullet slides:
   - Multi-column layouts for comparisons
   - Card/grid layouts for ratings or features
   - Table slides for data comparisons
   - Full-bleed image slides for section dividers
   - Scoreboards or stat callouts for key numbers

4. **Build presentation** (do this yourself, not with subagents):
   ```bash
   # Delete unwanted slides (by number or keep only the ones you want)
   python $SKILL_DIR/scripts/delete_slide.py unpacked/ 3 5 6 7 9 10
   # Or equivalently: keep only slides 1, 2, 4, 8
   python $SKILL_DIR/scripts/delete_slide.py unpacked/ --keep 1 2 4 8

   # Duplicate a slide you want to reuse (auto-inserts into presentation order)
   python $SKILL_DIR/scripts/add_slide.py unpacked/ slide2.xml                  # append at end
   python $SKILL_DIR/scripts/add_slide.py unpacked/ slide2.xml --after slide4.xml  # insert after slide4
   ```
   - **Complete all structural changes before step 5**

5. **Replace placeholder text** — use `replace_text.py` instead of manual XML editing:
   ```bash
   # Simple text replacement (inherits formatting from template)
   python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --text "New Title"

   # Multi-line text (creates line breaks)
   python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph subTitle --text "Line 1\nLine 2"

   # Custom formatting per run (when you need different fonts/colors/sizes)
   python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --runs '[
     {"text": "Gift the Glow", "size": 4800, "color": "accent1", "font": "Satisfy"},
     {"br": true},
     {"text": "LuminaBotani • Holiday 2025", "size": 2000, "color": "accent4"}
   ]'

   # Match by text content instead of placeholder type
   python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --match "Christmas" --text "Holiday Special"
   ```
   **Use subagents here if available** — slides are separate XML files, so subagents can replace text in parallel.

   For shapes not covered by `replace_text.py` (images, charts, complex grouped elements), use `replace_nth_text.py` for targeted `<a:t>` element edits, or the Edit tool on the XML directly — see Editing Content below.

   > ⚠️ **NEVER use `sed`, `awk`, or shell regex commands on XML files.** They break on XML escaping, shell quoting (apostrophes, special chars), and multi-line tags. Always use the Python scripts or the Edit tool instead.

6. **Clean**: `python $SKILL_DIR/scripts/clean.py unpacked/`

7. **Pack**: `python $SKILL_DIR/scripts/office/pack.py unpacked/ output.pptx --original template.pptx`

---

## Scripts

| Script | Purpose |
|--------|---------|
| `inspect_slide.py` | **Inspect placeholders, text, images, and media** — use first |
| `check_overlaps.py` | **Lint for overlapping shapes** — run after editing, before packing |
| `replace_text.py` | **Replace placeholder text preserving formatting** — use for edits |
| `replace_nth_text.py` | **Replace substrings or duplicate text in individual `<a:t>` elements** |
| `resize_shape.py` | **Resize or reposition shapes** — fix text overflow without editing XML |
| `delete_slide.py` | **Delete slides** — remove from presentation order + cleanup |
| `add_slide.py` | **Duplicate slide or create from layout** — auto-inserts into order |
| `unpack.py` | Extract and pretty-print PPTX |
| `clean.py` | Remove orphaned files |
| `media_grid.py` | **Visual thumbnail grid of all media assets** |
| `pack.py` | Repack with validation |
| `thumbnail.py` | Create visual grid of slides |

### inspect_slide.py

```bash
# Full inspection: slides + theme colors + media inventory
python $SKILL_DIR/scripts/inspect_slide.py unpacked/ --theme --media

# Inspect a single slide
python $SKILL_DIR/scripts/inspect_slide.py unpacked/ppt/slides/slide1.xml
```

Shows text shapes (with placeholder type, formatting, autofit mode, dimensions), image shapes (with resolved media file paths), theme colors, and a full media inventory. Use this **before** editing.

Example output:
```
=== Theme Colors ===
  Scheme: Christmas
    dk1          = system:000000
    lt1          = system:FFFFFF
    accent1      = #F33D41

=== slide1.xml ===

[0] Picture 3  4.0"×3.0"
  image: ppt/media/image1.png (rId2)

[1] Title 1 (ctrTitle)  8.2"×1.4" autofit=fixed
  text: "This is your Christmas presentation"
  'T'                                  → Satisfy 44pt accent1
  'Christmas'                          → Satisfy 48pt accent1

=== Media Inventory ===
  ppt/media/image1.png                      234 KB  png   ← slide1.xml
  ppt/media/image2.svg                       12 KB  svg   ← slide2.xml, slide3.xml
  ppt/media/logo.emf                         89 KB  emf   ← slideLayout1.xml

  Total: 3 files, 335 KB
```

The media inventory shows which slides/layouts reference each file — critical for knowing which assets to preserve during template editing.

### media_grid.py

```bash
# Visual grid of all media assets (images, icons, logos, backgrounds)
python $SKILL_DIR/scripts/media_grid.py unpacked/

# Custom columns
python $SKILL_DIR/scripts/media_grid.py unpacked/ assets --cols 6
```

Creates `media_grid.jpg` — a thumbnail grid showing every file in `ppt/media/` with labels (filename, size, referencing slides). Non-image formats (EMF, WMF, SVG) appear as colored placeholders with format labels.

**Use this to visually identify** which images are logos, which are decorative backgrounds, and which are content — critical for knowing what to preserve during template editing.

### replace_text.py

```bash
# Simple replacement (inherits font, size, color from template)
python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --text "New Title"

# Multi-line
python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --text "Line 1\nLine 2"

# Custom formatting per run (JSON)
python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --runs '[
  {"text": "Gift the Glow", "size": 4800, "color": "accent1", "font": "Satisfy"},
  {"br": true},
  {"text": "LuminaBotani • Holiday 2025", "size": 2000, "color": "accent4"}
]'

# Match by text content (case-insensitive)
python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --match "Christmas" --text "Holiday"

# Dry run (preview without modifying)
python $SKILL_DIR/scripts/replace_text.py unpacked/ppt/slides/slide1.xml --ph ctrTitle --text "New" --dry-run
```

Replaces text in a placeholder while preserving paragraph properties (alignment, spacing) and inheriting formatting from the template's existing runs. Modifies the file in-place.

**JSON run properties** (all optional — omitted properties inherit from template):

| Property | Type | Example | Notes |
|----------|------|---------|-------|
| `text` | string | `"Gift the Glow"` | The text content |
| `br` | boolean | `true` | Line break (mutually exclusive with text) |
| `size` | integer | `4800` | Hundredths of a point (4800 = 48pt) |
| `color` | string | `"accent1"` or `"#FF0000"` | Scheme name or hex |
| `font` | string | `"Satisfy"` | Typeface name |
| `bold` | boolean | `true` | Bold weight |
| `italic` | boolean | `true` | Italic style |

**Tip:** Always add `--autofit` when your replacement text is longer than the original to prevent overflow:

### resize_shape.py

```bash
# List all shapes with current positions and dimensions
python $SKILL_DIR/scripts/resize_shape.py unpacked/ppt/slides/slide1.xml --list

# Set absolute height (inches) — text box too short for new content
python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph body --height 3.5

# Set absolute width and height
python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph ctrTitle --width 9.0 --height 2.0

# Grow taller by 0.5" relative to current size
python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph body --dh 0.5

# Move a shape down by 0.3" to make room above
python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph body --dy 0.3

# Match by shape name or text content
python $SKILL_DIR/scripts/resize_shape.py slide.xml --name "Title 1" --height 2.0
python $SKILL_DIR/scripts/resize_shape.py slide.xml --match "Lorem" --height 4.0

# Dry run (preview without modifying)
python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph body --dh 0.5 --dry-run
```

Adjusts shape dimensions and/or position in the slide XML without touching text or formatting. All values are in **inches**. Use `--width`/`--height` for absolute sizes, `--dw`/`--dh` for relative adjustments, and `--x`/`--y`/`--dx`/`--dy` for position.

**Common patterns:**

| Problem | Fix |
|---------|-----|
| Text overflows bottom of box | `--dh 0.5` (grow taller) or `--height 4.0` (set exact) |
| Text wraps too much (box too narrow) | `--dw 1.0` (grow wider) |
| Two shapes overlap after resize | `--dy 0.5` on the lower shape (push it down) |
| Need to see current dimensions | `--list` |

### unpack.py

```bash
python $SKILL_DIR/scripts/office/unpack.py input.pptx unpacked/
```

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

### delete_slide.py

```bash
# Delete specific slides (by filename or number)
python $SKILL_DIR/scripts/delete_slide.py unpacked/ slide3.xml slide5.xml slide7.xml
python $SKILL_DIR/scripts/delete_slide.py unpacked/ 3 5 7

# Keep only specific slides (delete everything else) — usually easier
python $SKILL_DIR/scripts/delete_slide.py unpacked/ --keep 1 4 8

# List all slides in presentation order
python $SKILL_DIR/scripts/delete_slide.py unpacked/ --list

# Dry run (preview without modifying)
python $SKILL_DIR/scripts/delete_slide.py unpacked/ --keep 1 4 8 --dry-run
```

Removes slides from `<p:sldIdLst>` in `presentation.xml` and automatically runs cleanup to remove orphaned slide files, media, and relationships. Prevents deleting ALL slides (at least one must remain).

**Use `--keep` mode** when the template has many slides and you only want a few — it's easier to list what you want than what you don't.

### add_slide.py

```bash
# Duplicate slide2, append at end
python $SKILL_DIR/scripts/add_slide.py unpacked/ slide2.xml

# Duplicate slide2, insert after slide1
python $SKILL_DIR/scripts/add_slide.py unpacked/ slide2.xml --after slide1.xml
python $SKILL_DIR/scripts/add_slide.py unpacked/ slide2.xml --after 1

# Create from a layout template
python $SKILL_DIR/scripts/add_slide.py unpacked/ slideLayout2.xml
```

Duplicates an existing slide (or creates from a layout), then automatically inserts it into the slide order in `presentation.xml`. Use `--after` to control position.

### clean.py

```bash
python $SKILL_DIR/scripts/clean.py unpacked/
```

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

### pack.py

```bash
python $SKILL_DIR/scripts/office/pack.py unpacked/ output.pptx --original input.pptx
```

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

### thumbnail.py

```bash
python $SKILL_DIR/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>`.

**Delete**: Use `delete_slide.py` — removes from `<p:sldIdLst>` and cleans up orphans automatically:
```bash
python $SKILL_DIR/scripts/delete_slide.py unpacked/ --keep 1 4 8   # keep only these
python $SKILL_DIR/scripts/delete_slide.py unpacked/ 3 5 7           # delete these
```

**Add/Duplicate**: Use `add_slide.py` — creates the file and auto-inserts into `<p:sldIdLst>`:
```bash
python $SKILL_DIR/scripts/add_slide.py unpacked/ slide2.xml --after slide1.xml
```
Never manually copy slide files — the script handles notes references, Content_Types.xml, and relationship IDs.

**Reorder**: Rearrange `<p:sldId>` elements in `presentation.xml` using the Edit tool.

---

## 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 `replace_text.py`, `replace_nth_text.py`, or the Edit tool — NEVER `sed`/`awk`/shell regex.** The Python scripts handle XML escaping, formatting preservation, and shell quoting automatically. `sed` will silently corrupt XML or fail on content with apostrophes, angle brackets, or special characters.

### 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, causing overlap with neighboring elements

### Preventing Text Overflow

Text overflow is the #1 cause of `no_render_artifacts` and `layout_match` failures. PPTX shapes have fixed absolute positions — they don't reflow like HTML.

**Check dimensions first** with `inspect_slide.py`:
```
[0] Title 1 (ctrTitle)  8.2"×1.4" autofit=fixed
```
The `8.2"×1.4"` tells you how much space you have. `autofit=fixed` means text will clip/overflow if too long.

**Prevention strategies (in order of preference):**

1. **Use `--autofit`** when replacing text — adds `<a:normAutofit/>` to the text box, which makes PowerPoint auto-shrink the font to fit:
   ```bash
   python $SKILL_DIR/scripts/replace_text.py slide.xml --ph ctrTitle --text "A Very Long Title" --autofit
   ```

2. **Resize the text box** with `resize_shape.py` — make it taller or wider to fit longer content:
   ```bash
   # Grow body box taller by 0.5"
   python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph body --dh 0.5

   # Set exact height for a text box that needs more room
   python $SKILL_DIR/scripts/resize_shape.py slide.xml --ph body --height 4.0

   # If resizing causes overlap, move the shape below it down
   python $SKILL_DIR/scripts/resize_shape.py slide.xml --name "Footer Text" --dy 0.5
   ```

3. **Reduce font size explicitly** in `--runs` when replacement is significantly longer than original:
   ```bash
   python $SKILL_DIR/scripts/replace_text.py slide.xml --ph body --runs '[
     {"text": "Long paragraph...", "size": 1600}
   ]'
   ```

4. **Adapt content to fit** — shorten text, use abbreviations, split across multiple slides. The model should respect the template's design constraints.

5. **Reduce line spacing** — tighten `<a:lnSpc>` in `<a:pPr>` to fit more lines:
   ```xml
   <a:pPr><a:lnSpc><a:spcPts val="1600"/></a:lnSpc></a:pPr>
   ```

6. **Set autofit manually in XML** — add `<a:normAutofit/>` inside `<a:bodyPr>`:
   ```xml
   <!-- Before: text clips at box boundary -->
   <a:bodyPr wrap="square" rtlCol="0"/>

   <!-- After: text auto-shrinks to fit -->
   <a:bodyPr wrap="square" rtlCol="0"><a:normAutofit/></a:bodyPr>
   ```

**Autofit modes in PPTX:**

| XML Element | Behavior | When to Use |
|-------------|----------|-------------|
| `<a:normAutofit/>` | Auto-shrink font to fit box | **Default choice** — preserves layout |
| `<a:spAutoFit/>` | Auto-grow box to fit text | Risky — may overlap neighbors |
| `<a:noAutofit/>` | Fixed — text clips at boundary | Only for decorative text |
| *(none)* | Varies by shape type | Check with `inspect_slide.py` |

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

### Replacing Specific Text (Substrings, Duplicates, Form Fields)

**Use `replace_nth_text.py`** when `replace_text.py` doesn't fit — it operates on individual `<a:t>` elements and does **substring replacement** by default.

**⚠ Shell quoting**: If replacement text contains `$`, use **single quotes** to prevent bash expansion. `"$4,500"` becomes `",500"` (bash eats `$4`). Use `'$4,500'` instead.

#### Substring fields (e.g., "Debut Year: YYYY")

When a shape has multiple fields like `Debut Year: YYYY | Fan Club: [Name]`, `replace_text.py --match` would replace the ENTIRE shape text. Use `replace_nth_text.py` to swap individual placeholders:

```bash
# Only the matched portion is replaced — surrounding text is preserved:
#   <a:t>Debut Year: YYYY</a:t>  →  <a:t>Debut Year: 2015</a:t>
python $SKILL_DIR/scripts/replace_nth_text.py slide2.xml --find "YYYY" --all --text "2015"
python $SKILL_DIR/scripts/replace_nth_text.py slide2.xml --find "[Fan Club Name]" --all --text "ONCE"
python $SKILL_DIR/scripts/replace_nth_text.py slide2.xml --find "[Company Name]" --all --text "JYP Entertainment"
```

#### Duplicate text (e.g., multiple "Chapter Title" bullets)

When `edit_file` says "Found N matches," **don't build unique `old_string` with XML context** — that wastes tokens and is fragile:

```bash
# Step 1: See all text elements with indices
python $SKILL_DIR/scripts/replace_nth_text.py slide4.xml --list --find "Chapter Title"
#  Idx   Line  Text
#  ---   ----  ----
#    3    132  Chapter Title
#    4    176  Chapter Title

# Step 2: Replace each occurrence individually (1-based)
python $SKILL_DIR/scripts/replace_nth_text.py slide4.xml --find "Chapter Title" --nth 1 --text "2025 CREATIVE VISION" --full
python $SKILL_DIR/scripts/replace_nth_text.py slide4.xml --find "Chapter Title" --nth 1 --text "CIRCULARITY METRICS" --full
# Note: after replacing the 1st, the former 2nd becomes the new 1st

# Or target by absolute index (0-based, from --list output)
python $SKILL_DIR/scripts/replace_nth_text.py slide4.xml --index 3 --text "2025 CREATIVE VISION"
python $SKILL_DIR/scripts/replace_nth_text.py slide4.xml --index 4 --text "CIRCULARITY METRICS"
```

#### When to use which tool

| Scenario | Tool |
|----------|------|
| Replace text in a placeholder shape (ctrTitle, subTitle, body) | `replace_text.py --ph` |
| Replace text matched by content, targeting the whole shape | `replace_text.py --match` |
| Swap a substring field like "YYYY" → "2015" preserving context | `replace_nth_text.py --find --text` |
| Duplicate text in same shape (multiple bullets with same text) | `replace_nth_text.py --find --nth --full` |
| Need to target a specific `<a:t>` element precisely | `replace_nth_text.py --index` |
| Bulk replace all occurrences of a string | `replace_nth_text.py --find --all` |
| ~~Replace text with sed/awk~~ | **NEVER** — use the tools above instead |

### 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)
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall