ericrisco/rsc-harness / skills/presentations
presentations
VerifiedUse when building, theming, or exporting a presentation deck — pitch, sales, keynote, board/QBR, leave-behind one-pager — from slide structure to a token-based theme to PDF or editable PPTX (Marp, Slidev, python-pptx). NOT the words (that is `marketing`), NOT the visual tokens (that is `design`), NOT the investor story arc (that is `pitch-deck`).
Presentations — Stunning, On-Brand Decks (PDF + PPTX)
Two first-class pipelines, one decision. Design-led Markdown decks (Marp/Slidev) for a deck that flipa and exports clean to PDF and PPTX, or native editable PowerPoint via
python-pptxwhen the user must hand off a.pptxpeople will edit in PowerPoint/Keynote/Google Slides. The deck owns structure, visual system, and export. The words aremarketing's job; the visual tokens aredesign's. This skill orchestrates all three into a finished deck.
Also out of scope: a web-native, scroll/animation-heavy landing page (that is
../design/SKILL.md + ../nextjs/SKILL.md); a video / motion explainer as the deliverable — this
skill uses motion only as restrained slide transitions and builds, never as the medium; and the live
financial model behind an investor deck — this skill renders the slides and cites the model as the
source of truth.
Brand grounding (gate — clears before the first headline)
Never produce deck copy or a deck narrative without a complete brand study. A deck is the brand on
stage: generic slides read as "another AI deck" the moment they hit the projector, and the only cure is
grounding every headline, claim, and tone choice in a real, persisted brand profile. This is the same
gate marketing and design enforce — decks share the study, they do not fork it.
- Locate the brand study. Read the project's root
CLAUDE.mdfor a## Brand & voicesection linking into02-DOCS/wiki/brand/(theharnessKarpathy-wiki convention: compiled brand articles under02-DOCS/wiki/brand/, raw inputs the user pastes under02-DOCS/raw/brand/). NoCLAUDE.md, no link, or a link that points nowhere = ABSENT. - Check completeness against the checklist in
references/brand-grounding.md— it extends the shared brand checklist with deck-specific dimensions: deck purpose, audience & setting, length, presenter-vs-leave-behind, and must-include slides. Any empty dimension = INCOMPLETE. - If ABSENT or INCOMPLETE, STOP and interview the user — one focused batch at a time, never all questions at once. Voice samples are mandatory; never fabricate a voice. Then persist: write/update the brand study under
02-DOCS/wiki/brand/(raw inputs verbatim under02-DOCS/raw/brand/), and add/update the## Brand & voicelink in rootCLAUDE.md. Exact format →references/brand-grounding.md. - Only once the study is complete, proceed — and cite which articles drove the deck (e.g. "narrative grounded in
02-DOCS/wiki/brand/value-proposition.md, voice invoice.md").
Single exception: if the user explicitly says "skip it, rough draft", you may produce a clearly-labelled
DRAFT (ungrounded — not brand-checked) and still recommend running the gate before it ships.
Design the message before the pixels
A deck is a communication artifact, so the design that matters most is the message design. Everything below descends from audience-centered design — every choice serves the audience's understanding, not the presenter's comfort.
Plan the message (six questions). Lock these before storyboarding: (1) who specifically is the
audience and what do they already know; (2) the ONE main message they remember a week later; (3) the 3–5
supporting points that carry it; (4) the evidence proving each; (5) the single call-to-action; (6) what is
essential vs. expandable under time pressure. These feed the deck arc directly: message = thesis, points =
beats, CTA = closing ask (→ references/storytelling-and-decks.md).
Assertion-evidence is the slide unit. Each slide = one assertion (a complete claim, written as the title) + the visual evidence that proves it — never a topic label over a bullet list. "User engagement rose 43% after the redesign" + a chart, not "Engagement" + three bullets. The body proves the headline; it never repeats it.
One concept per slide. Working memory is small and the audience is also listening to you. If a slide needs two breaths to explain, it's two slides. Reveal sequential parts progressively — build order is the explanation — rather than dumping everything at once.
Spoken vs. shown — never both. The slide and your mouth are two channels; redundancy wastes both. Show the assertion, the visual, the number, the next step; say the elaboration, the context, the interpretation, the story. Reading slides verbatim is the fastest way to lose a room.
Full frameworks — the planning questions, the spoken/shown table, the 1–5 evaluation rubric
(audience-centered / visual clarity / cognitive load / accessibility), the implementation checklist, and the
communication anti-patterns — live in references/slide-design.md. Score any draft against the rubric (≥ 4
on each axis) before shipping.
Which pipeline? (decide before building)
Pick once, up front — switching mid-build is expensive.
| Question | → Markdown deck (Marp/Slidev) | → Native PPTX (python-pptx) |
|---|---|---|
| Primary deliverable | A stunning deck; PDF is the hero, PPTX a bonus | An editable .pptx people will open and change |
| Who edits after handoff | You / engineering, in Markdown + Git | Non-technical stakeholders, in PowerPoint/Keynote/Slides |
| Visual ceiling | High — full CSS/HTML, web fonts, CSS grid, gradients, SVG | PowerPoint's box model; native charts/tables/SmartArt-lite |
| Theming source | Design tokens → CSS theme (OKLCH, type scale, spacing) | Design tokens → .pptx theme (sRGB colors, theme fonts) |
| Data viz | SVG / chart libs / images, full control | Native, editable PowerPoint charts (live in the file) |
| Diffable / reviewable in Git | Yes (Markdown) | No (binary) |
| Speaker notes | Yes (<!-- notes --> / notes:) | Yes (native notes pane) |
| Version control of changes | Excellent | Poor (binary blobs) |
Default to the Markdown pipeline for anything where "stunning" matters and the user is fine getting a
PDF (+ image-based PPTX). Choose python-pptx the moment the user says "I need to edit it in
PowerPoint", "the client edits the slides", "live charts", or "corporate template .potx". When unsure,
ask one question: "After I hand it over, will someone edit the slides in PowerPoint/Keynote, or is a
polished PDF enough?" You can also build in Markdown and additionally export a --pptx for handoff —
just warn that Marp/Slidev PPTX slides are images, not editable text (a key gotcha, see exports).
Deep recipes for each → references/markdown-decks.md and references/pptx-python.md.
Workflow
- Ground in the brand study (gate above). Pull voice, positioning, proof, audience.
- Pick the deck arc for the purpose (pitch / sales / product / keynote / investor / QBR) from
references/storytelling-and-decks.md. Lock the one-sentence thesis the whole deck proves. - Write the slide-by-slide skeleton — one assertion headline per slide + the proof it carries. This is a
marketingcollaboration: headlines are copy. Get the skeleton approved before designing pixels. - Pick the pipeline (table above).
- Build the theme from design tokens — map the project's OKLCH palette, type scale, and spacing into a Marp/Slidev CSS theme or a python-pptx theme. (→
references/slide-design.md,references/markdown-decks.md,references/pptx-python.md) - Lay out the slides against the visual system: grid, type scale for projection, data-viz best practices, imagery, contrast, restrained motion. (→
references/slide-design.md) - Produce presenter + leave-behind variants if needed: presenter version is sparse (headline + visual, talk track in notes); leave-behind is self-explanatory (more on-slide text, appendix). (→
references/storytelling-and-decks.md) - Export to PDF (vector, fonts embedded, 16:9) and/or editable PPTX; handle font-embedding and file-size gotchas. (→
references/markdown-decks.md,references/pptx-python.md) - Verify with
scripts/verify.sh(lint deck sources, dry export, import check) and the QA gate below. - Record deck conventions in
02-DOCS/wiki/stack/presentations.md(Project grounding, below).
Worked example — storyboard → theme → export (Markdown pipeline)
One end-to-end pass, brand study already complete. Read this once and you rarely need to round-trip the references for a standard Markdown deck.
1. Storyboard the spine (assertion headlines only — read top-to-bottom, they ARE the pitch; →
references/storytelling-and-decks.md). Thesis: "Onboarding v2 is why we can raise now."
1 Onboarding v2 cut churn 40% (title)
2 One in three users never finished setup (problem — make it ache)
3 We rebuilt the first run as one screen (solution, one visual)
4 Activation rose 28pts in six weeks (proof — chart, one series)
5 TAM is $12B, growing 24%/yr (market, stated assumptions)
6 The ask: $2M to make this the default path (CTA — one ask)
2. Theme from design tokens. Pull OKLCH palette + type scale from 02-DOCS/wiki/stack/design.md into a
Marp CSS theme (full theme → references/markdown-decks.md). The load-bearing move is mapping tokens to
variables once, never hand-picking hex per slide:
/* @theme brand — generated from 02-DOCS/wiki/stack/design.md */
@import url('https://fonts.googleapis.com/css2?family=Fraunces:wght@700&family=Inter:wght@400;600&display=swap');
:root { --brand: oklch(0.62 0.19 264); --ink: oklch(0.18 0.03 264);
--surface: oklch(0.98 0.005 264); --accent: oklch(0.74 0.17 52); }
section { background: var(--surface); color: var(--ink); font-family: Inter, sans-serif; font-size: 26px; }
h1 { font-family: Fraunces, serif; font-size: 44px; } strong { color: var(--accent); }
Write the spine into deck.md with marp: true, theme: brand, size: 16:9, talk track in <!-- notes -->.
3. Export to PDF + PPTX and verify fonts embed (gotchas → references/markdown-decks.md):
npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pdf --pdf-outlines --pdf-notes
npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pptx # image-per-slide; NOT editable text
pdffonts deck.pdf # every font must read 'emb yes'
./scripts/verify.sh # lint + dry export + QA checklist
If the client will edit the slides, this is the wrong pipeline — rebuild with python-pptx (→
references/pptx-python.md), whose build_deck.py emits the same six slides as native editable shapes/charts.
Tooling & current versions (verified 2026-06)
- Marp —
@marp-team/marp-cli. Run pinned:npx @marp-team/marp-cli@latest deck.md --pdf. Exports HTML / PDF / PPTX / PNG / JPEG. Needs a Chromium-family browser (Chrome/Edge) or Firefox for PDF/PPTX/image export (v4 added Firefox via WebDriver BiDi as a fallback; Chrome/Edge are preferred and give the most faithful PDF).--pptxis image-per-slide;--pptx-editableis experimental and needs LibreOffice (soffice).--notes/ a.txtoutput exports speaker notes. Node 18+. (→references/markdown-decks.md) - Slidev —
@slidev/cli(Vue-based). Scaffoldnpm init slidev@latest; devslidev; exportslidev export(PDF default;--format pptx|png). Export needsplaywright-chromiuminstalled in the project (npx playwright install chromiumornpm i -D playwright-chromium). PPTX is image-per-slide; notes carry over per slide. Best for code-heavy / developer talks (live code, Monaco, Mermaid, Vue components). (→references/markdown-decks.md) - python-pptx —
pip install python-pptx(current major1.x, e.g.1.0.x). Pure Python, no Office/LibreOffice needed to write.pptx. Creates masters/layouts, text, tables, native editable charts, images, speaker notes. Cannot render to PDF itself — convert via LibreOfficesoffice --headless --convert-to pdfor open in Office. (→references/pptx-python.md) - decktape / Playwright — fallback HTML→PDF for any web deck (reveal.js, custom HTML) when Marp/Slidev export isn't available. (→
references/markdown-decks.md)
Always pin/verify the version in the target project before generating (marp --version, npx slidev --version, python -c "import pptx; print(pptx.__version__)"). Tooling moves; re-check rather than trusting memory.
Slide copy (with marketing)
The deck's words are conversion copy on a stage. Defer the craft to ../marketing/SKILL.md; this skill
enforces the deck-specific shape:
- Benefit-led, climbing feature → benefit → proof, stopping at the rung the audience cares about. Specificity (a number, a mechanism, a receipt) beats adjectives — "2× faster" not "blazing fast".
- Two text densities, chosen deliberately: presenter slides carry a headline + one visual + 0–3 support points, with the argument in the speaker notes / your mouth; leave-behind slides are self-contained because no one is narrating. Never ship a wall-of-text presenter slide.
- Voice from the brand study. Headlines obey the do/don't word lists and tone samples. Ban-list words ("revolutionary", "seamless", "game-changer", "supercharge") are defects.
Visual system for slides (with design)
The deck's pixels are the brand's design system projected at 3 metres. Defer the system to
../design/SKILL.md; this skill enforces the deck-specific constraints (full depth →
references/slide-design.md):
- Layout grid built for 16:9: a 12-column grid, generous margins, one focal point per slide, consistent safe-area so nothing clips on a projector.
- Type scale for projection, not laptop reading distance: display/headline/body/caption steps, body ≥ 24pt (≥ 28–32pt for talks), ~6 words/line and ~6 lines/slide as a ceiling, contrast ≥ 4.5:1. Never drop below the legibility floor to cram text — split the slide instead. If it doesn't read at 3 metres, it doesn't ship.
- Color from tokens, allocated for a room: dark themes read better in dark rooms / on big screens, light themes for printed handouts and bright rooms. High contrast always; never rely on color alone to encode meaning.
- Data viz that makes one point: one chart = one takeaway named in the headline; remove gridlines/clutter; label directly; pre-attentive emphasis (one highlighted bar/line) over rainbow palettes; never a 3-D pie. Every number traces to a source — mark gaps
[[NEEDS PROOF]], never fabricate one to fill a chart. - Imagery full-bleed and intentional (with a legibility scrim behind text), not stocky decoration; respect resolution so it doesn't pixelate on a 4K projector.
- Motion with restraint: one transition family, ≤ 300ms, builds that reveal one idea at a time; reduced-motion honored in HTML pipelines. Animation explains sequence/state change, never just fills time.
Anti-patterns
| Anti-pattern | Why it's wrong | Do instead |
|---|---|---|
| Topic-label headlines ("Market", "Team") | Forces the audience to find the point | Assertion headline that states the point |
| Wall of bullets / paragraphs on a slide | Audience reads instead of listening; nothing lands | One idea, ≤ ~6 lines; move detail to notes/appendix |
| Reading the slides verbatim | The slide and the talk become redundant | Slide = the visual; you = the narration; notes = the script |
| Tiny text to fit more | Unreadable from the back; signals filler | Split into more slides; raise the floor, not lower it |
| Hand-picked hex per slide | Drifts off-brand, inconsistent | Map design tokens once into the theme |
| Rainbow charts, 3-D pies, dual axes | Decoration over meaning; misleads | One highlighted series; direct labels; honest axes |
| Generic stock photos + purple gradient | Reads as "AI deck"; no identity | Brand imagery + token palette + a real type pairing |
| Every-element animation, slow transitions | Noise; tanks pacing; nausea | One fast transition family; builds that reveal meaning |
| Exporting PPTX from Marp/Slidev and calling it "editable" | Slides are flattened images, not text | Use python-pptx when editability is required |
| Fonts not embedded in the PDF | Renders with fallback fonts on other machines | Embed fonts; verify (see exports gotchas) |
| Invented metrics to fill a chart | Destroys credibility in the room | Cite the source; mark gaps [[NEEDS PROOF]] |
Quick reference
# --- Markdown: Marp (PDF is the hero; PPTX = images) ---
npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pdf # vector PDF, fonts embedded
npx @marp-team/marp-cli@latest deck.md --theme ./theme.css --pdf --pdf-outlines --pdf-notes
npx @marp-team/marp-cli@latest deck.md --pptx # image-per-slide PPTX
npx @marp-team/marp-cli@latest deck.md --pptx --pptx-editable # experimental, needs soffice
npx @marp-team/marp-cli@latest deck.md --notes notes.txt # speaker notes only
# --- Markdown: Slidev (code-heavy talks) ---
npm init slidev@latest # scaffold
npx slidev # dev server (localhost:3030)
npx playwright install chromium # one-time, for export
npx slidev export # PDF (default)
npx slidev export --format pptx # image-per-slide PPTX
# --- Native editable PPTX (python-pptx) ---
pip install python-pptx
python build_deck.py # your generator (see ref)
soffice --headless --convert-to pdf deck.pptx # PPTX -> PDF via LibreOffice
# --- Fallback: any HTML deck -> PDF ---
npx decktape reveal http://localhost:8000 deck.pdf
# --- Verify before shipping ---
./scripts/verify.sh # warn-by-default; lint sources + dry export + import check
./scripts/verify.sh --strict # gate CI (warnings become failures)
Deck QA gate
Run before claiming done — each line is a defect if unchecked. scripts/verify.sh automates the
mechanical subset.
- Brand study located, complete, and cited (which articles grounded the deck).
- One idea per slide; every slide titled with an assertion headline, not a topic label.
- Body text ≥ 24pt (≥ 28–32pt for a talk); ≤ ~6 words/line, ≤ ~6 lines/slide; contrast ≥ 4.5:1.
- Colors / type / spacing come from design tokens, not hand-picked per slide.
- Deck follows a deliberate arc with a single thesis; opens with a hook, closes with the ask/CTA.
- Every number traces to a source; gaps marked
[[NEEDS PROOF]], none invented. - Charts each make one point, named in the headline; no 3-D/rainbow/dual-axis clutter.
- Motion is one restrained family (≤ 300ms); reduced-motion honored (HTML); builds reveal meaning.
- Presenter vs leave-behind variant chosen deliberately; presenter notes hold the talk track.
- 16:9; PDF is vector with fonts embedded; PPTX opens clean in PowerPoint/Keynote/Slides.
- PPTX editability matches the promise (python-pptx if "editable", not flattened Marp/Slidev images).
- File size sane (compressed images, subsetted fonts); ban-list words absent from copy.
- Scored ≥ 4/5 on each axis of the design rubric — audience-centered, visual clarity, cognitive load, accessibility (→
references/slide-design.md, "Diagnostic rubric").
Project grounding (02-DOCS)
In a project with a 02-DOCS/ layer (the harness Karpathy wiki), read
02-DOCS/wiki/stack/presentations.md first and stay consistent with it; create or refresh it when
missing or stale, and index it in 02-DOCS/wiki/index.md. It records this project's real choices: the
chosen pipeline (Marp / Slidev / python-pptx) and why, the theme file path and how it maps the design
tokens, the standard deck arc(s), export commands and the canonical output, the presenter-vs-leave-behind
convention, and font-embedding / asset-location notes.
The deck theme is downstream of the design tokens: always reconcile that article with
02-DOCS/wiki/stack/design.md so the deck and the product share one palette and type system.
No 02-DOCS/ layer? Skip silently (optionally suggest harness). Unlike the brand study, deck
conventions are recorded, not gated — never block the task on this.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |