Lesson-Deck-Builder

What it is

A skill is a folder of instructions and files that Claude reads when a task needs it. This one teaches Claude to build lesson decks: slide-style web pages that explain a topic step by step, like a good teacher at a notebook or a blackboard.

You describe what you want to learn or present. Claude asks a few short questions, plans the lesson, fills slides from a ready-made library, checks the file, and hands you one .html file. Double-click it and it opens in your browser. Send it to anyone; it needs nothing else installed.

Install

The skill is the folder lesson-deck-builder/ inside this repository. Put that folder where Claude looks for skills.

Option A — Claude Code (all your projects)

Clone the repository, then copy the skill folder into your personal skills folder, ~/.claude/skills/.

git clone https://github.com/MstrPxl/lesson-deck-builder.git
mkdir -p ~/.claude/skills
cp -r lesson-deck-builder/lesson-deck-builder ~/.claude/skills/

git clone https://github.com/MstrPxl/lesson-deck-builder.git
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse lesson-deck-builder\lesson-deck-builder "$HOME\.claude\skills\"

You should now have ~/.claude/skills/lesson-deck-builder/SKILL.md. Start a new Claude Code session and the skill is ready.

Option B — Claude Code (one project only)

Copy the same folder into the project instead: <your-project>/.claude/skills/lesson-deck-builder/. Anyone who clones that project gets the skill too.

Option C — Claude apps (claude.ai, desktop)

1. Download lesson-deck-builder.zip from the latest release. (Or zip the lesson-deck-builder/ folder yourself: the zip must contain that folder, with SKILL.md inside it.)
2. In Claude, open Settings → Capabilities, make sure code execution is on, and upload the zip under Skills.
3. Start a new chat and ask for a lesson. In the apps the skill runs in chat mode: one complete deck per request.

Check that it works

In Claude Code, type /lesson-deck-builder (the skill also starts by itself when you ask for "slides", "a deck", "a lesson" or "a visual walkthrough"). Claude should answer with questions about your topic, not with a deck. That is correct: the questions come first.

Your first deck

Just ask in plain words. Any of these works:

A typical conversation

1. You ask

   You/lesson-deck-builder Make slides explaining how vaccines work.

2. Claude maps the topic and asks you to confirm it

   ClaudeHere are the nearby topics: how a vaccine trains your immune system · the main vaccine types · how vaccines are tested · herd immunity. I'll restate your aim: "understand how one shot teaches the body to fight a germ it has never met". Is that right?

3. Claude asks the canvas and the language

   ClaudeCanvas? I suggest Paper (bright, good for daytime reading) · or Chalkboard. And: Arabic or English?

4. A short intake

   ClaudeWho is it for (complete beginner · generally informed · expert), and how long (≈10 · 20 · 30 min)?

5. Claude plans, builds and checks

   It sketches the slide list, fills slides from the component library, and runs validate.py.

6. You get one file

   vaccines.html. Open it in a browser; use the arrow keys, the Prev/Next buttons, or swipe. Ask for changes any time: "make it chalkboard", "shorter", "add a slide on boosters".

Prompt builder

Pick your options and copy a ready prompt.

How a session goes

Claude follows the same steps every time. Knowing them helps you answer quickly and know what to expect.

1. Detect the environment

   Repo mode (Claude Code, inside a folder) or chat mode (the Claude apps). It changes where lessons and notes are kept. More below.

2. The topic conversation (required)

   Every new learning journey starts here. Claude assumes you know nothing, lists the topics near what you said (with one plain line each), and asks you to confirm one topic or one exact learning aim. Even a precise request gets restated and confirmed. Nothing is built before you say yes.

3. The canvas gate (required)

   Paper or chalkboard; on the chalkboard, which of the six boards. Claude suggests one with a one-line reason, always shows the full menu, and never picks for you. See the boards.

4. The language (required)

   "Arabic or English?" Asked every time unless you already said it. It sets direction, fonts, button labels and arrow keys.

5. Scope (broad subjects only)

   If you could spend weeks on the subject ("DevOps", "personal finance"), Claude offers three ways in: an Overview deck (at most ~30 minutes), a Roadmap + Lesson 1, or a Deep dive on one subtopic. Narrow topics skip this.

