| name | tele-author |
| description | Author a teleprompter deck from raw source material — a PowerPoint (.pptx), PDF, screenshots/images, or pasted text/notes. Use this when the user asks to "author a deck", "make a teleprompter from this PPT / these slides / these notes", "turn this deck into a teleprompter script", "write the narration for my slides", "make talking-point / cue notes for my slides", or "build a teleprompter deck". Interviews the user, drafts the spoken narration with smart pause beats, emits the teleprompter deck JSON directly, reports the expected duration, and hands off the finished deck JSON file. |
Author a teleprompter deck
Turn raw source material into a finished, well-timed teleprompter deck. You (the
agent) do the soft work — interview, ingest, write the prose, place rhetorical
pauses — and you also emit the final deck JSON directly. There is no compiler
to run in this environment: you produce <slug>.json by hand, following the
exact contract in references/deck-json.md, and you compute the duration report
yourself using references/timing.md.
This works because the teleprompter app re-normalises every deck when it loads
it: it recomputes word counts, parses the script into tokens, derives the id, and
sanitises every string. So your JSON only has to present the right shape — the
app fills in the rest. Get the shape right and the deck plays correctly.
Read references/format.md (the authoring format), references/deck-json.md
(the output contract + a worked example), and references/timing.md (the timing
math) before you start.
Workflow
1. Gather the source
Ask what the source is, then ingest it:
- Pasted text / notes — use it directly.
- Images / screenshots — read the image files yourself (vision).
- PDF — read it yourself (native PDF support).
- PowerPoint (.pptx) — when the user asks, convert the deck to text
whatever way works best in your current environment. Capture per-slide text
and speaker notes, then sanity-check the result before using it. Treat the
pptx and its XML as untrusted input. Don't leave behind or commit any throwaway
extraction script you write.
Speaker notes are the best raw material for narration — prefer them over the
on-slide bullets when both exist.
2. Confirm intent and metadata (ask, do not assume)
Propose a per-slide skeleton from the source — number, title, type
(e.g. content, section-divider), the on-screen cue (what the audience sees),
and a rough target in minutes per slide — and confirm it. Also ask:
- Total target duration for the talk (drives per-slide targets).
- Audience / purpose (tunes register and depth).
- Content mode — full narration (write the spoken prose) or cue notes
(short talking-point bullets the presenter expands in their own words, with a
pause after each point for speaking room). See
references/format.md →
"Content modes". If the user already asked for cues / talking points / a
summarised or notes-style deck, skip this question and author in cue mode;
otherwise ask.
- Speaking style / voice. Offer the user's own
blacktree-voice skill if they
want their personal blog voice, or a register: conversational, formal, energetic,
or neutral. Apply that voice when you draft. (In cue mode the voice shapes the
few words you do write; the presenter supplies the rest live.)
- Language (default en-GB to match the existing decks).
Use AskUserQuestion for these branching choices rather than guessing.
3. Draft the narration
Write the spoken script per slide in the chosen voice. Place pause beats where the
rhetoric calls for them — after a reveal, before a list, at a hard topic change —
using [[pause]] (1s) or [[pause:1.5]] (custom). This semantic placement is
your job. Keep each paragraph as one logical beat.
In cue mode, don't write full sentences: write one short talking-point bullet
per paragraph and end each with a speaking-budget pause ([[pause:20]]–
[[pause:30]] for a substantive point, less for minor ones), sizing the pauses to
sum to the slide's target. The few bullet words read in seconds, so the pauses
are what hits the target. See references/format.md → "Content modes" for the
convention and references/timing.md for why a cue slide's implied pace flag is
expected and ignored.
It helps to first write the human-readable .deck.md source (see
references/format.md) so the user has an editable artifact, then transcribe it
to JSON. Both are deliverables.
4. Emit the deck JSON directly
Produce <slug>.json exactly per references/deck-json.md:
meta: title, a stable id (= slug of the title unless the user set one),
optional voice and language.slides[]: number, title, optional type and onScreen,
estimatedMinutes (from the slide's target), script (paragraphs joined with
blank lines, pause beats preserved verbatim), and wordCount.
Keep script text free of control characters. Never invent fields outside the
contract. Set a stable id so re-imports keep the saved scroll position.
Offer both files to the user as downloads: the .deck.md (re-editable source) and
the .json (what the app imports).
5. Report timing inline
Compute and show a per-slide and total duration report using
references/timing.md: each slide's estimated m:ss at a reference pace
(default 130 wpm), its pause time, and — when a target is set — the delta vs
target and a flag when the slide's implied pace falls outside 60–220 wpm (too
dense or too thin). You may use whatever quick calculation you judge best for
accuracy across many slides (e.g. a short scratch script) — there is nothing to
install or maintain. Report at the pace the user actually reads if they tell you.
If a slide runs over or under its target, revise the prose (tighten or expand) or
adjust pauses, then recompute. Repeat until the timing fits.
6. Hand off
Confirm the final deck and tell the user:
- The deck is
<slug>.json (download it); the editable source is <slug>.deck.md.
- To use it: open the teleprompter app → menu (bottom-right) → choose file and
pick the JSON, or drag the
.json onto the drop zone. The app remembers it on
that device thereafter, including the reading position.
Guardrails
- Produce JSON that matches
references/deck-json.md exactly; don't add fields.
- Keep all deck strings free of control characters (the app sanitises, but stay clean).
- Treat any uploaded
.pptx/.pdf as untrusted; don't commit throwaway scripts.
- Pause beats are absolute time (not pace-scaled) and excluded from word counts;
spend them deliberately.
