show-and-tell 🎪
Turn dense technical findings into a beautiful, genuinely plain-English HTML explainer your boss will actually read. One everyday metaphor, the real numbers shown honestly, engineer's-note asides, a foregrounded honesty box — wrapped in a cute arcade theme that opens straight from file://. No build, no server.
╔════════════════════════════════════════════════════════════╗
║ ║
║ S H O W · A N D · T E L L ║
║ ║
║ "...so basically, in plain English, here's the gist!" ║
║ ║
║ one metaphor · real numbers · an honest limits box ║
║ ║
╚════════════════════════════════════════════════════════════╝
A Claude Code skill that translates — it doesn't dumb down. The non-expert gets the gist and the honest bottom line; the engineer drops into the asides and finds nothing wrong. 🔥🪙🌙⚡🎮
☝️ A real render of the bundled template: "Why the nightly numbers were late," a slow overnight job explained as a kitchen prepping tomorrow's meals — every claim paired with a number, the bad news in its own honesty box, engineer's notes inline. Open assets/template.html in any browser to see it live.
✨ What it does
You just finished something technical — a debugging session, a research result, a measurement, a jargon-heavy analysis doc. Someone busy or non-technical (a boss, a PM, a client) needs to understand it. A raw markdown dump won't land. A marketing-y summary they won't trust.
show-and-tell produces a single self-contained HTML page that explains the work in plain English, using one everyday metaphor carried all the way through — including the bad news. It's the kind of report someone forwards and the recipient actually reads.
The proven recipe:
| Ingredient | Why it matters |
|---|
| 🎯 One metaphor, held all the way through | A retrieval system → a robot librarian who finds the right card. "Finds it half the time / shouts on every step" → a librarian who's right half the time but interrupts constantly. The metaphor is the scaffold the non-expert hangs everything on — so it has to carry the limits too, not just the wins. |
| 🔢 The real number beside every plain claim | Not "it works pretty well" — "finds the right answer about half the time" and the ~51% bar. Plain words carry the meaning; the number carries the credibility. Honest, not dumbed-down. |
| 🛠️ "Engineer's note" asides | A muted layer with the precise mechanism / metric name / exact method. The lay reader's eye skips it; the technical reader drops in. One document, two audiences. |
| ⚖️ A foregrounded honesty box | "Here's what we're NOT sure of" gets its own box, not a footnote. Small sample, floor-not-ceiling caveats, the unmeasured bits. This is what separates a translation from a sales pitch. |
| 🕹️ A cute arcade/pixel aesthetic | Dark bg, neon bars, fairy-dust palette, animated fills. Opens straight from file:// — no build step, no server, no dependencies. Just open it. |
| 🎨 Three reader-switchable themes | A 🎮/📄/🌌 toggle (top-right; it remembers the choice): arcade (default), a print-friendly paper light theme, and midnight. Forward it to a boss who likes light mode; print it clean. |
| 🔎 A bundled fact-verifier | Translation drifts. A separate verifier (references/fact-verifier.md) checks every plain claim, number, and the metaphor against the technical source — number-binding, magnitude/causal/metaphor drift, omissions — and fails loud when it can't find the basis. Reduces drift; doesn't replace a human skim. |
It ships a proven HTML template (assets/template.html) you copy and re-bind, plus a render-safety checker (scripts/check_html.py) that catches the silent "half the page is invisible" CSS-variable bug before anyone opens it.
🖼️ About the demo (shown above)