6. Intake

   One quick round: the angle, the audience level (default: "a newcomer gains real understanding"), and the length (default ≈20 minutes).

7. Plan the outline

   Claude chooses the arc (teaching or presentation), turns the time budget into a slide count, and names each slide's teaching job before choosing its component.

8. Set up from the template

   Copies assets/template.html, sets dir/lang, fonts, nav labels and the canvas attributes. The engine script is never edited.

9. Build the slides

   A visual on every slide that earns one, text in HTML and shapes in SVG, staggered entrances, logical CSS properties so both directions mirror correctly, one idea per slide.

10. Validate, then present

    Runs scripts/validate.py, fixes what it flags, and delivers the file with a short note: what was made, how to move through it, and what you can ask to change.

Two kinds of deck

If your request could be either, Claude asks one question. When a deck explains a concept and nobody said otherwise, it is treated as a teaching deck.

Canvases & boards

There is one style, Sketchbook, on two canvases: bright paper, or a chalkboard in one of six boards. Click a card to repaint this whole page with it (the dots in the top bar do the same).

One attribute pair decides it

In a deck, the canvas is set on the <html> tag and every colour follows. This page right now is:

<html data-canvas="paper">

data-canvas="chalkboard" without a data-board gives the default board, Slate re-inked. Never hand-edit a board's colours inside a deck: pick a board.

Language & direction

Layouts use CSS logical properties (margin-inline, inset-inline-start…), so everything mirrors by itself, including the notebook's red margin line. Bilingual lessons (say, English taught with Arabic support) pick one base language for direction and fonts and mix the other inside the content, using less of the support language as the level rises.

The teaching method

Teaching decks are designed to turn information shown into capability gained. Four ideas do most of the work.

1 · Attempt before instruction

Right after the cover, the reader meets a real problem and commits to an answer before any teaching. People learn most from the gap between what they expected and what turned out true. The problem is pitched attemptable but uncertain: you should have a guess and not be sure of it. At the end, the deck returns to the exact same problem (never a similar one) and solves it with what was just taught.

2 · The click trio

Every load-bearing idea gets all three, woven together. Two out of three is a definition, not understanding.

3 · Close every loop inside the deck

Each teaching deck delivers at least one complete, demonstrated capability in one sitting. "More next time" with no win is a failure: the content is split across decks rather than the payoff postponed. The recap is phrased as capabilities: "you can now…".

4 · Feedback is data, never judgment

A wrong answer gets the mechanism-level reason right away and a chance to apply it again. No scolding, no "unfortunately", no padding. And progress is always visible: roadmaps mark finished steps, and a concept missed last time and solved now is named on the slide.

The calm voice

Questions & the adaptive loop

Every teaching deck ends with a short question set and a copyable answer box. In a series, this is how the next lesson knows what to build on.

How the next lesson adapts

The notes file

NOTES.md is written by Claude and read before every lesson. It stays small: a header (subject, roadmap version, date), a live picture (active gaps with the question that found them and the lesson that will re-test them, strengths, what kinds of explanation landed), a per-lesson log of a few lines each, and closed gaps. Single data points only tune tone and examples; only repeated patterns can justify a proposal.

Chat mode, repo mode, roadmaps

Repo mode layout

On a new journey Claude creates only what is missing, and never touches files that aren't its own:

If the folder is a git repository, Claude commits after each artifact ("lesson 03: transformers — attention", "notes: lesson 02 answers").

Scope: narrow topic or broad subject?

Rule of thumb: could a person spend weeks learning this? If not, it's narrow: one deck. If yes, you choose:

Roadmap mode, step by step

1. Shape the journey

   2–3 quick questions: hands-on · theory-first · balanced; with or without a business lens; job-ready · solid mental model · general literacy. These change emphasis and order, never correctness: no load-bearing step is dropped.

2. Research the path

   Real web searches, so the order is right and nothing is outdated or missing. This is research about what to learn and in what order; deep research on each subject waits for its lesson.

3. Roadmap deck + spec

   lessons/00-roadmap.html shows every phase, why it's there and how it connects. The machine-readable spec goes in docs/ROADMAP.md (repo mode) or a hidden comment in the deck (chat mode).

4. Lesson 1

   Introduction, big picture and why, with a roadmap slide near the front: current step highlighted, finished steps marked.

