This skill has two jobs, and the second one is the point.
\nBuild: turn a repository into a deck whose every claim came from the code, not from a\nmodel's impression of the code. Keep in sync: make that deck able to prove, months\nlater, whether it still matches the repository, cheaply enough that nobody has to\nremember to care.
\nThe mechanism joining them is a citation. Every quoted snippet records the file, the line\nrange, and a hash of those source lines at build time, and the deck records the commit it\nwas built from. That turns \"is this deck still accurate?\" from a question somebody has to\nanswer by reading into a command that answers itself:
\npython3 scripts/check.py docs/slides/ --repo .\nStandard library only. No model, no network, no tokens, milliseconds to run. Two scripts\nship with this skill and do all of it: scripts/cite.py writes the\ncitations while you build, and scripts/check.py reads them back\nafterwards. Writing the citations as you go (Step 3) is therefore not optional decoration:\nit is the entire reason the deck can be maintained instead of rewritten. See\nreferences/freshness.md for the mechanism and\nreferences/automation.md for wiring it into pull requests,\nscheduled refreshes, and agent hooks.
references/markdown.md. It reuses this file's\nresearch, confidentiality, and refresh rules and swaps the build and verify steps;\nreferences/markdown-pdf.md covers exporting such a doc\nto PDF. Checking or refreshing an existing .md doc is the same check.py workflow\nas decks; sweeps pick both up together.Produces a single self-contained HTML slide deck (no build step, no CDN dependencies):\none 1280×720 slide per screen, click/arrow-key/URL-hash navigation, a progress bar and\nslide counter, an Esc-toggled overview grid (deep-linkable as #overview), optional\nper-slide speaker notes (<aside class=\"notes\">, toggled with N, invisible in exports),\nand, on request, a paginated PDF export. Every slide is grounded in the real repository:\nreal code snippets, real commands, real screenshots, real numbers. Nothing is invented\nto fill space.
A worked example ships with the skill: examples/skill-demo.html\nis a 17-slide deck about this skill, built by this skill, showing the patterns, all four\ntheme presets on real decks, and an inlined Mermaid diagram.
Two starting points, chosen with the user up front:
\nSpend ~2 minutes scanning the repo before asking anything, so every question you ask\nis concrete and every option you offer actually exists: read the README and the\nmanifest(s) that define the product (per-app in a monorepo), run git log --oneline -15\nand glance at the top-level tree and docs/, and check whether docs/slides/ already has\ndecks (open one: its title slide, theme and build stamp show the local conventions). Do\nnot start slide research yet; this pass is only to ask good questions. The scan itself may hit stale doc pointers; note them\nand move on (Step 1's code-wins rule deals with drift later).
What you find shapes the candidates:
\nThen ask everything in one compact intake (use your environment's structured-question\ntool if it has one; otherwise a single message with lettered options). Mark the default\nin each list, skip any item the user already answered, and never exceed these six:
\nsync/ subsystem is\nthe largest and undocumented: a deep dive\", \"no onboarding doc exists: a general\noverview\"), plus \"something else: tell me\". Never ask a bare \"what should the deck be\nabout?\": the scan is what makes this question answerable in one click. Mark as default\nthe candidate you would genuinely bet the user wants given the repo's core domain and\nits deck history (a core subsystem with zero coverage usually beats a\nrecently-changed-but-already-presented area), not mechanically the most recent change.references/themes.md: Ledger\nLight (default) · Ledger Dark · midnight · graphite · match a brand (ask for the URL/style\nguide; fetch it for real per references/style-guide.md\n§ Theming, never invent colors from a description). Optionally a font choice\n(themes.md § Font options) if the user signals caring about typography. If the user\nhesitates between themes or asks to see them, show rather than tell: copy the\ntemplate, swap in each candidate preset's :root block, screenshot the title slide\nof each (the recipe in references/verification.md),\nand present the images side by side before they choose.npx network access, see\nreferences/diagrams.md) · output:\n<repo>/docs/slides/<topic-slug>-<date>.html\"). The deck (plus a PDF if asked for) is\nthe only file this produces, so there is nothing else to agree on.For \"what changed\" style decks, also pin the recency window (a date range or \"since\nthe last release\") and resolve it with git log before writing anything, not from memory.
The outline checkpoint. After the first research pass, show the user a proposed\ntopic list and slide flow (like a table of contents) and get a thumbs-up before\nwriting any HTML: this is the single highest-leverage checkpoint. Building 25 slides\naround the wrong 6 topics wastes far more time than a 30-second review would have.\nSkip the checkpoint only when one of these observable conditions holds:
\nA deck is a document that leaves the repository: it gets emailed, screen-shared, and\nposted. Treat everything you put on a slide as public from the moment it is written.
\nNever read for slide content, and never quote: .env and any *.env*, key/certificate\nfiles (*.pem, *.key, id_rsa*, *.p12, service-account JSON), secrets/,\ncredentials*, .npmrc/.pypirc/.netrc, CI secret definitions, production logs,\ndatabase dumps, fixtures containing real customer data, and any path the repository's own\nignore files exclude. If a file you need is on this list, describe its shape (\"a service\naccount JSON, mounted at runtime\") instead of its content.
Redact even from files that are safe to quote: credentials, tokens, API keys, private\nhostnames and internal URLs, IP addresses, account and customer identifiers, personal\nnames and emails that are not public contributors, and precise infrastructure paths where\na generic description carries the same meaning. Replace with a clear placeholder\n(<project-id>, db.internal.example), never a plausible-looking fake.
Ask when it is the user's call, not yours: if a slide would be materially weaker\nwithout a detail that looks sensitive (an internal hostname in a diagram, a real customer\ncount, an unannounced feature name), ask the user before including it, and say what you\nare about to expose. Silence is not consent.
\nScreenshots carry more than you think. A screenshot of a terminal, dashboard, or\neditor also captures window titles, file trees, branch names, ticket numbers, other\ntabs, and notifications. Crop to the region that makes the point, and read the image back\nbefore embedding it.
\nVerification includes a redaction scan of the finished artifacts: see\nreferences/verification.md § Redaction scan.
The deck is only as credible as its weakest verified claim. For every slide you plan to\nwrite:
\npyproject.toml, package.json,\ngo.mod, …), the actual source of anything you plan to quote or diagram, existing\narchitecture docs, existing agent-instruction files (CLAUDE.md, .agents/skills/,\n.claude/skills/, and similar: these often already describe real user-facing\ncapabilities accurately, a goldmine for \"say to your assistant\" style bubbles).git log --oneline --since=... -- path\n(and git log -p for real diff content) to ground every \"shipped this month\" claim in an\nactual commit, not a vague impression. Cross-check version bumps (e.g. pyproject.toml\nhistory) against the commits that produced them. A file added inside your window may\nalready be deleted again by a later commit: git show <commit>:<path> recovers it, and\nthe deletion may itself be worth a slide note.references/diagrams.md.Before writing HTML, sketch the flow as a short outline (title → agenda → N sections, each\nwith 2-6 slides → close) and share it per the outline checkpoint above. A well-paced deck\nopens with a title slide, an agenda, and 2-3 \"the project in one picture\" slides (what it\nis, one or two real results/screenshots), then either a section-divider-led deep dive per\ntopic (for a general/multi-topic deck) or straight into content (for a focused deck), and\nends on a closing/roadmap slide. Typical density: 1 idea per slide; resist cramming two\nideas onto one slide just to save a slide.
\nSection dividers count toward the slide budget.
\n| Deck type | \nRough slide count | \nSection dividers? | \n
|---|---|---|
| Lightning update (one topic, one meeting) | \n8-15 | \nNo, straight into content | \n
| Focused deep dive (one subsystem/feature) | \n12-20 | \nOptional, only if it has 2+ sub-topics | \n
| General overview / onboarding | \n20-35 | \nYes, one per major section | \n
Copy assets/template.html to the output path. It already has\nthe full verified CSS + navigation JS; do not rewrite either from scratch. All slide\nmarkup lives between the <!-- SLIDES START --> and <!-- SLIDES END --> markers;\neverything outside them stays untouched (a scripted splice against those markers is the\neasiest way to replace the body in one pass), with two exceptions: set the <head>'s\n<title> to the real deck title, and swap the :root theme block if the user chose a\nnon-default theme (references/themes.md).
Work through your topic list slide by slide, copying the matching PATTERN: block from\nthe template for each slide (title, agenda, section-divider, prose+cards, image+caption,\ntable, before/after code, single annotated snippet, flow diagram, chat-bubble examples,\nlane comparison, closing: see the template's own comments for when to use which) and\nreplacing every bracketed placeholder with real, verified content. Delete every pattern\nblock you didn't end up using; delete the illustrative comments too once real content\nreplaces them.
Cite every snippet as you write it, with the script, never by hand:
\npython3 scripts/cite.py app/main.py:40-58 --repo <repo> --snippet\nIt prints the data-src / data-sha256 pair to paste onto the <pre>, warns when the\nlines are too wide for the pattern you chose, and with --snippet prints the source\nalready HTML-escaped. Stamp the build commit once, when the deck is otherwise finished:
python3 scripts/cite.py --stamp <deck.html> --repo <repo>\nA hand-computed hash is worse than no hash: it silently reports CHANGED months later\nand nobody can tell whether the code moved or the build was sloppy. Same for the date,\nwhich is easy to invent and impossible to verify afterwards. Cite anything you quote or\nassert from one place; prose summarising a whole subsystem needs no citation. See\nreferences/freshness.md.
HTML-escape every verbatim snippet: & → &, < → <, > → >\ninside <pre>/<code>. Unescaped source code (generics, arrows, includes) silently\ncorrupts the markup downstream. Mind snippet line width too: see\nreferences/style-guide.md § Code snippets.
Follow every rule in references/style-guide.md as you\nwrite: sentence case, no em dashes in prose, tag accuracy, real-content-only, rather\nthan fixing it all in a pass at the end.
Keep slide numbering visible to yourself: an HTML comment <!-- N: LABEL --> above each\n<section class=\"slide\">. Comments are 0-indexed; the URL hash and the on-screen\ncounter are 1-indexed. Worked example: <!-- 6: ARCHITECTURE --> is display slide 7,\nreached at deck.html#7. Renumber the comments any time you insert or delete a\nslide, and when the user later says \"slide 12\", re-derive which section that is from\nthe file itself (grep -n '<!-- [0-9]*:' deck.html) rather than trusting a remembered\ncount: a stale comment index is a fast path to editing the wrong slide.
Do not consider the deck done until you've actually looked at it. This is not optional\npolish: run for the first time on any deck, this step reliably catches real bugs: broken\nimage paths, text overlapping the nav pill, tables overflowing their card, stale slide\nnumbering, wrong aggregate numbers.
\nreferences/verification.md, which also covers staging\ndirectories (always a fresh per-deck directory, never fixed shared paths: parallel deck\nbuilds collide) and a faster batched screenshot loop.fill class\nonly where stretching is wanted; the grids default to content height), tables or code\nblocks overflowing their container, and images that failed to load (a small\nbroken-image icon with visible alt text, almost always a relative-path problem: see the\nPDF workflow note in verification.md).python3 scripts/check.py <deck> --repo <repo>\nshould report every citation CURRENT. Anything else means the deck is already stale on\nthe day it was built: CHANGED means you quoted something and then it moved under you (or\nthe hash was hand-computed), UNVERIFIED means a snippet has no hash at all. Both are\nbuild defects, not future problems. Fix them now with scripts/cite.py.<div> breaks\neverything downstream silently:\npython3 -c \"\nimport re\nc = open('deck.html').read()\nprint('section:', len(re.findall(r'<section class=\\\"slide', c)), len(re.findall(r'</section>', c)))\nprint('div:', len(re.findall(r'<div', c)), len(re.findall(r'</div>', c)))\n\"\nIf asked for a PDF, use the companion slides-to-pdf skill (distributed alongside this\none; its SKILL.md is the full self-contained recipe if it isn't installed as a skill).\nIt screenshots every slide at 2x, prints a page-per-slide PDF with a centred page number\non every page, and verifies the result by rendering the PDF back to images, which is\nrequired because headless Chrome cannot rasterize a local PDF for a visual check and image\npages can be silently blank.
\nThe deck is the only file you leave behind. Do not write a companion README.md,\nindex, summary or notes file next to it, and do not add the deck to an existing one unless\nthe user asks: the deck already states what it covers, the build stamp already records\nwhere it came from, and a hand-written sidecar is one more thing to go stale. If the repo\nalready keeps such an index and the user wants it updated, that is their call to make, not\na default.
Everything that would have gone in that file belongs in your final message instead: what\nthe deck covers, its slide count, where it was written, how to view and navigate it\n(click, arrow keys, Esc for the overview, N for notes) and, since decks get edited\nslide-by-slide over many follow-up requests, one paragraph on how the file is structured\nfor future edits (the pattern-block/comment-numbering conventions above).
Tell the user, in that same message, how to find out when the deck has gone stale:
\npython3 scripts/check.py <deck-or-folder> --repo <repo> --suggest\nThen ask whether this deck should be kept in sync, and make it concrete rather than\nleaving it as a suggestion. The answer depends on what kind of document it is, so say so:
\nreferences/automation.md.\nReport-only first (--exit-zero), so it annotates a PR without blocking anyone. Vendor\ncheck.py into the repo (tools/slideops-check.py), because it is one dependency-free\nstandard-library file and the deck's repo should not depend on a skill being installed.Do not propose blocking every commit. A docs check on the fast path trains people to pass\n--no-verify, and drift is a review-time concern. The reasoning, the workflow files, the\nadvisory hook variants, and the delegated-refresh recipe are all in\nreferences/automation.md.
When the user asks whether a deck is still accurate, or wants one brought back in line,\nrepair it; do not rebuild it. A rebuild throws away the pacing, the narrative and the\nreview that went into the original, and costs far more than fixing three slides.
\nDetect, for free. Sweep the folder and read the result:
\npython3 scripts/check.py docs/slides/ --repo . --json\nThis costs no tokens and no model call. The JSON is a complete repair brief: per stale\ncitation it carries the status, the unified diff, the commits that caused it, the\ncorrected data-src/data-sha256, and the current source. Read that instead of\nre-reading the repository. If nothing is stale, say so and stop: that is the common\ncase and it should be cheap.
Triage by status, because they need different work:
\nMOVED: the code is identical, only the line numbers shifted. Update the two\nattributes. Do not touch the slide's prose, and do not re-verify visually: nothing\nrendered changed.CHANGED: read the diff and the commit subjects. A rename needs a re-quote; a\ndeleted branch of logic may have killed the claim the slide makes. Decide about the\nclaim first, then the snippet.MISSING: the file is gone. The slide is probably obsolete. Find where it went\n(git log --diff-filter=D -- <path>) and ask the user before deleting a slide.UNVERIFIED: no hash was recorded. Re-cite it with scripts/cite.py so it is\ncheckable from now on.Repair only what drifted. Edit those slides, re-trim snippets to the width budget\n(references/style-guide.md § Code snippets), and leave\nevery other slide alone.
Re-stamp and re-verify. python3 scripts/cite.py --stamp <deck> --repo ., then\ncheck.py until clean, then re-screenshot only the slides you touched (Step 4): a\nlonger snippet can push content under the nav pill. Re-export the PDF only if one exists.
Report what changed and why. Name the slides you edited, the commits that caused\nthe drift, and anything you judged still-true-despite-the-diff. That last category is\nwhere a human may disagree with you, so surface it rather than burying it.
\n