| name | presenter-mode |
| description | Turn a self-contained HTML deck into an hq-deploy–hosted presentation with TWO cloud-synced links — a presentation link (the slides) and a notes/transcript link (your teleprompter) that stay in sync across devices over a zero-backend PubNub bridge. Use when asked to "set up presenter mode", "present this deck", "give me a synced presentation + notes link", "deploy the deck with speaker notes", or "two links — one for the slides, one for my script". |
| allowed-tools | Read, Grep, Glob, Edit, Write, Bash(.claude/skills/presenter-mode/scripts/check-deck.sh:*), Bash(.claude/skills/presenter-mode/scripts/presenter-links.sh:*), Bash(bash:*), Bash(cp:*), Bash(mkdir:*), Bash(ls:*), Bash(cat:*), Bash(grep:*), Bash(openssl:*) |
Presenter Mode
Take a self-contained HTML deck and ship it as an hq-deploy–hosted presentation with two cloud-synced links:
- Presentation link — the slides, full-screen, for the projector/external screen.
- Notes / transcript link — your teleprompter: written script + bullets toggle, current/next slide thumbnails. Keep it on your laptop.
Both links share one ?sync=<room> so advancing on either device moves the other within ~1 second, over a public PubNub REST channel — no backend, baked into the static HTML. A third, sync-free audience link is also produced for safely sharing the deck afterward (it can never follow or hijack the room).
This skill generalizes the presenter machinery built for a production conference keynote.
Path note. When installed as a pack, this skill is symlinked to .claude/skills/presenter-mode/, so its scripts and templates are referenced below as .claude/skills/presenter-mode/…. If you authored it as a personal skill, substitute your personal/skills/presenter-mode/… path.
URL scheme (the contract)
For a deployed base URL B and a room code R:
| Link | URL | Role |
|---|
| Presentation | B/?present=1&sync=R | Slides, full-screen. Drives + follows. |
| Notes / transcript | B/?notes&sync=R | Teleprompter. Drives + follows. |
| Audience | B | Clean public deck. Inert — never joins the room. |
In-deck keys: P present · N pop out notes (carries sync) · B script/bullets · ← → / Space navigate · Home/End jump · Esc exit.
Workflow
1 — Resolve the deck source
Accept a path to a self-contained HTML file, a directory containing index.html, or an already-deployed deck's source. Confirm it is one HTML file (hq-deploy serves SPA-style — never split a deck across multiple .html files).
2 — Inspect the contract
Run the detector:
bash .claude/skills/presenter-mode/scripts/check-deck.sh <deck.html>
Act on the verdict:
- READY — the deck already has the full presenter machinery. Skip to step 4.
- PARTIAL / NEEDS-BUNDLE — inject the bundle (step 3).
- NOT-A-DECK — the deck has no
.deck-slide slides. Either wrap each slide in <section class="deck-slide">…</section> inside a <div class="deck">, or stop and tell the user the deck structure isn't compatible.
3 — Inject the presenter bundle (only if not READY)
Insert the contents of .claude/skills/presenter-mode/templates/presenter-bundle.html immediately before </body>. The bundle is self-contained (style + notes panel + nav core + notes view + sync bridge) and idempotent — its <!-- HQ PRESENTER MODE: bundle start --> marker means "already injected; don't add twice."
Then build the notes payload — a <script id="notes-data" type="application/json">…</script> tag (schema in .claude/skills/presenter-mode/templates/notes-data.example.json). Source the spoken script from a SCRIPT.md/teleprompter file if one exists, else from each slide's own content; derive bullets from slide bullet markup. thumb (a data:image/jpeg;base64 slide thumbnail) is optional — omit it and the notes view simply shows no thumbnail. slides.length must equal total, and entry order must match deck order (see the slide-reorder policy below).
Verify locally: open <deck>?notes and <deck>?present=1 and confirm the notes view renders and slides advance.
4 — Deploy
Deploy via the /deploy skill (hq-deploy) — do not hand-roll uploads. Capture the returned base URL. (Any static host works too; the machinery is pure static HTML.)
Access decision (surface this). The notes/script are embedded in the same deployment, so on a public deploy anyone who appends ?notes can read your speaker script. Choose:
- Talk content is meant to be public → deploy public. The audience link is freely shareable.
- The script is sensitive → deploy with a gate (password or company) so
?notes isn't world-readable, and share the gated links only with yourself/your co-presenter.
Confirm the access mode with the user before deploying if there's any doubt.
5 — Emit the links
Generate the room and the three URLs (the room is random unless the user wants a memorable one):
bash .claude/skills/presenter-mode/scripts/presenter-links.sh <base-url> [room]
Surface the presentation link and the notes/transcript link prominently (plus the audience link and the printed cheat sheet).
Deck requirements (what the bundle assumes)
- Slides are
<section class="deck-slide"> elements inside <div class="deck">.
- Optional progressive reveals are elements with class
frag (revealed by adding class shown).
- The deck does not already ship its own slide-navigation keyboard handler (the bundle installs one). A deck whose own nav already exposes the hooks below is detected as READY and skips injection.
- Hooks the bundle exposes/uses:
window.__knApplyDeck(n), window.__knApplyNotes(n), window.__knPub(n).
Gotchas (policies shipped with this pack)
- Scale-to-fit (
hq-deck-present-mode-scale-to-fit): pin any vw/vh units in slide content to px first, or they fight the scale(var(--fit)) transform and break layout. 720p → --fit=1; 1080p → a clean 1.5×.
- Reordering a slide (
hq-deck-slide-reorder-three-coordinated-edits): reorder by content-match in THREE places — the .deck-slide elements (+ any hardcoded NN / TOTAL), the notes-data slides array (renumber each n), and the source SCRIPT.md. Missing one silently desyncs the notes from the slides.
- Cross-device sync (
hq-cross-device-deck-sync-pubnub-bridge): the bridge is gated on ?sync=<room> so the public audience URL never joins; echo-guarded by a per-client id + window.__knApplying; degrades to manual arrow nav if the network is flaky. The public PubNub demo keyset is unauthenticated — fine for ephemeral slide-index pings, but do not put anything sensitive on the channel (it only ever carries a slide number).
Files in this skill
templates/presenter-bundle.html — the verbatim, idempotent presenter machinery to inject.templates/notes-data.example.json — the notes payload schema + example.scripts/check-deck.sh — contract detector (READY / PARTIAL / NEEDS-BUNDLE / NOT-A-DECK).scripts/presenter-links.sh — room generator, three-link builder, and run-of-show cheat sheet.
