Slide deck
A deck states an argument with pictures. This skill gives you the mechanism and the judgment. The mechanism is a theme, layout archetypes, a deterministic build, a render pass and a rehearsal pass. The judgment is what each slide owes the next one, and what an academic talk is judged on.
All content lives in the user's own deck directory. This skill holds mechanism only.
The tool surface is <skill>/scripts/deck build|check|render|readiness|timing|handout|themes|init.
Python runs through uv. The launcher pins the dependencies.
How this skill works with the others
Four skills share this ground. Each one owns a different thing, and the boundaries are worth stating.
| skill | owns |
|---|---|
academic-writing |
The argument in the paper or thesis, and the constructs a talk must render: contribution types, the validity taxonomy, the citation discipline. |
human-writing |
The prose a person reads. Notes, README text and any explanatory writing in the deck should pass its scanner. |
asd-ste100 |
Text that a machine parses without a person to resolve ambiguity. Error messages, tool descriptions, and the instruction files of this skill. |
unslop |
Source code and web interfaces. |
diagrams |
A Mermaid source and the figure it renders to. It derives the renderer theme from this skill's theme.json, so a diagram cannot land in a deck in different colours. |
| this skill | The deck module, the theme, the layout, the speaker notes and the rehearsal passes. |
Two consequences follow.
The instruction files in this skill follow the asd-ste100 structural rules, because an
agent parses them. The sentences are short and active, each sentence carries one
instruction, and the files use no semicolons.
The talk's own words belong to the user. When a deck reads as machine-written, hand the
notes and the slide text to human-writing. When the argument is unclear, hand the
source document to academic-writing. This skill does not rewrite the user's argument.
Genre profile
Pick the genre before you write a spine. The genre fixes the spine, the slides that must land, the backup set, and the questions the room will ask.
| genre | reference |
|---|---|
| DSR or qualitative thesis defence (colloquium, viva, Disputation) | references/genre-dsr-defence.md |
| Empirical-CS or conference paper talk (method, baselines, ablations) | references/genre-empirical-cs-talk.md |
| Academic job talk (faculty or postdoc research presentation) | references/genre-academic-job-talk.md |
The three are not interchangeable. A defence is judged on abstraction, positioning and contribution. A paper talk is judged on beating a baseline. A job talk is judged on a research programme. If the genre is unclear, ask. A wrong genre produces a confidently wrong deck.
The academic layer
Read narrative.md first. It carries the craft that every talk shares. Then read the
files that sit under it for an academic talk.
| file | what it fixes |
|---|---|
academic-narrative.md |
The objects: a question at class level, the contribution type, the bounding register, the construct column, the four validities. |
evidence-on-slides.md |
How to show a number or a figure without overstating it. Access and colour. |
citing-on-slides.md |
Inline attribution, the single references slide, reproduced material. |
academic-register.md |
Person, tense and register in a spoken sentence. |
defence-readiness.md |
The five questions a reviewer answers against the argument. |
The constructs behind these files belong to academic-writing. Read its genre
references when the talk needs the underlying source. This skill renders them for a
spoken talk.
Workflow
Copy this checklist and track progress.
- [ ] 1. Brief fixed: audience, duration, language, and what the deck must achieve
- [ ] 2. Genre chosen and read
- [ ] 3. Theme derived from the source artifact, or `slate` when there is none
- [ ] 4. Spine written: sections, one assertion per slide, a time budget that sums
- [ ] 5. Deck module written, notes on every slide
- [ ] 6. build returns clean
- [ ] 7. check returns 0 errors. Fix or explain every warning.
- [ ] 8. render. Look at the contact sheet. Fix and build again.
- [ ] 9. timing. The budget sums, and every script fits its slot.
- [ ] 10. readiness. Answer the five questions. Fix and rebuild. (a defence)
- [ ] 11. handout. Rehearse from it, or give it to the examiners.
- [ ] 12. Backup slides written for the questions the talk will raise
Step 1. Fix the brief
Four facts change the whole design: the audience and their prior knowledge, the duration and whether questions are included, the language, and what the deck must achieve. If the request leaves a fact open, ask one batched round of numbered questions. Put the recommended option first. Do not infer the language from the source material. A German defence of an English thesis is normal.
When the user defers, proceed on named defaults and print them. references/narrative.md
section Ambiguity holds the question set. Record the duration as Deck(minutes=...).
The timing verb compares against it.
Step 2. Choose the genre
Read the genre profile. It fixes the spine, the slides that must land, the backup set and the questions the room will ask. A defence profile also carries the Kritikpunkte map.
Step 3. Scaffold and theme
scripts/deck themes # list built-in themes
scripts/deck init <name> --dir <where> [--theme x] # deck.py + Assets/
When the source material has figures, derive the theme from their palette. Read
references/theming.md for the order of preference and the contrast rules. A deck that
disagrees with its own embedded diagrams looks borrowed.
Step 4. Write the spine
Write the sections and the per-slide assertions before you write any slide. Read
references/narrative.md for the spine shape, the assertion-title rule, the
claim/evidence/bound rhythm and the words-per-minute budget. Read
references/academic-narrative.md for the academic objects. The assertions alone should
reconstruct the argument — the slide title, or the claim bar on a claim-first deck. If
they do not, the deck is a set of notes.
Step 5. Write the content
Edit deck.py. Reach for an archetype first. references/slide-recipes.md maps a
slide's job to a layout. It also gives you the primitives and the composition patterns
for the cases that no archetype fits, and the academic compositions (research question,
contribution, positioning matrix, objectives against evidence, threats to validity,
references). Read references/design-system.md before the first slide, and again
whenever a slide looks wrong but nothing is broken.
Follow evidence-on-slides.md for the evidence. Follow citing-on-slides.md for
attribution. Follow academic-register.md for the voice.
Every slide needs notes. The notes carry a running clock, the spoken text and the answer
to the question the slide will provoke. check fails a slide with no notes.
Steps 6 to 8. Build, check and render
scripts/deck build <deck.py> # -> out/<name>.pptx, and the PDF when export_pdf=True
scripts/deck check <deck.py> # Exit code equals the error count.
scripts/deck render <deck.py> # -> out/render/ pdf + slide-NN.png + contact sheets
Deck(export_pdf=True) makes build write the PDF beside the .pptx as well, so the
deck folder holds both files and the export is not a step to remember. It needs
LibreOffice, and it does not need the rasteriser. render writes the PDF beside the
.pptx too, and keeps its working files in out/render/.
Look at the contact sheet. This step makes the deck good, and a model tends to skip it.
check cannot see a drop shadow, a centred bullet, an imbalance or a dead bottom third.
Read references/verification.md for the loop and the order of inspection. Read
references/gotchas.md when something renders wrong and no visible cause exists.
Repeat build and render until the sheet is clean. Two passes is normal.
Step 9. Check the timing
scripts/deck timing <deck.py>
The verb reads the ZEIT budget from the notes. It sums the budget against
Deck(minutes=...), and it reports each slide's spoken words against its slot at 125
words per minute. A script that does not fit its slot is the defect that a rehearsal
finds too late.
The total is the number that matters. A talk 30 seconds over is a talk that skipped its conclusion. Fix the script or the budget. Do not trust speed.
Step 10. Check the readiness (a defence or a viva)
check sees the structure. render sees the layout. Neither sees the argument, and a
defence is marked on the argument.
scripts/deck readiness <deck.py> # argument skeleton: titles, statements, closing verdict, backup questions
Read the skeleton instead of the slides. Answer the five questions in
references/defence-readiness.md: abstraction, contribution, positioning, scope and
thread. Report each finding with its slide number. Fix, rebuild, and run the pass again
after the next render.
This is a reviewer pass. The verb extracts the argument. You supply the review.
Step 11. Build the handout
scripts/deck handout <deck.py> # -> out/render/<name>-handout.pdf
One page per slide: the slide image, its notes and its clock. The speaker rehearses from it, and an examiner sometimes asks for it. Cut the script here when the timing report says the script runs over budget.
Step 12. Write the backup
Write eight to twelve slides after deck.backup_divider(). Each slide answers one
question that the talk will raise, and its notes name that question. The genre profile
lists the highest-value set for a defence, and that set includes the Kritikpunkte map.
Error handling
deck: theme not found. The theme JSON was not copied.initcopies one. You can also runscripts/deck themesand pass an explicit path toTheme.load().deck: figure not found. Figures resolve relative to the deck module. UseHERE / "Assets/figures/..."and check that the file exists.checkreportsoverlapon a statement bar. Passreserve=s.statement_reserveto the archetype above it.checkreportsshadow. A shape was built outsidedeckkit.layout. Build it with a primitive.checkreportsfigure. A picture carries noalt=and nocredit=. Add one. A reproduced figure needs its source. Every figure needs a description.renderreports "LibreOffice not found". Install it withbrew install --cask libreoffice. No fallback exists, because an unrendered deck is an unverified deck.timingreports a slide as "not budgeted". The notes have noZEIT h:mm–h:mm (N s)line, so the slide is invisible to the budget. Fix the notes.handoutembeds 100 MB of images, or the notes show?. The images are not being downscaled, or the machine has no Unicode font for the PDF.deckkit/handout.pyhandles both cases. A machine with neither Arial nor a DejaVu or Liberation face transliterates the quotes and dashes.readinessprints a title but no statement. The slide's claim lives only in the notes. The skeleton shows what the audience hears. Move the claim onto the slide, or accept that the slide carries none.- You changed
deckkit/. Rebuild and render a real deck, not the scaffold.
Boundaries
Will:
- Author a deck module, choose a talk genre, derive a theme.
- Run build, check, render, readiness, timing and handout.
- Export
.pptxand.pdf. - Write backup slides and a Kritikpunkte map.
- Run the defence-readiness reviewer pass.
Will not:
- Edit a
.pptxin place. - Animate or transition slides.
- Write the underlying argument of a thesis. That work belongs to
academic-writing. - Produce anything other than a slide deck. Prose belongs to
human-writing. - Store deck content inside this skill.
Done when
scripts/deck check <deck.py>exits 0.- You looked at the contact sheet, and the last build is the one you looked at.
scripts/deck timingshows the noted budget meetingminutes=, and no slide's script runs long for its slot without a recorded decision.- An academic talk has the genre profile's "what must land" slides, evidence that follows
evidence-on-slides.md, and attribution that followsciting-on-slides.md. - A defence has a readiness pass with the five questions answered and findings keyed to slide numbers.
- Every slide carries notes with a time budget and a quoted
Sprechtext. - The brief's four facts appear either in the deck module or in the printed defaults.