step-animation
把任何学习材料(一段讲义或文章的文字、一个概念或公式、一个流程、一段代码或算法、一份文件如 .md/.pdf/.docx/.pptx/.txt/.csv)做成一个独立的「分步动画」HTML 网页:用小的数字格子演示数据,数字从输入格子飞到结果格子,橙框标正在读、蓝框标正在写,每一步显示对应的原文句子/公式/代码行和一句大白话,自动播放、可暂停/上一步/下一步/调速。当用户说「用动画讲给我听」「做成分步演示」「这个我看不懂,一步一步演示」「把这个讲义/这份文件做成动画网页」或者要把学习内容可视化成逐步动画时使用。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/rinta13795--step-animation-skill)HTML
<a href="/listings/rinta13795--step-animation-skill"><img src="/api/listings/rinta13795--step-animation-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires [Node.js](https://nodejs.org/) 18+. The self-check and screenshot tools also need Chrome or Edge installed.
# install as a personal skill (available in every project) git clone https://github.com/Rinta13795/step-animation-skill ~/.claude/skills/step-animation cd ~/.claude/skills/step-animation npm install # only puppeteer-core, for the headless self-check and screenshots
On Windows PowerShell, use `$HOME` instead of `~`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 107 lines
- ---
- name: step-animation
- description: 把任何学习材料(一段讲义或文章的文字、一个概念或公式、一个流程、一段代码或算法、一份文件如 .md/.pdf/.docx/.pptx/.txt/.csv)做成一个独立的「分步动画」HTML 网页:用小的数字格子演示数据,数字从输入格子飞到结果格子,橙框标正在读、蓝框标正在写,每一步显示对应的原文句子/公式/代码行和一句大白话,自动播放、可暂停/上一步/下一步/调速。当用户说「用动画讲给我听」「做成分步演示」「这个我看不懂,一步一步演示」「把这个讲义/这份文件做成动画网页」或者要把学习内容可视化成逐步动画时使用。
- ---
- # 分步动画学习网页
- 给一段学习材料,生成一个**独立的 HTML 文件**(双击就能打开,不联网),让学习者一步一步看懂。
- 材料**不限于代码**:讲义或文章里的一段话、一个概念(复利、梯度下降、TCP 握手)、一个公式、一个流程、一份文件都可以——只要里面有「一步一步发生的变化」,就能拆成动画。
- 效果:小格子里的数字 → 飞到结果格子;橙框 = 正在读,蓝框 = 正在写;底下是当前代码行 + 一句大白话;自动播放,停留时间按说明文字长短算;← → 翻步,空格暂停。
- 本目录:
- - `engine/engine.js`、`engine/engine.css`:引擎(格子、框、飞行数字、指针、变量面板、表格、折线图、播放器、自检)。**不要改引擎来适配某一节课**,课程里的东西都写在课程文件里。
- - `build.mjs`:把「课程文件 + 引擎」拼成一个独立 HTML。
- - `check.mjs`:无界面打开网页的 `?check` 模式,每一步都跑一遍,打印问题。
- - `tools/snap.mjs`:给指定的步骤截图,用来自己看一眼效果。
- - `template/lesson.js`:课程文件骨架,从这里开始写。
- - `reference/api.md`:引擎全部函数的说明(写课程前读一遍)。
- - `examples/`:`compound-interest.lesson.js`(复利,**输入只有一段文字、没有代码**)、`binary-search.lesson.js`(二分查找,含图表)、`bubble-sort.lesson.js`(冒泡排序,含交换动画)、`sliding-window.lesson.js`(滑动窗口)。写新课程前至少看一个和材料类型接近的。
- ## 流程
- ### 0. 拿到材料
- - 用户直接贴的文字、代码:直接用。
- - 给的是文件:先完整读一遍。.md/.txt/.csv/代码文件直接读;.pdf/.docx/.pptx 用能读这些格式的工具或 skill 读出文字(扫描版 PDF 先 OCR)。材料很长时,先列出里面的知识点让用户挑要做哪几个,或者按章节一节一节做。
- - 材料里有数据(表格、CSV、实验结果):把要用的数据直接写成 JS 数组常量放进课程文件。
- - 先判断材料里**什么在一步一步变化**:代码是变量和数组;概念讲解里通常是数量(钱、温度、概率)、状态(排队的人、网络包)、或者一张表格。演示的就是这个东西怎么变。
- ### 1. 读材料,拆成「节 → 步」
- - **节**(上方标签)= 一个独立的小知识点:一个函数、一个循环、一张图怎么读。第 0 节通常讲「数据长什么样」(比如「图片就是一张数字表格」「列表就是一排格子」)。
- - **步** = 一个动作:一次读取、一次计算、一次比较、一次写入。一步只讲一件事。
- - 循环:一轮里有几行**有新东西**的代码,就拆成几步(比如「更新 s」「更新 best」是两步)。轮数多时,前 1~2 轮细拆,后面每轮合成一步;再多就「……一直重复……」直接跳到关键的一轮。
- - 一节 3~15 步比较合适。整个网页 3~10 节。
- - 最后一节可以是「读图 / 看结果」:嵌入真实数据画折线图,回答材料里的问题。
- ### 2. 先用 JS 把材料里的计算真的跑一遍
- 网页上出现的每一个数字都要是**算出来的**,不要手填。做法:在课程文件里用 JS 实现同样的算法,记下 trace(每一步的中间值),再按 trace 生成步骤(见 `examples/binary-search.lesson.js` 的 `trace()` 和 `searchScene()`)。要嵌入真实数据(CSV、实验结果)时,把数据直接写成 JS 数组常量放进课程文件。
- ### 3. 选演示用的小数据
- - 用**很小**的数据:图片用 3×4、4×4 的表格,数组 5~12 个数。真实规模写在说明里(「真实是 8 行 9 列,这里用 2 行 4 列演示,道理一样」)。
- - 数字要挑得**好算、能看出规律**:比如 10、20、200 而不是 137、59。
- - 舞台宽度大约 900px:一排格子 × 格子边长不要超过 ~850px(12 格 × 54px 正好)。
- ### 4. 写每一步的 `c`(代码)和 `p`(说明)
- - `c`:这一步对应的**原文**。材料是代码时,就是正在执行的那一行(或几行)代码,原样照抄;可以在后面用 `→` 或 `#` 写出这一步的结果,比如 `'img[0, 2] → 200'`。
- 材料是文字、概念或文件时,写这一步对应的**原文那句话**(用「」括起来)、公式或规则,比如 `'「每年的利息会加进本金,下一年连利息一起生利息」'`、`'本金 × (1 + 10%)'`(见 `examples/compound-interest.lesson.js`)。
- - 代码是一个完整函数/循环时,给这一节写 `code: '整段代码'`,然后每步的 `c` 写**行号**(从 1 数),比如 `c: [5, 7]`,网页会显示整段代码并高亮这几行。
- - `p`:**一两句大白话**,说清「这一步在干什么、得到了什么」。规则:
- - 不堆术语;必须出现的术语,后面马上用大白话解释一次。
- - 学习者懂 Java / C:能类比就类比(「相当于 C 的 `unsigned char img[3][4]`」「append = Java 的 `list.add`」「`//` 是整除,和 Java 两个 int 相除一样」)。
- - 写出具体的数和算式:「(10 + 10 + 10 + 10) ÷ 4 = **10**」,比「求平均」好懂得多。
- - 用 `<b>…</b>` 标出这一步最关键的几个字(显示成橙色),`<code>…</code>` 标代码。
- - 说明里的数字用模板字符串从 trace 里取,不手写。
- - 停留时间自动按 `p` 的长度算(4 秒 + 每字 70ms)。动画本身很长(比如画一条 2.5 秒的折线)时加 `wait: 2500`。
- ### 5. 写每一步的 `run(S)`
- - `build()` 只搭舞台:创建格子、结果框、图表,`stage.appendChild(...)`,返回一个对象 `S`。
- - `run(S)` 只写**这一步的变化**(增量)。引擎翻到第 k 步时,会先重新 `build()`,再瞬间重放第 0 ~ k−1 步,再带动画播放第 k 步——所以每一步不需要也不应该重画前面的结果。
- - 动画写法:
- - 读哪些格子 → `frame('a', CO, 格子们)`(橙框);写哪个格子 → `frame('b', BL, 格子)`(蓝框)。同名框会平滑移动过去。
- - 数字移动 → `fly(从, 到, '文字', () => 到达后要 set 的值)`。**结果一定在 `then` 回调里 set**,不要只在 `setTimeout` 里 set。
- - 多个数先后飞 → 给 `fly` 传 `delay`,或用 `T(fn, 毫秒)`;**不要直接用 setTimeout**(瞬间重放时 `T` 会立即执行,setTimeout 不会)。
- - 指针(lo / hi / i / j)→ `mark('lo', 格子, 'lo', BL)`;同一格子上多个指针会自动错开,grid 要加 `below: 行数` 留位置。
- - 图表:`chart({...})` 创建,`C.line(xs, ys, 颜色)` 画线(会逐渐画出来),`C.text(x, y, '标注')` 写字:会自动上下挪,躲开其他文字、圆点和**已经画好的**曲线,并拉回边界内。所以先画线、再写标注;标注写在线的后面一步也行。
- - 详细函数表见 `reference/api.md`。
- ### 6. 生成网页
- ```bash
- node <本目录>/build.mjs 你的课程.lesson.js [输出.html]
- ```
- 课程文件放在用户的工作目录里(不要放进本 skill 目录),输出的 HTML 和它放在一起。
- ### 7. 自检(必须做,不能跳过)
- 自检会把**每一节的每一步**都跑两遍:瞬间模式查布局,带动画(8 倍速)查回调报错和「动画播完的画面和瞬间重放是否一致」。会报告:
- - `报错`:JS 异常(包括动画回调里的);
- - `标注重叠`:文字标签、格子、指针、图表文字互相压住;
- - `标注压住圆点` / `标注压线`:图表文字压在圆点、圆圈或曲线上;
- - `超出画布` / `超出图表`:东西伸出舞台或 SVG,被裁掉看不见;
- - `框没对准`:框或指针没有对准它要指的格子;
- - `文字撑出格子`:数字太长,格子装不下;
- - `重放不一致`:只在动画里 set、瞬间重放时没 set 的值(会导致按「上一步」时画面不对);
- - `缺内容`:某一步没有 `c` 或 `p`、某一节 `steps` 是空的,或者课程文件有语法错误(这时一节都读不到)。
- 怎么跑(任选一种):
- - **有 Node 和 Chrome/Edge**:`node <本目录>/check.mjs 输出.html`(退出码 0 = 通过),再加 `--width 760` 跑一次窄屏。
- 如果它报「缺少 puppeteer-core」,在本 skill 目录运行一次 `npm install`(这是唯一需要在 skill 目录里做的改动)。
- - **有浏览器工具**(如 Claude 的内置浏览器):打开 `file:///…/输出.html?check`,等页面顶部出现「✅ 自检通过」或「❌ 自检发现 N 个问题」;也可以执行 JS 读 `window.__CHECK__`(`{ok, steps, problems}`)。
- - **都没有**:告诉用户用浏览器打开 `输出.html?check` 看顶部报告。
- 有问题就改课程文件 → 重新 build → 重新 check,直到通过。然后**再截几张图自己看一眼**:
- ```bash
- node <本目录>/tools/snap.mjs 输出.html 截图目录 0:1 1:5 3:2 [--width 760]
- ```
- `节:步` 里,节 = 上方标签从左数第几个(最左边是 0,不管标签上写的是「0」还是「①」);步 = 网页右下角「第 k / n 步」的 k。比如「① 找 77」是第 2 个标签,它的第 5 步写 `1:5`。
- 自检查不出「数字算错」「说明和画面对不上」「看起来挤」这类问题,要靠截图看。
- ### 8. 交付
- 告诉用户 HTML 的路径、一共几节几步、自检结果。不要在网页里放真实的个人信息、公司名、内网地址或真实监控画面;演示数据用编出来的小数字。
- ## 常见坑
- - `build()` 里不要调用 `fly`/`frame`/`mark`:那时元素还没布局好。
- - 改格子、结果框、变量、表格的内容,一律用 `G.set` / `valBox.set` / `vars.set` / `table.add`,不要直接改 `textContent`:引擎靠这些函数知道布局变了,好让框和指针跟着挪。
- - 课程代码会被包在自己的作用域里运行,起什么变量名、函数名都不会和引擎冲突;`LESSON` 会被自动交给引擎。
- - 每步的 `run` 里的 `if (!INST)` 分支只能放纯装饰(比如额外的飞行效果),不能 set 任何最终状态。
- - 一个格子里的文字很长(比如 16 位哈希)→ 用 `valBox` 并设置 `{w: 宽度, fs: 字号}`,或者截短显示。
- - 横轴最右边的刻度文字和轴名字会挤:引擎已经把轴名放在刻度下面居中。自己加的标注先交给 `C.text` 自动避让;如果自检还报重叠/压线(比如曲线很密、没空地方),再手动换一个空白处的坐标。
- - 二维数据:`grid([[...],[...]])`;一维:`grid([...])` 也可以,取格子用 `G.c(列)` 或 `G.c(行, 列)`。
README.md · README · 109 lines
- # step-animation: turn anything you're learning into a step-by-step animation
- **English** | [简体中文](README.zh-CN.md)
- A [Claude Code](https://claude.com/claude-code) skill. Give it **any learning material** — a paragraph from lecture notes or an article, a concept or formula, a process, a piece of code or an algorithm, or a whole file (.md / .pdf / .docx / .pptx / .txt / .csv) — and it builds a **single standalone HTML page** (double-click to open, works offline) that walks through it one step at a time:
- - Data is drawn as small **grids of numbers** (an image is a table of numbers, an array is a row of cells)
- - Numbers **fly** from the cells being read into the result cell
- - **Orange frame** = cell being read, **blue frame** = cell being written; frames glide from step to step
- - Every step shows the **source line** it explains (the sentence from the notes, the formula, or the line of code) plus a **plain-language** caption
- - Autoplays, pausing longer on longer captions; pause, previous, next and speed controls, plus ← → and Space on the keyboard
- - Real data can be embedded as line charts that **draw themselves**, with labels that automatically avoid overlapping
- 
- > The bundled examples and the generated pages are in Chinese (the author's language); the engine and the skill work with material in any language.
- ## Why
- Whether it's code in a language you don't know well, or a sentence in your notes like "the interest is added to the principal, so next year the interest earns interest too", reading text alone rarely lets you *see* what actually happens. Shrink the data to a handful of cells, make every step visible, and it clicks. This skill turns that teaching style into a repeatable workflow: Claude splits the material into steps, writes the captions, builds the page, and **checks every single step** for errors and overlapping labels before handing it over.
- ## Examples
- | **Compound interest** (input is just a paragraph of text, no code) | **Compound interest**: the gap over 30 years |
- |---|---|
- |  |  |
- | Binary search (found / not found / why it's fast) | Bubble sort (compare neighbours, swap) |
- |  |  |
- | **Charts from real data** | **Sliding window** (written by a fresh Claude that had only read SKILL.md) |
- |  |  |
- Download any `.html` in `examples/` and open it in a browser. Full demo video: [docs/demo.mp4](docs/demo.mp4).
- ## Install
- Requires [Node.js](https://nodejs.org/) 18+. The self-check and screenshot tools also need Chrome or Edge installed.
- ```bash
- # install as a personal skill (available in every project)
- git clone https://github.com/Rinta13795/step-animation-skill ~/.claude/skills/step-animation
- cd ~/.claude/skills/step-animation
- npm install # only puppeteer-core, for the headless self-check and screenshots
- ```
- On Windows PowerShell, use `$HOME` instead of `~`.
- ## Usage
- Just ask Claude Code:
- > Use step-animation to walk me through this step by step: (paste notes, a concept, or code)
- > Use step-animation to turn the gradient descent part of `chapter3.pdf` into an animation
- or type `/step-animation` followed by your material. Claude will:
- 1. Read the material (extracting the text from files first), find what changes step by step, and split it into **sections → steps** (one idea per section, one action per step);
- 2. **Actually run** the calculations in JS, so every number on the page is computed, not typed in;
- 3. Write a lesson file `xxx.lesson.js` and build a standalone page with `build.mjs`;
- 4. Run the self-check over **every step** with `check.mjs`, fixing and re-running until it passes;
- 5. Take a few screenshots to eyeball the result, then hand it to you.
- You can also write lessons by hand:
- ```bash
- cp template/lesson.js my.lesson.js # start from the skeleton
- node build.mjs my.lesson.js # -> my.html
- node check.mjs my.html # self-check (add --width 760 for narrow screens)
- node tools/snap.mjs my.html shots 0:2 1:1 # screenshots: section (leftmost tab = 0) : step (the "k" in "step k / n")
- ```
- ## What the self-check catches
- Open `page.html?check` in a browser, or run `node check.mjs page.html`. Each step runs twice (instant mode + animated at 8× speed) and reports:
- | Problem | Meaning |
- |---|---|
- | Error | Any JS exception, including inside animation callbacks |
- | Overlapping labels | Text labels, cells, pointers or chart text covering each other |
- | Label on a dot / line | Chart text sitting on a dot or a curve |
- | Outside canvas / chart | Something sticks out and gets clipped |
- | Frame misaligned | A frame or pointer isn't on the cell it should point at |
- | Text overflows cell | A number too long for its cell |
- | Replay mismatch | The state after the animation differs from the instant replay (breaks the Previous button) |
- | Missing content | A step without source line or caption, an empty section, or a lesson file with a syntax error |
- ## Layout
- ```
- SKILL.md the skill: when to use it, how to read the material, split sections/steps, write source lines and captions
- engine/engine.js engine: grids, frames, flying numbers, pointers, variable panel, tables, line charts, player, self-check
- engine/engine.css styles (light and dark mode)
- build.mjs lesson file + engine -> standalone HTML
- check.mjs headless self-check
- tools/snap.mjs screenshot given steps
- template/lesson.js lesson skeleton
- reference/api.md engine API reference
- examples/ compound interest (plain-text material), binary search, bubble sort, sliding window (.lesson.js + built .html)
- promo/ scripts that made the demo video (screen capture, synthesized music, frame-by-frame render)
- docs/ screenshots, GIFs and the demo video used in this README
- ```
- ## How the engine works (for contributors)
- Each step only describes *its own change*. When you jump to step k, the engine rebuilds the stage → **instantly replays** steps 0…k−1 (with all animations and CSS transitions off) → plays step k **animated**. So previous/next/jumping between sections never gets out of sync, and lesson authors never have to think about restoring state. The "replay mismatch" check guards exactly this.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.