5. Every later lesson

   Load the roadmap → read NOTES.md (save any new answer block first) → re-check the roadmap is still current → propose a change only if the notes justify it → research and build the lesson, personalized → write the state back and commit.

{"subject":"Machine learning","version":2,"updated":"2026-10-16",
 "shape":{"style":"balanced","business":"no","destination":"working mental model"},
 "steps":[
   {"n":1,"title":"What learning from data means","goal":"…","volatility":"solid",
    "research":"angles, sources and freshness checks to run when building this lesson"},
   {"n":4,"title":"Tooling: notebooks and libraries","goal":"…","volatility":"fast","research":"…"}],
 "changelog":[{"v":2,"date":"2026-10-16","cause":"research","change":"library X replaced Y as the common default"}]}

Why volatility? Lessons are often taken days or weeks apart, and fields move. Before every lesson Claude re-checks the roadmap: "fast" steps (tools, practices) get re-researched, "solid" steps (fundamentals) a light check. Every change bumps version and adds a changelog entry whose cause is either research (applied by Claude) or approved-proposal (applied only after your yes).

The slide engine

Every deck carries the same small script (no libraries). It is copied from the template and never edited; new behaviour goes after it.

Moving through a deck

A progress bar and a slide counter show where you are. Keys and swipes are ignored while you type in a field (the answer box) or work a widget marked data-capture (sliders, drag figures).

Anatomy of a slide

<!-- the first slide, and only the first, is "slide active" -->
<section class="slide active"> … cover … </section>

<section class="slide">
  <!-- .reveal: animates in when the slide opens; --d staggers it -->
  <h2 class="reveal" style="--d:.1s">How a request finds a server</h2>

  <!-- data-build: appears one key-press at a time before the page turns -->
  <div data-build="1">1. Your browser asks a resolver.</div>
  <div data-build="2">2. The resolver asks the root.</div>
  <div data-build="3">3. The answer comes back.</div>

  <!-- data-capture: the engine leaves keys and swipes here alone -->
  <input type="range" data-capture>
</section>

const s = document.querySelector('#dns-slide');
s.addEventListener('slideenter', () => startDrawing(s));
s.addEventListener('build', e => moveToken(e.detail.step, e.detail.of));

Component library

43 copy-paste building blocks. Every one follows the canvas, the board and the language automatically, and lists the teaching jobs it suits, best fit first. These rankings are suggestions, not rules: a deck where every slide uses its "rank 1" component looks templated.

Core slides §1–§21Figures & interaction §22–§31 (v1.2)Skeletons & ported mechanics §32a–l

Core slides

Figures & interaction (added in v1.2)

Skeletons & ported mechanics (§32)

Behaviour without a fixed picture. The drawing ("skin") is invented fresh for each topic; working code is in assets/style-samples/sketchbook-kit.html.

See them live: open the Mechanics kit tab in the demo at the top of this page.

Teaching jobs

Before choosing a component, Claude names what each slide must do. There are 19 jobs. Each one is explained once in use-cases.md with everyday, lecture and tech examples, a "spot it when" line and a reverse index of components.

1. For each planned slide, name its job in one phrase from the list.

2. Open that job's entry and read its reverse index (best fit first).

3. Choose a component, usually near the top, checked against the content and against what the neighbouring slides already use.

The "Spot it when" lines double as a classifier when converting lecture slides: they describe what a source slide doing that job usually looks like.

Style laws

Five laws apply to every deck. They keep decks calm, readable and consistent.

Drawing vocabularies

Ways to represent a mechanism, kept from the retired styles and drawn in ink or chalk:

The style file also maps eight content categories (definitional, process, intuition, comparison, narrative, code, thesis, check) to their visible layer, depth mechanic and signature component, and ends with a pre-ship checklist every deck is graded against.

Length budget

A reader spends about 60–90 seconds per slide. Claude turns your time budget into a slide count and stops there; if the topic needs more, each slide gets tighter, not the deck longer.

In teaching decks, the opening challenge, the challenge revisited and the question set count inside this budget: they replace content slides, they are never added on top.

Validator & scripts

Two small Python 3 scripts, no packages to install.

validate.py — check a finished deck

