SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmath-explainer

math-explainer

Design & creation

View repository

Updated 10-16 05:49

About this skill

Math Explainer — Math explainer video + interactive web page generation

Turn a math/physics conceptsimultaneouslyinto two complementary products:

  • Explainer video(rendered to MP4 with Manim): linearly explain the "why" clearly, walking the audience through the main line of derivation.
  • Interactive web page(self-contained HTML): let the audiencedrag parameters themselves and see changes instantly, exploring the same concept hands-on.

By default, do both(unless the user explicitly wants only one of them). The two share the same design (same concept, notation, parameters, color scheme) and complement each other: the video is responsible for explaining clearly, the web page for exploring clearly.

Reference implementation:ManimCommunity/manim(This Skill is written based on Manim Community v0.20+).

Reminder for the executor:Strictly follow the stage order, do not skip steps. Each stage has "what to do / how to do it / how to self-check". If unsure about an API, go read references/manim-guide.md, do not write blindly from memory. Wherever you can render a still frame and look at it with your eyes, always look first before continuing.

0. Core principles (must-read, follow them)

  1. By default, produce both a video + interactive web page, and the twoshare the same design(concept, notation, parameters and value ranges, color scheme, key visuals). First define this "shared design specification" in the storyboard; both the video and the web page follow it, ensuring consistent look and symbols.
  2. Explain the "why", do not just show the "what" (highest red line). The audience mustwatch the conclusion being derived, rather than just presenting the conclusion and pretty graphics and calling it done. Smooth ≠ clear. Derivation/argumentation must account for ≥ 50% of the whole video. See references/pedagogy-and-storyboard.md §0, for proof examples see templates/example_pythagoras_proof.py。
  3. Design first, code later. Do not write code without a storyboard. See Stage B.
  4. One screen, one thing. Before moving to the next knowledge point, FadeOut away what is not needed from the previous screen.Never let elements overlap or drift off-screen.
  5. Ensure the effect even without visual capability (both video + web page have text-based checks). Do not rely on "adjusting by looking at the image".
    • Video: ① Use templates/mathviz.py 's SafeScene + fit_content()/arrange()/clear_screen() for mechanical typesetting; ② After rendering, search the log for [layout], confirm DONE 共发现 0 处; ③ Run check_text.py to prevent boxes. See manim-guide.md §3.5。
    • Web page: after writing, run check_web.py, must [PASS](check formulas/id/sliders/canvas/layout/JS syntax). If you have visual capability, you can additionally read PNGs / view in a browser for secondary confirmation; if not, you can still deliver based on the above text results.
  6. Use templates, don't write from scratch. Copy the skeleton in templates/ and modify it, which avoids 90% of low-level mistakes.
  7. When it fails, check the table first. When you get an error, first consult references/manim-guide.md 's "Common Errors Quick Reference", do not try things randomly.
  8. Self-check before delivery. For the video, confirm the MP4 exists and can play, and thatthe reasoning is understandable even with the narration covered; the webpage must be confirmed to open in a browser, formulas must render, and interactions must work.

1. Stage overview (copy this checklist first to track progress)

进度跟踪（默认两件产物都要做）：
- [ ] A. 明确需求（主题/受众/时长/语言/风格）—— 默认“视频 + 网页”都做
- [ ] B. 写分镜 storyboard.md，并在其中定下「共享设计规范」（概念/记号/参数+范围/配色/关键视觉）
- [ ] C. 准备环境（仅视频需要；运行 setup + check_env）
- [ ] D1. 视频：按分镜写 Scene → 静帧自检 → 完整渲染 → 验证 MP4
- [ ] D2. 网页：套用模板 → 按同一套设计填内容/交互 → 浏览器验证
- [ ] E. 交付（两件产物路径 + 如何查看 + 一致性确认 + 后续可调项）

Put all deliverables underthe same topic folder <主题英文短名>/ , for convenient bundled delivery.Place both finished products (webpage + video) in the root of the folder, so the user can find them at a glance when opening the folder:

<主题英文短名>/
├── index.html        # ← 交互网页成品（双击打开）
├── <SceneName>.mp4   # ← 讲解视频成品（render.sh 渲染后自动复制到这里）
├── storyboard.md     # 分镜 + 共享设计规范
├── scene.py          # 视频源码
└── media/            # Manim 渲染中间产物（可忽略，可不交付）

