Speaker Toolkit

An eleven-skill presentation system for conference speakers: analyze your existing talks to extract your rhetoric patterns, create new presentations that match your documented style, produce the deck illustrations + thumbnail visual layer, publish talk pages to a Jekyll shownotes site, verify a recorded screencast against its storyboard, and edit a Camtasia screencast into a finished video.

What's New (0.21.0)

Focused presentation skills — author a talk with presentation-creator, build or export it with presentation-builder, coordinate delivery with presentation-publisher, and write submissions with cfp-writer. Independent requests open only their action's references and selected profile fields. The catalog's historical identity is preserved.

What's New (0.19.0)

Evidence-exact reparsing — fresh ingress work now uses schema-v5 claims, returns, talk records, and scoring. Every processed talk records an exhaustive outcome for each of the 83 observable catalog entries, bound to the exact live catalog and to owner-validated transcript, slide, video, or metadata evidence. Older generations remain readable history but cannot enter the current scoring cohort by implication.

Defensible absence and ready-to-use classification — all observable entries declare explicit evidence gates, and the catalog keeps absence decisions source-bound. Profile schema v5 preserves each pattern's exact denominator and automatically applies the bundled speaker-toolkit-default@1 thresholds. A vault may provide a strict optional override. If that file is present but invalid, profile generation stops instead of silently falling back. Mastery/novelty, antipattern recurrence, underuse, combinations, trends, and modes report availability independently. Section 15 readers still accept occurrence-only v2 blocks, while every replacement writes a policy-bound v3 block.

Safer installed operation — toolkit commands resolve from the installed plugin root and use the vault's configured Python interpreter. A stdlib-only runtime probe reports each source lane independently, while atomic, source-bound transcript quality and timing receipts keep optional enrichment failures from replacing trusted text.

What's New (0.18.27)

Real PowerPoint deck engine — decks are now created and edited through the real PowerPoint app (VBA driven via AppleScript), replacing python-pptx and the MCP PPT server, which had been silently emitting broken .pptx files. A single DeckOps module covers whole-deck creation, placeholder slides, background images, and QR insertion; speaker notes go through PowerPoint's AppleScript object model instead of a macro, so they keep every Unicode character. The deterministic pieces (op validation, notes validation, slide targeting, color matching) are unit-tested while the PowerPoint automation layer is validated by opening the deck. macOS + Microsoft PowerPoint.

QR codes that survive deck reuse — the QR step detects an existing QR on any slide and replaces it in place, so a deck trimmed from another talk no longer ends up with a duplicate or a stale code. The short link's back-half is always the talk slug (bit.ly custom back-half and rebrand.ly slashtag), uses the vault's custom domain when one is configured, and the custom-domain decision is captured and saved on the first short link. Slugs are composed date-less, so the QR and the published shownotes page always match.

narrative.md for early review — narrative.md is now a TL;DR plus a one-line-per-slide walk, generated from a partial outline in Phases 1–2 so the argument can be reviewed before any slide exists.

What's New (0.18.7)

Progressive-reveal build expansion — the toolkit now assembles generated build frames into the deck: a new ExpandBuilds PowerPoint pass replaces each progressive-reveal parent slide with its frames as full-bleed slides (notes on the final frame), so a build sequence becomes the sequential slides you advance through. Pairs with poster-theatrical for pure full-bleed, builds-and-all decks.

Deck tooling works on installed plugins — tessl install strips .bas/.applescript files, which had left the PowerPoint deck layer dead on any installed copy. The drivers now ship as committed .txt mirrors and are restored automatically on first use (sync-deck-drivers.py), so RunDeckOps.bas and the AppleScript drivers are there when you need them — no manual recovery. And deckops-doctor.py now answers whether the one-time PowerPoint setup is done, where the macro container is, and — the one nothing could see before — whether the module imported into DeckOps.pptm is the build that shipped, or an old one still quietly running.

No more per-illustration permission clicks — the background and build passes now stage illustrations into PowerPoint's own sandbox container before applying them, so the "grant access / select file" prompt that used to fire on every slide (once per Google Drive image) collapses to zero — no Full Disk Access grant needed.

Poster-theatrical composition — a style-wizard option where every slide is full-bleed and the title + footer are rendered into the image (stylized, blended), with only the QR code added afterward. No overlaid titles, no safe zones — an "all art, no chrome" look. Chosen in the wizard and baked into the STYLE ANCHOR header.

