CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

jbaruch/speaker-toolkit

Twelve skills for conference speakers covering rhetoric analysis, talk authoring, deck building and export, CFP submissions, publishing, illustrations, shownotes, screencast production, and vertical shorts, informed by a 113-entry Presentation Patterns taxonomy (83 observable: 64 patterns + 19 antipatterns; 30 unobservable: 21 patterns + 9 antipatterns).

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Medium

Suggest reviewing before use

Overview
Quality
Evals
Security
Files

deck-editing-rules.mdrules/

alwaysApply:
Yes

Deck Editing Rules

How to make STRUCTURAL edits (delete / reorder / cross-deck import) to an existing .pptx and how to apply illustration backgrounds — distinct from generating slide structure (see rules/slide-generation-rules.md).

Don't Edit Decks With python-pptx

  • python-pptx and clipboard Slides.Paste drop each slide's <p:bg> picture fill, flattening illustrated decks whose full-bleed art is a background fill.
  • python-pptx editing OOXML from outside the app breaks strict OOXML that Keynote refuses to open.
  • All structural edits go through RunDeckOps — there is no python-pptx slide-delete / slide-reorder path.

Use Real PowerPoint via RunDeckOps (macOS)

  • Drive the actual PowerPoint app so PowerPoint serializes the file — fonts, full-bleed backgrounds, masters, and relationships are preserved and the output stays Keynote-openable. The original is never modified (the macro writes a COPY).
  • skills/presentation-creator/scripts/RunDeckOps.bas builds the target deck with Slides.InsertFromFile (the programmatic "Reuse Slides", keep-source- formatting — NOT clipboard paste). Invoke it through skills/presentation-creator/scripts/run-deck-ops.sh:
    bash skills/presentation-creator/scripts/run-deck-ops.sh \
      <basePath> <outPath> <importSpec> <orderStr> <replaceStr>
    # orderStr: "BASE:1 BASE:2 voxxed:13 BASE:49"  (alias:1-based-slide-#)
  • Set up DeckOps in PowerPoint. Create the macro container, import the module, approve macros for that file, and grant Automation consent. Follow skills/presentation-builder/references/deck-editing-setup.md.
  • Never assume whether setup has been done — run deckops-doctor.py --vault-root <path> and act on its status. Statuses and their routing live in Step 0 of the setup doc.
  • The doctor is the only reader of a STALE macro import. A saved .pptm yields no VBA source; the loaded module's content stamp comes back from the running PowerPoint, never off disk.
  • A container imported before the stamp existed answers no version at all. The doctor reads the .pptm to tell that from a container that never had the module — classification lives in skills/presentation-creator/scripts/deckops-doctor.py's inspect_container / verdict.
  • The file read refines the verdict; the live probe remains the authority.
  • The macro container has one canonical location, <vault_root>/.deckops/DeckOps.pptm. The importable .bas is exported beside it with sync-deck-drivers.py export --to <vault_root>/.deckops.
  • Never hand the user an import path inside the plugin tree.

Add a Generated Illustration as a Slide Background

  • A generated illustration must become the slide's BACKGROUND FILL, not a top-pasted picture: the layout's halftone-dot overlay sits above the slide background but below shapes, so a pasted picture lands above the dots.
  • Don't hand-build the slide in python-pptx: a fresh deck can't borrow the source deck's layout (and its overlay).
  • RunDeckOps.bas's MakeBgImageSlide clones a comic template slide, sets Slide.Background.Fill.UserPicture, retitles, and saves a 1-slide deck. Pick a template whose title sits in the image's clear safe zone. Invoke via bash skills/presentation-creator/scripts/make-bg-slide.sh, then import with bash skills/presentation-creator/scripts/run-deck-ops.sh (order token <alias>:1).
  • Generate the illustration first with the illustrations skill, then make it a background slide here.