2. Stage A — Clarify requirements

First confirm the following items.For anything the user has not made clear, use reasonable defaults and explain them at delivery; do not repeatedly ask follow-up questions.

Dimension Key points Default value
Topic Specific to one concept/theorem/problem (e.g. "the area proof of the Pythagorean theorem") Must be clarified; if too broad, narrow it down
Format Video / interactive webpage / both Do both(default)
Audience Primary school / middle and high school / university / popular science Middle and high school
Duration/length Video recommended 30s–3min; webpage single page Video ~60–90s
Language Chinese / English (including subtitles and narration text) Follow the user's language (Chinese)
Style Dark background (default) / light; color scheme Dark + high contrast

Regarding "format": by default produce both a video + an interactive webpage; do not make the user choose one of the two. Only when the user explicitly says "video only" or "webpage only" should you make just one of them.

How the two divide the work (two sides of the same concept):

  • VideoCarries the main derivation line: explain "why it holds" step by step (the process of proof, transformation, limit approximation).
  • WebpageCarries hands-on exploration: turn the concept'svariable quantitiesinto sliders, so viewers can immediately see the changes (adjust slope/sample size/angle/parameter n…).
  • Almost any topic can be split this way: the video explains the principle clearly, and the webpage lets people play with the same set of parameters. If a topic really has no adjustable quantities, make the webpage a "step-by-step clickable" explanation (click once to advance one step).

3. Stage B — Write the storyboard script (the most important step)

Read references/pedagogy-and-storyboard.md（Be sure to first read §0 Fatal Red Lines and §7 Derivation Strategy Library), then copy templates/storyboard.md to the workspace and fill it in.

