gslides-sync

scripts/sync-gslides.py replaces a Google Slides deck with a local .pptx; Drive converts it. It then fixes what the converter gets wrong. It runs on a bare python3, and it finds the service-account key on its own: --sa-key, then $GOOGLE_SA_KEY, then ~/.config/gdoc-sync/sa-key.json, then gcloud ADC.

Quick start

python3 scripts/sync-gslides.py deck.pptx --pres-id 1ImErdoIfgdebBjHvZ7YBbkUaeVLiswlPiA87ae44taI \
  --title "DEV delivery - Nov 2026" --thumbnails /tmp/deck-thumbs

[0/6] Deck unchanged since the last sync
[1/6] Pushed pptx: deck.pptx (15,865,389 bytes); renamed to 'DEV delivery - Nov 2026'; page 960x540pt
[2/6] Fixed 0 in-deck slide-anchor links
[3/6] Skipped cross-pres link rewriting (no --cross-pres-map)
[4/6] Resized 0 oversized images (max width 960pt)
[5/6] Skipped RTL (use --rtl to enable)
[6/6] Saved 14 slide thumbnails → /tmp/deck-thumbs/slide-NN.png
Done. https://docs.google.com/presentation/d/1ImErdo.../edit

--pres-id is the token in docs.google.com/presentation/d/<ID>/edit. The deck must already exist and be shared with the service account's email as Editor. A service account can't create files, so create the empty deck in the UI first. Look at the thumbnails after every push.

The pipeline

Narrated decks

Google Slides drops a pptx's embedded audio on every import, and the Slides API can't insert audio. The narration for a Google Slides deck is one small autoplaying Drive video per slide, handled by the narrating-pptx skill (its Google Slides section, scripts/gslides_narration.py). The two skills split the work:

1. Push the clean, audio-free pptx with this skill. If you push the narrated pptx instead, the audit warns and the slides keep silent speaker icons.
2. Attach the narration with gslides_narration.py insert, then confirm it with gslides_narration.py check.
3. After every later push, run insert again. The push deletes the videos. This skill counts them before pushing, and afterwards prints the exact insert/check commands, with the Drive folder already filled in.

Gotchas

The full list is in reference/gotchas.md. The ones that bite most:

• Every push wipes the deck, including pending suggestions, comments on changed shapes, hand edits, and every element added through the API, such as narration videos. Re-run gslides_narration.py insert after each push. Each push is an entry in File → Version history.
• Charts and embedded video become static images, and chart category labels can disappear. Render charts as pictures in the pptx you push to Google.
• Fonts outside Google Fonts fall back to Arial, which changes line breaks. Use Google Fonts in the source pptx.
• Decks over 100 MB fail to convert. Compress the images or split the deck.

When to use / not

Files

gslides-sync/
├── SKILL.md                    # this file
├── README.md                   # GitHub landing page
├── scripts/sync-gslides.py     # the script (stdlib only; google-auth used when present)
├── scripts/README.md           # flags and exit codes
└── reference/
    ├── auth-setup.md           # service account, API enablement, sharing, ADC fallback
    └── gotchas.md              # destructive behaviors, converter losses, limits

Related skills

• gdoc-sync: the same pattern for markdown → Google Docs, with the same key.
• presentation-generator produces image-per-slide decks this skill consumes.
• narrating-pptx builds the narration, and its Google Slides section attaches it to the deck this skill pushed. self-presenting-decks runs the whole deck → narration → video chain.