Slides from your repo,
that tell you when to rebuild them
A skill that turns any repository into a single-file HTML deck, then tells you which slides stopped matching the code. This demo deck was built by the skill, about the skill.
SlideOps · examples/skill-demo.html
What we'll cover
1. What it builds
One self-contained HTML file; nothing invented to fill space.
2. How to use it
The guided intake: it scans your repo, then asks with real options.
3. Design control
Four theme presets, font options, Mermaid diagrams: shown on real decks.
4. Under the hood
The verification loop that makes "done" mean "looked at".
One file, no dependencies, all real
Every deck is a single HTML file: 1280×720 slides, click/arrow/URL-hash navigation, a progress bar, optional paginated PDF export. No build step, no CDN, works offline and attaches to an email.
Grounded content
Code snippets are copied from real files, stats are recomputed from raw data, diagrams trace real call paths, images are real artifacts. When docs and code disagree, code wins.
Two starting points
A general overview (what it is, install, run, architecture) or a focused deep dive (one subsystem, one release, one decision).
The pipeline, orient to ship
The checkpoint is the highest-leverage step: 30 seconds of review beats rebuilding 25 slides around the wrong topics.
Say what you want, it asks the rest
💬 "make slides about this repo"
→ scans README, git log, and docs first, then proposes 3-4 concrete deck topics with a "why now" for each, plus audience, length, theme, and extras menus
💬 "deep dive on the auth subsystem, midnight theme, with a PDF"
→ skips answered questions, researches the subsystem, shows the outline, builds a 12-20 slide deck and a page-per-slide verified PDF
# install: copy the skill folder into your skills directory cp -R slideops ~/.claude/skills/
Existing decks in the output folder reshape the proposals: covered topics drop off the list, and "update deck X" appears when commits have landed since it shipped.
Three deck shapes
| Deck type | Slides | Section dividers | Real decks built with it |
|---|---|---|---|
| Lightning update | 8-15 | No, straight into content | release update (12), design system tour (12) |
| Focused deep dive | 12-20 | Only if sub-topics run 3+ slides | subsystem deep dive (16-19) |
| General overview | 20-35 | Yes, one per major section | onboarding overview (25) |
Density rule: one idea per slide. A table, a diagram, and a code comparison get three slides, not one.
The accuracy contract
Always
- Copy snippets from the real file, then HTML-escape them
- Recompute every aggregate stat from the raw data
- Ground "shipped" claims in actual commits via git log
- Trace diagrams through real imports and call sites
Never
- Fabricate a chart or invent numbers for a caption
- Reword a quoted line to make it fit the slide
- Checkmark planned work as if it shipped
- Trust a doc the code contradicts
Why so strict: a wrong technical detail is far worse than a slide with less detail on it. The style guide enforces this with grep checks, not good intentions.
13 slide patterns, copy and fill
| Pattern | Use for |
|---|---|
| Title · agenda · section divider · closing | Deck skeleton; dividers give multi-topic decks breathing room |
| Prose + cards | "What is X" concept intros |
| Reference table | Flags, modes, field lists: anything row-shaped |
| Before/after code | Migrations and "old way vs new way", both sides verbatim |
| Annotated snippet (half or full width) | One real file with commentary; full width fits ~95-char lines |
| Flow diagram · lane comparison | Simple pipelines and "where does X apply" rows |
| Image + caption | Real screenshots and generated charts only |
| Chat bubbles | "Say this, get that" usage examples (slide 5 of this deck) |
Each block ships in assets/template.html with a comment saying when to use it; unused blocks get deleted.
The whole theme is one block
:root{
/* surfaces */
--bg:#faf6ee; --bg2:#f2ecdf; --card:#ffffff; --code-bg:#2b2820;
…
/* roles */
--accent:#7a7f1f; --accent2:#5f6419; --warn:#a34a3f; --bad:#b5544a;
…
--card-border:color-mix(in srgb, var(--muted) 30%, transparent);
}
Every color derives from these tokens: tags, tints, borders, and gradients are color-mix expressions, so swapping the block restyles the entire deck.
Presets in references/themes.md: Ledger Light, Ledger Dark, midnight, graphite, or extract a brand's real CSS values and map them onto the roles. The next four slides are real decks, one per theme.
Ledger Light, the default
Sample deck slide in the default theme: warm paper surfaces, olive accent, dark code blocks.
Ledger Dark, the same palette after dark
The same sample deck in Ledger Dark: espresso surfaces and a soft gold accent, the same warm family after dark.
Midnight, with an inline Mermaid diagram
Sample deck in Midnight: deep navy, sky-blue accent, with a Mermaid sequence diagram pre-rendered to themed SVG.
Graphite, and how cheap a re-theme is
The same sample deck re-themed to graphite by replacing its :root block and nothing else.
Mermaid without breaking self-containment
npx --yes @mermaid-js/mermaid-cli \ -i "$STAGE/<name>.mmd" -o "$STAGE/<name>.svg" \ -c "$STAGE/mermaid-config.json" -p "$STAGE/puppeteer-config.json" \ -b transparent -I "mmd-<name>"
Rendered at build time, inlined as SVG: no runtime JS, no CDN. The config maps the deck's current theme tokens onto Mermaid's themeVariables, and the unique svgId keeps two diagrams from restyling each other.
When to bother: sequence diagrams, branching graphs, and ER diagrams. Simple linear pipelines use the built-in flow boxes instead (slide 4 of this deck), which need no tooling at all.
The deck tells you when it goes stale
$ python3 scripts/check.py docs/slides/architecture.html --repo . slide 7 PIPELINE backend/app/main.py:40-58 CURRENT slide 12 MIGRATIONS backend/alembic/env.py:18-31 MOVED same content, now at lines 22-35 slide 15 RATE-LIMIT backend/app/middleware/rate.py CHANGED 4 line(s) differ 1 current, 2 stale, 3 cited in total.
Every snippet carries its source: data-src="path:40-58" plus a hash of those lines at build time. Checking a deck re-reads the repository and compares.
Exit code 1 when anything is stale, so a CI job fails the day a deck stops matching the code, not the day someone presents it. --suggest prints the diff and the replacement.
"Done" means "looked at"
| Check | What it catches |
|---|---|
| Screenshot every slide with headless Chrome, view each PNG | Text under the nav pill, stretched cards, clipped code, broken images, wrong numbers |
| Tag-balance grep (sections and divs) | One unclosed div silently breaking every later slide |
| Em-dash and color-literal greps | Style violations and colors that escaped the theme block |
| PDF re-rendered via pypdfium2 | Structurally valid PDFs whose image pages are silently blank |
Chrome discovery is cross-platform (macOS and Linux Playwright caches, then system installs); staging is a fresh per-deck directory so parallel builds never collide.
What ships & where to start
What ships
SKILL.md: the workflow, intake to shipassets/template.html: 13 patterns, nav, theme blockreferences/: style, themes, diagrams, verification, freshness, automationexamples/skill-demo.html: this deckslides-to-pdf: companion skill, any HTML deck to PDFscripts/cite.py: writes a citation, stamps the build commitscripts/check.py: tells you when a deck goes stale
Start here
SKILL.md: read top to bottom oncereferences/style-guide.md: the writing rules and grep checksreferences/themes.md: palettes and fonts