A qualified storyboard must include:

  • Learning objective: 1 question the viewer can answer after watching.
  • Shared design specification (shared by video and webpage, required)：
    • Core concept in one sentence; unified notation (e.g. uniformly use n、a/b/c, don't use k in the video and m in the webpage).
    • Interactive parameters + value range + step size(used by webpage sliders; in the video, the key values of these parameters are the shots).
    • Color scheme (background/primary color/secondary color/text); key visual elements (coordinate system range, reference curve, mechanism annotations, etc.).
  • Main derivation line (core, cannot be omitted): First select a derivation/proof path from §7, and break it into 3–6 atomic steps,each step corresponds to one logical advance of "because… therefore…", taking up more than half of the shots.
  • Shot list: For each shot, write clearly "① what is in the frame ② one sentence of narration/subtitle ③ what animation is used to cut to the next shot".
  • Ending: one-sentence summary + freeze the frame.

Hard gates for the storyboard (if not passed, rewrite; do not enter Phase D):

  • There is a clear main line of derivation, not "directly showing the conclusion".
  • Cover all narration, and the key steps of the reasoning can still be retold from the visuals alone.
  • Each step of the derivation can answer "on what basis does this step hold", with no logical gaps.
  • The shared design specification has been written clearly: notation is unified, interactive parameters and ranges are fixed (the video and webpage will share them).

Do not enter Phase D without a storyboard. The storyboard is the video and webpage'sshared"construction blueprint".

Write the storyboard as <主题英文短名>/storyboard.md, and both the video (D1) and the webpage (D2) must strictly follow it.

4. Phase C — Prepare the environment (needed for video; the webpage does not depend on it and can proceed in parallel)

The script is located in the project at .cursor/skills/math-explainer/scripts/. The following commands by defaultare executed in the project root directory。render.sh will automatically cd to the directory where the scene file is located, so the paths only need to be written correctly relative to the project root.

Execute in order,check the output at every step：

  1. Install (idempotent, skipped if already installed):
bash .cursor/skills/math-explainer/scripts/setup_manim.sh
  1. Health check (must all be OK to continue):
python3 .cursor/skills/math-explainer/scripts/check_env.py
  • If manim or ffmpeg is missing → go back to step 1 or install according to the error message.
  • If LaTeX shows unavailable → do not use MathTex/Tex, switch to Text + Unicode (see manim-guide.md under "How to write formulas when there is no LaTeX"). This is the pitfall that weak models most often fall into.

5. Phase D1 — Produce the video (Manim)

Read references/manim-guide.md(API discipline, layout, anti-overlap, old and new APIs, troubleshooting). Commonly used ready-made snippets are in references/manim-cookbook.md。

Execute step by step:

  1. Enter the topic folder <主题英文短名>/(already created in Phase B).
  2. Copy the skeleton: copy templates/scene_template.py to <主题>/scene.py, and copy templates/mathviz.py together to <主题>/(the scene needs from mathviz import ...). The skeleton is based on SafeScene, and already has built-in safe-zone layout,fit_content、title_bar/caption/clear_screen、frow, andautomatic layout checking。
  3. Fill in the Scene according to the storyboard: for each piece of content, first VGroup().arrange() then fit_content(); use title_bar()/caption()for titles/subtitles; before cutting shots clear_screen(); for symbols with subscripts use frow(). Colors and notationstrictly use the shared design specification。implement one or two shots first and then render for self-check; do not write it all in one go.
  4. Font glyph check (prevent boxes, must pass)：
python3 .cursor/skills/math-explainer/scripts/check_text.py <主题>/scene.py

Must [PASS]. If [FAIL] lists missing glyph characters (such as 'ₙ'), modify according to the prompt (change wording / use frow() to compose subscripts). 5. Layout self-check (key feedback loop, no vision required)：

bash .cursor/skills/math-explainer/scripts/render.sh <主题>/scene.py SceneName s
# -s 出静帧；construct 全程执行，SafeScene 会在日志打印 [layout] 检查结果

Search the output for [layout]: you must see DONE 共发现 0 处布局问题. If there is WARN 出界/文字重叠, fix it as prompted (fit_content() / clear_screen()), then render again, until there are 0. (If you have vision capability, you can additionally open the PNG for a second confirmation; if not, you can still judge from the [layout] text result.) 6. Full render(use low/medium quality for drafts, high quality for the final version):

bash .cursor/skills/math-explainer/scripts/render.sh <主题>/scene.py SceneName m   # m=720p草稿, h=1080p定稿
  1. Verify MP4：render.sh after rendering willcopy the finished video to the root directory of the topic folder <主题>/<SceneName>.mp4(side by side with index.html ). The script will print this path—confirm the file exists and its size is >0, and confirm in the render log that [layout] DONE 0 处。media/ is an intermediate artifact and can be ignored.

Multiple shots can be written as one long Scene (recommended, for coherent narration), or split into multiple Scenes rendered separately and then concatenated with ffmpeg (see cookbook). Prefer a single Scene.

Video quality baseline (self-check, go through item by item):

  • Clearly explained why: cover the narration and look only at the visuals; you should be able to retell the key derivation steps (most important; if not, redo it).
  • Derivation/argumentation accounts for ≥ 50% of the whole video, not an opening show of skill with the derivation glossed over.
  • check_text.py is [PASS](no boxes).
  • Render log [layout] DONE 共发现 0 处布局问题(no out-of-bounds/overlap).
  • Color contrast is sufficient; each screen stays long enough to finish reading the subtitles (caption()/self.wait() give enough), formulas are correct, and the ending has a freeze frame.

6. Phase D2 — Create an interactive webpage (companion to the video)

Read references/interactive-web-guide.md. Copy templates/interactive_template.html to <主题>/index.html。

Core principle: the webpage is the "playable version" of the video, not a separate project. Same concept, same notation, same color scheme; turn thethose parametersdiscussed in the video into sliders.

Execute step by step:

  1. Copy the template as <主题>/index.html. The template already includes:single-column centered layout (the interactive area is in the middle of the page, on the smaller side, interact first then explain), KaTeX formula rendering,<canvas> drawing, slider controls and redraw loop, dark theme.
  2. Interactive parameters follow the storyboard's "shared design specification": the quantities that change in the video (slope a, sample count n, angle θ…) → each corresponds to one slider, with consistent range/step.
  3. Implement the drawing function draw(): read the current parameters → clear the canvas → redraw. When a slider changes, call draw(). Also draw the "mechanism annotations" from the video (such as the point y=n at x=1) to reinforce the connection with the video.
  4. Write explanatory text + formulas: use the same explanatory wording and KaTeX formulas as the video; you may add a sentence like "To see the full derivation, watch the companion video."
  5. Color scheme consistent with the video: background/primary color/secondary color aligned with the shared design specification (the default dark theme is the same as the video).
  6. Automatic check without vision (must pass)：
python3 .cursor/skills/math-explainer/scripts/check_web.py <主题>/index.html

Must [PASS]. It checks: $ formula pairing, KaTeX is complete and called,getElementById all ids exist, sliders are bound to input events, canvas/draw chain, single-column centered + interact first then explain, JS syntax (when node is available). If there is [FAIL] , fix it as prompted until 0. 7. Secondary confirmation (optional when visual capability is available): View in browser (macOS open <主题>/index.html), confirm formula rendering, slider linkage, and no overflow. Without visual capability, rely on step 6 [PASS] and that's enough.

Webpage quality baseline: check_web.py is [PASS]; single file can be opened by double-clicking; formulas render correctly; at least 1 interaction that truly affects the graphics;single-column centered, interaction area in the middle with moderate size, interaction before explanation；notation/color scheme consistent with the video。

7. Phase E — Delivery

Give the user a brief delivery note,deliver both artifacts together, including:

  • Paths of the two artifacts (both in the topic folderroot directory, placed side by side for easy finding): video <主题>/<SceneName>.mp4 and interactive webpage <主题>/index.html, plus storyboard <主题>/storyboard.md。
  • How to use:first watch the video to understand the principle, then open the webpage to explore hands-on(use a player for the video; double-click the webpage or open <主题>/index.html）。
  • Consistency confirmation: the video and webpage use the same concept, same notation, same parameter range, and same color scheme (this is the key to a matched delivery).
  • What default values were used (audience, duration, style, whether Text was used instead of LaTeX).
  • Points that can be further polished (change color scheme, add voiceover narration, extend a certain shot, add more adjustable parameters or presets to the webpage).

Optional advanced (as needed, read references/manim-guide.md at the end): add real-person/TTS voiceover (manim-voiceover), add background music, export GIF.

8. Common errors quick reference (look here first, then consult the detailed docs)

Symptom Cause Handling
latex failed / No module named latex LaTeX not installed but MathTex/Tex Install LaTeX, or switch everything to Text(see manim-guide)
NameError: ShowCreation etc. Used old API Check the "old/new API comparison table" in manim-guide,ShowCreation→Create etc.
Rendered successfully but no video Used -s(only outputs images) or misspelled the Scene name Use render.sh to pass m/h; verify the class name
Elements overlap/fly off screen Didn't clear the screen, didn't lay out Before switching shots FadeOut; use .arrange()/.to_edge()/scale_to_fit_*
axes.get_graph error Old API Use axes.plot(func)
Chinese displays as boxes Font does not support Chinese Text("你好", font="PingFang SC")(mac) or switch to a system Chinese font
Rendering is very slow Used high quality for debugging For debugging use -s or l, only use h

For complete troubleshooting see references/manim-guide.md。

Resource index

  • references/pedagogy-and-storyboard.md — how to explain concepts clearly + storyboarding methods
  • references/manim-guide.md — Manim API discipline, layout, overlap prevention, old/new API, troubleshooting, advanced (voiceover/stitching)
  • references/manim-cookbook.md — copyable Scene recipes categorized by topic (coordinate systems/function graphs/geometric proofs/vectors/sequence limits/probability…)
  • references/interactive-web-guide.md — structure of self-contained interactive webpages, KaTeX, canvas, controls
  • templates/scene_template.py — Manim scene skeleton (based on SafeScene, centered on "derivation")
  • templates/mathviz.py — Guardrail module: SafeScene (automatic layout checking) + fit_content/title_bar/caption/clear_screen/frow (copy into the theme folder together with scene.py)
  • templates/example_pythagoras_proof.py — Golden example: truly proves the Pythagorean theorem (rearrangement/area method); read it before making derivation-type videos
  • templates/interactive_template.html — interactive webpage skeleton (single-column centered, interact first then explain)
  • templates/storyboard.md — storyboard script template
  • scripts/setup_manim.sh / scripts/check_env.py / scripts/render.sh — environment and rendering scripts
  • scripts/check_text.py — video font glyph check (prevents tofu boxes, no vision needed)
  • scripts/check_web.py — automatic vision-free webpage check (formulas/ids/sliders/canvas/layout/JS syntax)