python lesson-deck-builder/scripts/validate.py examples/isy-05-cryptography.html

slides: 30   ·   implied reading time ≈ 30–45 min
⚠ more than 20 slides — likely over a 30-minute calm budget; consider tightening
✓ clean.

✗ lines are problems (exit code 1); ⚠ lines are notes. It checks:

HTML comments are stripped before checking, so notes and records inside comments never cause false alarms.

use_cases.py — for people editing the skill

Keeps the components' "Suggested for" lists and the use-case catalogue in sync. Run it after changing either file.

python lesson-deck-builder/scripts/use_cases.py           # check only
python lesson-deck-builder/scripts/use_cases.py --write   # regenerate the reverse indexes, then check

Windows tip: if the console can't print ✓ or ·, set PYTHONIOENCODING=utf-8 first.

Hard rules

Failure modes the skill always avoids. Useful when you edit a deck by hand, or review one.

The rulebooks

Two optional companion files for one specific, demanding job: turning university lecture slides (PDF or PPTX) into a deck that a student can study instead of the slides, ending with a self-marking quiz. You attach them to your request; they add to the skill and, where they say so, override it.

How to use them

First deck of a course — attach the two rulebooks, deck-tools.zip and the lecture file, then send:

/lesson-deck-builder
Follow slides-rulebook.md for the attached lecture, and end the deck with a final quiz following questions-rulebook.md. Read the attached notes before planning.
This is the first deck of a new course: ask me the canvas and board before building.

Later decks of the same course — also attach the newest deck of the course (its code and choices are reused):

/lesson-deck-builder
Follow slides-rulebook.md for the attached lecture, and end the deck with a final quiz following questions-rulebook.md. Read the attached notes before planning. The newest deck of this course is attached.

Quiz only — for any existing deck: Add a final quiz to the attached deck, following questions-rulebook.md.

The attachments decide the case: A first deck of a course (asks the canvas gate and exam focus once), B a later deck (reuses the newest deck as the "shell" and asks only what's new), C decks of another course attached (settings don't carry over).

The six goals of the slides rulebook

When rules conflict: correctness first, then completeness, then the 2 × word ceiling, then ease of understanding, then teaching method, then style. Completeness and the ceiling are both hard limits: extras are cut to meet the ceiling, and if the facts alone wouldn't fit, Claude asks you.

Where the extra words go

The room between the source's word count and the ceiling is spent in this order, and cut from the bottom up when a deck runs long:

1. Plain words and full sentences, even when they're longer than the slides' wording.
2. A concrete example for every key idea, and a worked example for every procedure, calculation or piece of code.
3. The "why": the mechanism in a sentence or two.
4. Help where it's needed: visible glosses, a plain reading beside every exact quote, background the slides assume.
5. The common mistake, named and corrected.
6. A second example or an analogy, only for ideas students often find hard.

Never padding, repeats or decorative stories: the ceiling is a limit, not a goal.

What's inside each file

Records kept inside each deck

Rulebook decks carry their own paper trail as HTML comments (invisible, ignored by the validator):

Worked example: a real lecture deck

Lecture 5 of an information-security course (Cryptography), built with the skill and both rulebooks. It is the fifth deck of its course, so it reused the newest earlier deck as its shell.

Things to try

The validator's "more than 20 slides" note is expected here: the slides rulebook makes one deck per lecture and measures its length in words, not slides. The deck quotes the lecture's definitions word for word (rule F2); those quotations belong to their original authors.

Repository layout

Claude reads SKILL.md first and opens the reference files only when a step needs them, so the large files don't slow small requests down.

FAQ

Contributors & license

Ali AlQahtani · @MstrPxlCreator and maintainer of the skill and the rulebooks.

✳

Claude · by AnthropicCo-author: worked on the skill, the rulebooks and this documentation with Ali.

Versions

Full details: the skill's CHANGELOG.md and the rulebooks changelog.

Contributing

Issues and pull requests are welcome. If you change the skill: keep SKILL.md and the references consistent, run scripts/use_cases.py after touching component lists or use cases, run validate.py on the template and exemplars, and add a CHANGELOG.md entry.

License

The skill, rulebooks and this site are released under the MIT License. The example deck quotes definitions from its source lecture; those quotations remain their authors'.