Set Illustration Backgrounds in Bulk at Creation Time

  • When building a NEW deck, FULL-slide illustrations must also be slide BACKGROUND FILLS, not picture shapes — same overlay reason as above. python-pptx must not insert them as shapes, and must not be the last writer (it re-drops <p:bg> fills on save).
  • apply-illustrations-to-deck.py records each FULL slide in a backgrounds manifest (--backgrounds-out) and applies only scrim + title; it does NOT insert FULL-slide pictures. IMG+TXT slides keep a left-column picture shape.
  • RunDeckOps.bas's ApplyBackgrounds then sets all FULL backgrounds via Slide.Background.Fill.UserPicture in one pass. Invoke via bash skills/presentation-creator/scripts/apply-backgrounds.sh <baseCopy> <out> <manifest.json>.
  • Run this as the FINAL write of the build — after the structural walk, scrim/ title, and speaker-note injection — so no later python-pptx save drops the fills.

Progressive-Reveal Build Expansion

  • RunDeckOps.bas's ExpandBuilds replaces each progressive-reveal parent slide with its build frames as full-bleed background-fill slides, via real PowerPoint slide insertion — never python-pptx. Invoke via bash skills/presentation-creator/scripts/expand-builds.sh <baseCopy> <out> <builds-manifest.json> (manifest from build-expansion-manifest.py).
  • Run ExpandBuilds BEFORE the by-index passes (notes, backgrounds, QR): it renumbers every slide after a build parent, so those passes must key on the POST-expansion deck. It processes parents descending so one parent's expansion can't shift another's index.
  • Each build frame carries the notes spoken while it is on screen. build-expansion-manifest.py --notes --notes-out splits a parent's note at its [BUILD NN] cue lines and writes the whole deck's notes keyed on the POST-expansion deck; inject-notes.sh applies that map to every slide.
  • Never hand-compute post-expansion note keys.
  • ExpandBuilds writes only the manifest's notes, the final frame's segment, which the notes pass rewrites unchanged. Moving notes needed no macro change.

macOS-Only — VBA Layer Untestable in CI

  • The PowerPoint-driving layer (VBA + AppleScript) needs the Microsoft PowerPoint app and macOS Automation, so it CANNOT run in Linux CI. Validate it manually: re-open output in PowerPoint AND Keynote; confirm size recovers and a <p:bg>-blipFill check finds the expected slides.
  • The deterministic Python/shell helpers (illustration apply, manifest→spec) ARE unit-tested in tests/ — only the PowerPoint-driving layer is exempt.
  • Exempt artifacts, each with its manual validation procedure in skills/presentation-builder/references/deck-editing-setup.md (what to run, what to observe, what counts as a pass), all in skills/presentation-creator/scripts/:
    • RunDeckOps.bas and build-deck.applescript — Step 5 smoke test.
    • inject-notes.applescript — Step 5, Notes driver check.
    • deckops-version.applescript — Step 0, the deckops-doctor.py probe.
    • run-deck-ops.applescript, apply-backgrounds.applescript, expand-builds.applescript, insert-qr.applescript, make-bg-slide.applescript and make-placeholder-slide.applescript — Step 6, item 5: open the pass's output in PowerPoint and Keynote, confirm no "Repair" prompt and the expected slides, art and backgrounds.
    • Adding a driver means adding it to this list with its procedure.
  • skills/presentation-creator/scripts/deckops-doctor.py splits along the same line: the AppleScript probe is exempt, while path derivation, probe-output parsing, and the verdict table are unit-tested in tests/test_deckops_doctor.py against synthetic probe results.

Mac PowerPoint VBA Landmines (all handled in RunDeckOps)

  • run VB macro converts every string parameter to Mac Roman: a character outside it arrives in VBA as ?, with no error. Text never crosses raw: the wrappers send ASCII through deck-text-bridge.py, and DecodeBridgeText restores it at the top of each macro. A new macro parameter carrying text does the same.
  • Filename collision: PowerPoint keys open decks by filename and silently returns an already-open same-named deck from Presentations.Open. Always operate on UNIQUELY-NAMED copies; the macro also guards and errors loudly.
  • Slide.MoveTo / Slides.FindBySlideID raise E_INVALIDARG on current Mac builds — avoided by appending in target order via InsertFromFile.
  • SaveCopyAs rejects FileFormat / EmbedTrueTypeFonts enum args — use a bare SaveCopyAs FileName:=... (base is already .pptx).
  • Sandboxed PowerPoint can't create a file in a Google Drive File-Provider folder (E_FAIL): save to a local staging path, then move into Drive with the shell. run-deck-ops.sh does this automatically.

README.md

tile.json