Idea-sourcing wizard + render-before-bake gate — illustration style strategy is now an explicit multi-select wizard: pick where the visual ideas come from (your usual, mode/series match, new, wild, what's trending, or bring your own), with a Quick-default fast path that still renders and shows. The strategy steps are individually gated, and a new --check-style-explore verdict plus a guard in generate-illustrations.py refuse to generate from any model that wasn't rendered in the exploration grid the speaker reviewed — you can no longer bake a model into the STYLE ANCHOR by reasoning alone.

Explicit engine & theme sourcing — deck tooling (PowerPoint/pptx vs presenterm terminal-markdown) is now a first-class Phase 2 decision sourced through the same wizard, recorded on the outline (talk.engine) instead of inferred at build time. A live-coding talk that should run in a terminal tool no longer silently becomes a slide deck.

Structured style selection + model registry — Phase 2 style strategy now runs as an ordered process: elicit what the speaker optimizes for (cost, speed, quality, build-editability), narrow the model roster to a priority-driven shortlist with model_registry.py --shortlist, propose styles, then render a style × model × format grid into a structured style-explore/ directory with an index.md contact sheet (generate-illustrations.py --style-explore) for a visual pick. The model roster moved into a single source of truth, model_registry.py — a structured registry with vendor aliases (so "nano-banana" resolves to the canonical Gemini id instead of being dropped on refresh), per-model attributes, and a deterministic --check-freshness precheck that SKILL.md Step 2 now runs first and reports, closing the "freshness check never ran" gap. The roster is a seed cache, not an allowlist: rendering accepts any id from a supported vendor family, and a web-discovered model can be injected into the shortlist for one talk via --add without a code edit.

What's New (0.18.0)

Cross-vendor image generation + model-freshness check — generate-illustrations.py now dispatches by model-name prefix to three vendor families: Google's gemini-* / nano-banana-* (generateContent), Google's imagen-* (:predict), and OpenAI's gpt-image-* (/images/generations and multipart /images/edits). COMPARE_MODELS refreshed to current flagships including gpt-image-2, imagen-4.0-ultra-generate-001, gemini-3.1-flash-image-preview, and nano-banana-pro-preview. New SKILL.md Step 2 web-searches the model landscape before any image generation runs and proposes re-running --compare if a newer flagship has shipped since the outline's **Model:** was last set — closes the months-long gap between picking a model in Phase 2 and actually generating images in Phase 5.

Talk timer for timemytalk.app — New generate-talk-timings.py parses the outline's pacing summary into MM:SS Chapter format for the timemytalk.app delivery timer. Supports --qa flag, sub-minute resolution, and automatic subdivision of long acts. Phase 6 publishing docs updated.

Keynote compatibility rules — Slide generation rules now document three python-pptx gotchas that cause Keynote to reject generated .pptx files: use rectangles not connectors for decorative lines, avoid create-then-remove shape patterns, keep shape IDs contiguous.

Shownotes publishing destination — Agents can now resolve published shownotes from publishing_process.shownotes_site in the speaker profile instead of searching the web. Resources-gathering rules document the read path.

Test suite and CI — comprehensive pytest coverage runs on every push and PR via GitHub Actions with ffmpeg, LibreOffice, and Tesseract-backed source lanes.

See CHANGELOG.md for full history.

How It Works

The toolkit is built on eleven skills connected by a shared rhetoric vault — a directory of structured knowledge about how you present.

VAULT
                 (shared data)
                 +-----------+
  Vault skills   | summary   |        Creator skills
  (analysis) --> | design    | <--  (generation)
                 | spec      |
                 | profile   |
                 +-----------+

Vault skills (analysis):

• vault-ingress parses recorded talks from transcripts, native decks, PDFs, or video and extracts rhetoric patterns across 14 dimensions — opening hooks, humor style, audience interaction, slide design, pacing, transitions, verbal signatures, and more. Before scoring, deterministic catalog and source-identity gates verify the evidence; video-derived slide claims require a provenance-bound, manually verified slide-region artifact. Recoverable queue leases and validated returns keep interrupted or stale batches from corrupting the vault.
• vault-clarification runs interactive sessions to validate findings and capture deliberate intent.
• vault-profile generates a schema-v5 speaker profile with source-exact opportunity rows, a self-contained policy stamp, and independently gated classifications after enough talks are analyzed.

Creator skills (generation):

• presentation-creator develops the argument, narrative, outline, and speaker notes in your documented voice. Intent, architecture, content, and revision stay together; approved deck and publishing work hand off to focused skills.
• presentation-builder builds or edits a PowerPoint or presenterm deck and exports existing decks. It reads engine-specific instructions only for the chosen action. Exporting a deck does not start an authoring interview or require publishing credentials.
• presentation-publisher curates resources, coordinates QR codes and short links, prepares delivery, and runs your configured publishing workflow. It invokes the builder for exports and shownotes-publisher for Jekyll page publication.
• cfp-writer writes conference submissions and maintains the sessions catalog of approved titles, abstracts, outlines, and Program Committee notes. CFPs need no slide outline or deck setup.
• illustrations owns the deck illustration strategy, generation, build chains, and YouTube thumbnails. Invoked by presentation-creator for strategy and presentation-builder for deck application. Thumbnail requests enter this skill directly.
• shownotes-publisher creates a downloadable Agent Skill containing each talk's substance and writes talk pages into a Jekyll-based shownotes site (e.g., speaking.jbaru.ch). Encodes the custom parser's format contract so authored content actually renders: abstract is one paragraph, video field absent = "coming soon" badge, slides/video URLs must be markdown links, no frontmatter title, etc. Uses the delivery-specific rhetoric analysis, reconciled with notes, demos, and transcripts, to explain the thesis, argument, example roles, and caveats. Audience agents can summarize the talk and answer questions from the skill without retrieving a transcript. Publishes _skills/{talk-page-stem}/SKILL.md with the page through a PR and verifies the download. Runs before or after delivery; video-only updates preserve existing skills.
• screencast-recorder verifies a recorded screen sequence against its approved storyboard — route and data revision, content framing and label readability at delivery size, deliberate pans, the pointer landing on what it clicks, clip-to-clip continuity, and whether each visual proof happens while its phrase is actually spoken. Verification only: it does not record. The unchecked pixel axis reports unverified, never pass.
• screencast-editor turns a Camtasia for Mac recording (screen, camera and mic in one take) into a speaker-first video. It plans cuts between sentences from Camtasia's own word timings, zooms the screen evidence clear of the presenter inset, audits every framing against the pointer path recorded in the .trec, generates the Camtasia project, replaces the dynamic-caption words with a corrected transcript while keeping Camtasia's onsets, and times YouTube chapters from the captions. It composes the thumbnail from exact frames of the take with the illustrations skill's thumbnail script.

The vault skills never run simultaneously with the creator skills. You build the vault first (once, then incrementally), then use the creator whenever you need a new talk. The vault grows over time as you parse more talks, and the creator automatically picks up new patterns.

Installation

tessl install jbaruch/speaker-toolkit

Getting Started

Phase 1: Build Your Vault

Each talk needs at least one usable source:

• a local transcript, or a video from which ingress can acquire one;
• authored slides as a .pptx (preferred), local PDF, or Google Drive PDF; or
• a delivery video for observations that genuinely require delivered context.

Organize talk metadata as .md shownotes files in a directory and declare every source that actually exists. Video is useful but is not a universal eligibility requirement; ingress records source-limited outcomes as not_evaluable instead of inventing evidence from an unavailable channel.

Then run:

parse my talks

The vault skill will:

1. Check ~/.claude/rhetoric-knowledge-vault/ (or ask for a custom location on first run)
2. Scan for talks and .pptx files
3. Process talks in parallel batches of 5
4. Extract rhetoric patterns across 14 dimensions
5. Score each talk against the 83 observable Presentation Patterns entries using source-located, channel-permitted evidence
6. Build a running narrative summary and slide design spec
7. Run an interactive clarification session to validate findings and capture your intent
8. Generate a schema-v5 speaker profile with auditable opportunities and automatic, per-domain classification (after 10+ talks)

Phase 2: Create Presentations

Once the vault exists, invoke the creator:

create a presentation about [topic] for [conference]

The creator will:

1. Load the speaker context needed for the current task
2. Walk you through intent distillation (purpose, audience, constraints)
3. Jointly select rhetorical instruments, using the available schema-v5 mastery history for the four tiers or a flat current-taxonomy strategy when that domain is unavailable
4. Write a section-by-section outline with speaker notes in your voice
5. Run guardrail checks (slide budget, Act 1 ratio, profanity, branding, pattern-based antipattern scan)
6. Hand the approved outline to presentation-builder for a PowerPoint or presenterm deck
7. Hand the finished deck to presentation-publisher when publishing is requested

You approve metadata, narrative, outline, and slides before their dependent stages. The skill brings the rhetoric knowledge; you bring the topic expertise.

Start Directly at the Task You Need

The four authoring/delivery entry points have a 1,500-token budget each. A shared runtime resolver verifies the configured interpreter and database generation; each action then reads only its required context. A compact, phase-filtered pattern menu supplies the workflow owner and opens detailed patterns on demand without changing catalog history. Standalone exports need no complete outline, rhetoric summary, image keys, or shownotes setup. An outline migration returns to the creator for a bounded repair.

Architecture

Speaker Neutrality

All skills are generic — they work for any speaker. All personalization lives in the vault:

The vault lives at ~/.claude/rhetoric-knowledge-vault/ by default. If you prefer a different location (e.g., Google Drive for backup), the skill creates a symlink from the canonical path to your chosen directory. If you don't have a vault yet, the skill creates it from scratch on first run.

The Vault Directory

The vault lives at ~/.claude/rhetoric-knowledge-vault/ (or a symlink to a custom location). It contains:

rhetoric-knowledge-vault/
+-- tracking-database.json      # Source of truth: all talks, status, config
+-- rhetoric-style-summary.md   # Narrative analysis across all rhetoric dimensions
+-- slide-design-spec.md        # Visual design rules (fonts, colors, layout taxonomy)
+-- speaker-profile.json        # Machine-readable bridge to the creator
+-- sessions-catalog.md         # Submission-ready titles, abstracts, outlines
+-- analyses/                   # Per-talk rhetoric analysis + pattern scoring
+-- transcripts/                # Downloaded YouTube transcripts
+-- slides/                     # Downloaded slide PDFs

rhetoric-style-summary.md is the constitution — rich prose covering presentation modes, opening patterns, humor techniques, audience interaction styles, closing patterns, verbal signatures, persuasion techniques, and more. It grows every time you parse new talks.

speaker-profile.json is the structured specification that the creator reads at runtime. It contains presentation modes with quantitative thresholds, instrument catalogs, guardrail rules, pacing data, design rules, the publishing workflow, and a pattern_profile with exact positive/negative occurrence rows, per-pattern denominators, source cohort provenance, exhaustive classifications, and independent availability by domain. Schema v5 uses the bundled speaker-toolkit-default@1 policy automatically and embeds the full policy plus its semantic digest. An optional pattern-classification-policy.json overrides it only when the file passes strict validation. Schema-v4 profiles remain readable as occurrence-only history.

slide-design-spec.md captures visual design rules extracted from both PDF inspection and programmatic .pptx analysis: background colors, typography, footer specs, shape vocabulary, and template layout catalog.

Handoff Mechanism

The skills communicate exclusively through the vault files plus per-talk artifacts (outline.yaml, _talks/*.md). When the vault updates (new talks parsed), it regenerates the speaker profile. When a downstream skill runs, it reads the latest vault state and the talk's spec. A freshness check warns if the profile is stale.

Vault skills (analysis)            Downstream skills (generation + publish)
=======================            =======================================
vault-ingress      ----+
vault-clarification    +-->  rhetoric-style-summary.md  -->  presentation-creator
vault-profile      ----+      slide-design-spec.md           illustrations
                              speaker-profile.json            (via outline.yaml)
                              (incl. pattern_profile)

                                                              presentation-creator
                                                              produces outline.yaml
                                                                      |
                                                              presentation-builder
                                                              builds/exports decks
                                                                      |
                                                              presentation-publisher
                                                              coordinates delivery
                                                                      |
                                                              shownotes-publisher
                                                              reads outline.yaml +
                                                              resources.json, writes
                                                              _talks/<file>.md

Rules

The plugin ships persistent rules (auto-loaded by the agent at runtime via .tessl-plugin/plugin.json → rules). Keep this table in sync with the manifest:

Vault Skills Details

The vault skills (vault-ingress, vault-clarification, vault-profile) share the analysis triggers and processing pipeline below.

Triggers

• parse my talks / run the rhetoric analyzer
• analyze my presentation style
• how many talks have been processed
• update the rhetoric knowledge base / check rhetoric vault status
• process remaining talks for style patterns
• generate my speaker profile / update speaker profile

14 Rhetoric Dimensions

Each talk is analyzed across:

1. Opening pattern — hook type, first impression strategy
2. Narrative structure — arc, throughline, act breakdown
3. Humor & wit — technique, register, frequency, placement
4. Audience interaction — polls, questions, direct address
5. Transition techniques — verbal bridges, visual transitions
6. Closing pattern — callback, CTA, summary, emotional note
7. Verbal signatures — recurring phrases, characteristic expressions
8. Slide-to-speech relationship — density, reading vs. springboarding
9. Persuasion techniques — argument structure, credibility building
10. Cultural & pop-culture references — what's referenced and how
11. Technical content delivery — simplification, progressive revelation
12. Pacing clues — section lengths, density, speed variation
13. Slide design patterns — per-slide visual classification, typography, shapes, illustration style
14. Reflection — critical assessment of what could be improved

Each dimension is cross-referenced with the Presentation Patterns taxonomy — the analysis notes which named patterns and antipatterns are detected per talk.

Processing Pipeline

• Talks are processed in parallel batches of 5 subagents
• Transcripts use YouTube captions first, with local Whisper audio transcription as fallback; source timing is retained in a hash-bound sidecar when available
• Slides come from native PPTX files, local or Drive-acquired static PDFs, or provenance-gated video-derived artifacts; each source keeps its own evidence capabilities instead of aliasing one format to another. Every manifest PDF is generation-bound before persistence, including context-only artifacts, and a configured symlinked vault root does not weaken descendant path checks
• Preserved source recordings are inspected through a bounded, exact-generation probe before they contribute local-media digest or duration evidence to transcript validation, authorize delivery-video citations, support video-derived slide provenance, or participate in freshness checks. If a recording cannot be verified, only source-video capability is removed; independently verified transcript, PDF, and PPTX evidence remains
• Each talk is scored against the taxonomy's 83 observable entries (64 patterns + 19 antipatterns), with source-located evidence restricted to the artifact channels each entry permits
• Each batch updates the summary, per-talk analysis files, and triggers profile regeneration
• An interactive clarification session resolves ambiguities and captures confirmed intent

Prerequisites

• Python 3.10+ at the vault's configured python_path, with core PyYAML; pypdf + exactly psutil==7.2.2 for supervised PDF evidence; and python-pptx + the same exact psutil version for resource-supervised native-deck evidence. Preserved source-video evidence uses the separate source-video runtime lane with exactly psutil==7.2.2 plus ffprobe
• Lane-specific runtime: importable gdown for Google Drive acquisition, youtube-transcript-api for captions, exactly yt-dlp==2026.8.19 for provider probing/audio download, pdftoppm for rendered-PDF inspection, Pillow + imagehash + ffmpeg/ffprobe for video extraction, and optional mlx-whisper for local Whisper fallback
• Markdown-authored decks (Slidev, presenterm, Marp, reveal-md) render through that deck's own tool, one optional lane per flavor — presenterm + weasyprint, slidev, marp, or reveal-md
• Talks with at least one reachable transcript, slide, or video source

Installed plugin bundles do not include pyproject.toml; README and the vault-ingress skill are the runtime authority. After python_path is bootstrapped, run its stdlib-only check-runtime.py probe. Optional lane dependency absence is isolated: missing pypdf cannot erase transcript/PPTX capability, and missing python-pptx cannot erase transcript/PDF capability. Dependency initializer exceptions, native crashes, timeouts, and invalid child results remain lane-local and carry machine-readable failure reasons. The checker emits report schema v3; each lane's required_module_versions declares exact Python pins, while required_command_versions declares the youtube-download lane's yt-dlp pin. An incompatible installed version is unavailable rather than silently accepted. The yt-dlp probe and every ingress caller resolve the configured interpreter's console script before falling back to PATH.

Generation & Publishing Skills Details

Choose the skill for the requested task using the task routing table. presentation-creator owns talk authoring and outline repair; presentation-builder owns deck builds, edits, and exports; presentation-publisher coordinates publishing and delivery; cfp-writer owns conference submissions and the sessions catalog. illustrations and shownotes-publisher accept direct requests and typed Skill(...) handoffs from those workflows.

Triggers (presentation-creator)

• create a presentation about [topic]
• build a talk for [conference]
• adapt my [talk name] for [new venue]

Triggers (presentation-builder, presentation-publisher, cfp-writer)

• build slides from this outline / edit this deck / export this deck to PDF → presentation-builder
• publish this talk / replace the QR code / prepare this talk for delivery → presentation-publisher
• write a CFP for [conference] / update the sessions catalog → cfp-writer

Triggers (shownotes-publisher)

• publish shownotes / add talk to shownotes / shownotes for [talk]
• update shownotes with the recording (once the video URL lands)
• Receives a handoff from presentation-publisher when the configured publishing workflow includes Jekyll shownotes

Authoring and Delivery Workflow

Standalone requests enter their owning skill without running earlier authoring stages. Recording updates enter shownotes-publisher; thumbnails enter illustrations.

Guardrail System (10 checks + pattern taxonomy scan)

1. Slide budget — per-duration max from the profile
2. Act 1 ratio — problem section balance limits
3. Conference branding — footer, logos, stale names
4. Profanity audit — register consistency, on-slide profanity flagging
5. Data attribution — source visibility on data slides
6. Time-sensitive content — expired dates, version numbers
7. Closing completeness — summary + CTA + social
8. Modular cut lines — present for shorter/longer adaptation
9. Anti-pattern flags — current-outline taxonomy findings plus independently sourced non-pattern guardrails
   • 9A: Profile-based non-pattern recurring issues (source_lane: "non_pattern")
   • 9B: Taxonomy-based antipattern scan — [CONTEXTUAL] always; [RECURRING] only when the profile's antipattern-recurrence domain is available
10. Illustration coverage — format tags, EXCEPTION justifications, style anchor references, prompt quality (when illustration strategy is defined; [SKIP] otherwise)

Presentation Patterns Taxonomy

The creator includes a structured reference taxonomy of 113 presentation patterns and antipatterns from Presentation Patterns (Ford, McCullough, Schutta 2013) supplemented by Presentation Zen (Reynolds, 2nd ed. 2012), Resonate (Duarte 2010), Make It Stick (Brown, Roediger, McDaniel 2014), The Whole Brain Business Book (Herrmann, 2nd ed. 2015), and a small set of vault-derived patterns observed across the corpus (delayed-self-introduction, three-part-close, progressive-reveal, anti-sell, meme-as-argument, second-look), organized by presentation lifecycle:

• Prepare (24): Know Your Audience, Narrative Arc, Triad, Talklet, Brain Breaks, Takahashi, Cave Painting, Opening PUNCH, Walk-Around, and more
• Build (51): Foreshadowing, Bookends, Defy Defaults, Vacation Photos, Traveling Highlights, Emergence, Sparkline, Call to Adventure, Call to Action, New Bliss, S.T.A.R. Moment, Three-Part Close, Progressive Reveal, Meme as Argument, Guess First, Retrieval Beat, Second Look, and more
• Deliver (38): Carnegie Hall, Breathing Room, Echo Chamber, Seeding the First Question, Screen Blackout, Delayed Self-Introduction, Anti-Sell, Flyover, Spaced Follow-Up, The Nodding Room, and more

Of the 113 entries, 83 are observable (64 patterns + 19 antipatterns): directly detectable through their declared transcript, slide, or video locator channels, with allowlisted source metadata only as corroboration. The other 30 are unobservable (21 patterns + 9 antipatterns): pre-event logistics, hidden authoring/provenance processes, physical stage behaviors, post-event follow-up, and external systems the current artifacts cannot prove.

All 83 observable entries explicitly declare positive, strong, and absence source gates. Only 16 currently permit an undetected/absence outcome: 11 from a fully inspected, separately declared rendered PDF and 5 from a fully inspected transcript. The other 65 are positive-only and fail closed to not_evaluable on non-detection. Sampled, deduplicated video-extracted slide PDFs remain valid positive evidence but are never absence-complete; native decks, generic delivery-video roles, and comparison groups also remain outside absence denominators until versioned capability/alignment receipts exist.

How it integrates:

Special Workflows

• Adapting existing talks — pre-fills spec from vault analysis, auto-generates adaptation checklist
• CFP abstract writing — cfp-writer produces title, abstract, takeaways, and bio without a slide outline
• Co-presented talks — role split, footer adaptation, per-speaker voice in notes

Summary-Only Mode

If the speaker profile doesn't exist yet (fewer than 10 talks parsed), the creator runs in summary-only mode — drawing instruments from the rhetoric summary prose and using default guardrail thresholds. The pattern taxonomy still works as a flat relevant list without usage or novelty claims. The selected builder or publisher action asks for missing template or publishing details; delivery preparation still includes the go-live checklist.

Prerequisites

For the Vault Skills (vault-ingress, vault-clarification, vault-profile)

• Configured Python 3.10+ environment with PyYAML; add pypdf, python-pptx, exactly psutil==7.2.2, gdown, and youtube-transcript-api for the source lanes actually used
• yt-dlp, pdftoppm, ffmpeg, and ffprobe for the provider/download, rendered-PDF, and video lanes that require them; optional mlx-whisper for local Whisper fallback
• The authoring tool of any markdown deck you want rendered as slide evidence: presenterm + weasyprint, slidev, marp, or reveal-md
• Talks with at least one usable transcript, slide, or delivery-video source

For Talk Authoring and CFPs

• The vault's configured Python environment and the speaker context required by the selected task
• Deck setup, illustration credentials, and publishing services are selected only for actions that use them

For PowerPoint Builds, Edits, and Illustration Application

• Microsoft PowerPoint with VBA macros — the deck engine: slide generation, structural edits, backgrounds, and QR drive macros in the real app (macOS only). One-time DeckOps.pptm macro setup: skills/presentation-builder/references/deck-editing-setup.md. Speaker notes need PowerPoint and Automation consent but no macro.
• python-pptx (extraction reads + the illustration scrim/title apply pass)
• A PowerPoint template (the vault captures the path; a generic template works too)

Presenterm builds use presenterm instead of the PowerPoint lane. Export-only requests use the selected deck engine's export requirements; see presentation-builder/references/export.md.

For the Shownotes Publisher Skill

• A Jekyll-based shownotes site cloned locally (~/Projects/shownotes by default). The site must use the custom markdown parser plugin this skill targets; see skills/shownotes-publisher/references/parser-contract.md
• bundle exec jekyll build available locally for the Step 8 validation
• gh CLI for the branch + PR publish flow (and for direct push under the ci-safety Content-Only Direct-Push Carve-Out when the target repo has it wired)

File Reference

speaker-toolkit/
+-- .tessl-plugin/plugin.json
+-- README.md
+-- CHANGELOG.md
+-- pyproject.toml                            # Dependencies + pytest config
+-- tests/                                    # Deterministic pytest unit and integration coverage
|   +-- conftest.py                           # Script import helpers + PPTX fixtures
|   +-- test_*.py                             # Runtime, contract, docs, and packaging regressions
+-- .github/workflows/
|   +-- tests.yml                             # pytest on push/PR (ffmpeg + LibreOffice)
|   +-- publish.yml                    # Tessl skill review + publish
+-- skills/
    +-- vault-ingress/
    |   +-- SKILL.md                          # Main vault workflow (9 steps)
    |   +-- scripts/
    |   |   +-- artifact_metadata.py          # shared bounded metadata + cloud/reparse policy
    |   |   +-- pdf_evidence.py               # supervised exact-generation PDF evidence
    |   |   +-- video_evidence.py             # supervised exact-generation source-video evidence
    |   |   +-- pptx-extraction.py            # supervised PPTX extraction + bounded discovery
    |   |   +-- video-slide-extraction.py     # Video-to-slides via ffmpeg + perceptual dedup
    |   |   +-- vtt-cleanup.py                # WebVTT to plain text
    |   |   +-- batch-download-videos.py      # Parallel video download for batch processing
    |   +-- references/
    |       +-- bootstrap-and-preflight.md     # Runtime, discovery, migration, and preflight contract
    |       +-- queue-selection.md             # Deterministic selection, claim, and lease contract
    |       +-- batch-persistence.md           # Batch validation, atomic persistence, and rendering order
    |       +-- pptx-followup.md               # Native-deck extraction and catalog follow-up
    |       +-- clarification-handoff.md       # Post-processing clarification handoff
    |       +-- source-identity-preflight.md   # Source ownership, artifact authority, and repair routing
    |       +-- rhetoric-dimensions.md        # 14 analysis dimensions + pattern cross-refs
    |       +-- schemas-db.md                 # DB, subagent, and extraction output schemas
    |       +-- video-slide-extraction.md     # Layout heuristics, tuning tables, limitations
    |       +-- processing-rules.md           # Language policy, pattern migration logic
    +-- vault-clarification/
    |   +-- SKILL.md                          # Validate observations and capture speaker intent
    +-- vault-profile/
    |   +-- SKILL.md                          # Machine-readable speaker profile workflow
    |   +-- references/
    |       +-- profile-construction-rules.md  # Cohort, merge, trend, and diff authority
    +-- presentation-creator/
    |   +-- SKILL.md                          # Talk authoring, outline repair, and handoffs
    |   +-- scripts/
    |   |   +-- pattern-menu.py               # Compact phase-filtered taxonomy discovery
    |   |   +-- read-task-profile.py          # Selected action's profile fields
    |   |   +-- generate-qr.py                # QR generation + bg-color match (insert via InsertQR)
    |   |   +-- extract-resources.py          # Resource link extraction from outlines
    |   |   +-- guardrail-check.py            # Outline guardrail validation
    |   |   +-- export-pdf.py                 # Export deck to PDF (PowerPoint or LibreOffice)
    |   |   +-- validate-deckops.py           # Validate a deck op sequence before BuildDeck (tested)
    |   |   +-- build-deck.sh                  # Wrapper for BuildDeck (whole-deck creation via real PowerPoint)
    |   |   +-- build-deck.applescript         # AppleScript driver for BuildDeck (reads ops as UTF-8)
    |   |   +-- RunDeckOps.bas                 # VBA: BuildDeck + trim/reorder/import/bg/placeholder/QR via real PowerPoint
    |   |   +-- run-deck-ops.sh                # Wrapper for RunDeckOps (staging + move into place)
    |   |   +-- run-deck-ops.applescript       # AppleScript driver for RunDeckOps
    |   |   +-- deckops-doctor.py              # Is the deck layer set up, open, and current? (tested)
    |   |   +-- deckops-version.applescript    # Read-only probe: which macro build is loaded
    |   |   +-- smoke-test-ops.txt             # 3-slide op sequence for the setup smoke test
    |   |   +-- deckops-smoke-test.sh          # Build that sequence against the template and report where it landed
    |   |   +-- make-bg-slide.sh               # Wrapper for MakeBgImageSlide (illustration -> bg slide)
    |   |   +-- make-bg-slide.applescript      # AppleScript driver for MakeBgImageSlide
    |   |   +-- make-placeholder-slide.sh       # Wrapper for MakePlaceholderSlide (yellow [PLACEHOLDER] slide)
    |   |   +-- make-placeholder-slide.applescript # AppleScript driver for MakePlaceholderSlide
    |   |   +-- apply-backgrounds.sh           # Wrapper for ApplyBackgrounds (bulk FULL-slide bg fills)
    |   |   +-- apply-backgrounds.applescript  # AppleScript driver for ApplyBackgrounds
    |   |   +-- backgrounds-manifest-to-spec.py # Manifest JSON -> ApplyBackgrounds spec (tested)
    |   |   +-- inject-notes.sh                # Wrapper for the notes driver (notes via real PowerPoint)
    |   |   +-- inject-notes.applescript       # Notes driver: sets each note via AppleScript, Unicode intact
    |   |   +-- notes-to-packed.py             # Notes JSON -> notes driver wire format (tested)
    |   |   +-- atomic-replace.py              # Exact-target rename that refuses directories (tested)
    |   |   +-- insert-qr.sh                    # Wrapper for InsertQR (QR PNG bottom-right via real PowerPoint)
    |   |   +-- insert-qr.applescript           # AppleScript driver for InsertQR
    |   +-- references/
    |       +-- phase0-intake.md through phase4-guardrails.md # Authoring phase details
    |       +-- patterns/                     # Presentation Patterns taxonomy (113 entries)
    |           +-- _index.md                 # Master index, phase mapping, dimension lookup
    |           +-- prepare/                  # 20 patterns + 4 antipatterns
    |           +-- build/                    # 41 patterns + 10 antipatterns
    |           +-- deliver/                  # 24 patterns + 14 antipatterns
    +-- presentation-builder/
    |   +-- SKILL.md                          # Build, edit, export action router
    |   +-- references/                       # PowerPoint, presenterm, export, setup
    +-- presentation-publisher/
    |   +-- SKILL.md                          # Publishing and single-action router
    |   +-- references/                       # Resources, QR, shownotes, delivery
    +-- cfp-writer/
    |   +-- SKILL.md                          # CFP and sessions-catalog router
    |   +-- references/                       # Submissions and catalog contract
    +-- illustrations/
    |   +-- SKILL.md                          # Illustration strategy, generation, application, thumbnails
    |   +-- scripts/
    |   |   +-- model_registry.py             # Model roster, aliases, attributes; --check-freshness + --shortlist
    |   |   +-- generate-illustrations.py     # Illustration generator + model comparison + style exploration + builds
    |   |   +-- apply-illustrations-to-deck.py # Swap into deck, reposition title, position IMG+TXT
    |   |   +-- suggest-scrim-color.py        # Sample deck-tuned scrim color from illustrations
    |   |   +-- generate-thumbnail.py         # YouTube thumbnail via Gemini composition
    |   +-- references/
    |       +-- strategy.md                   # Phase 2 D#11 — priorities, model shortlist, style proposals, exploration render
    |       +-- generation.md                 # Setup, edit/fix workflow, format vocabulary, apply-to-deck
    |       +-- builds.md                     # Backwards-chained build generation + deck insertion
    |       +-- thumbnails.md                 # Thumbnail composition + slide selection
    |       +-- style-explore-candidates-schema.md # candidates.json contract for --style-explore
    |       +-- title-placement.md            # Outline schema + scripts for Safe-zone title placement
    +-- shownotes-publisher/
    |   +-- SKILL.md                          # Jekyll shownotes and talk skills; recording updates
    |   +-- scripts/
    |   |   +-- place-thumbnail.py            # Validate or convert the generated image to the site's PNG
    |   +-- references/
    |       +-- parser-contract.md            # `_plugins/markdown_parser.rb` capture rules per extracted_* field
    |       +-- template-conditionals.md      # `talk.html` conditional rendering per extracted field
    |       +-- common-mistakes.md            # 13 failure modes (1, 1b, 1c, 2-11) with right-way fixes
    |       +-- thumbnails.md                 # Generation handoff and convention-path placement
    +-- screencast-recorder/
    |   +-- SKILL.md                          # Verify a recorded sequence against its storyboard
    +-- screencast-editor/
        +-- SKILL.md                          # Camtasia edit, captions, and chapters

License

MIT