What this skill produces
A single-page HTML (three columns) that can be opened directly in a browser:
- Left column: problem statement + dynamic console — one variable-parameter slider (such as time t / angle θ / velocity v / temperature T) drives real-time recomputed physics quantities (position, velocity, acceleration, energy, momentum…), as well as an "identity indicator" (conservation law) or "state determination".
- Middle column: step-by-step analysis (formulas use KaTeX), can be collapsed with one click to give the space to the board.
- Right column: 2D Canvas dynamic physics board (trajectory trace + particle + vector arrows + waveform + light rays + electric field lines + grid coordinate axes), overlaid with a brush doodle toolbar.
Division of labor between edu-physics (2D) and edu-physics-3d
This skill (edu-physics) coversphysics scenarios that a 2D plane is sufficient to display. Whenever the physics quantities/directions/trajectories involvethree-dimensional space, or need to be observed from any angle, please use the separate edu-physics-3d skill (Three.js 3D board).
| Scenario | Skill to use | Reason |
|---|---|---|
| Projectile motion, simple harmonic motion, waves | edu-physics | 2D is completely sufficient |
| Inclined plane block, collisions, circular motion | edu-physics | Motion within a plane |
| Electric field lines, equipotential surfaces, circuits | edu-physics | Planar field distribution |
| Gas state changes, thermodynamic cycles | edu-physics | PV diagram plane |
Lorentz force F=qv×B |
edu-physics-3d | The cross product direction is perpendicular to the plane, must be 3D |
| Right-hand rule visualization | edu-physics-3d | The force direction is perpendicular to the plane of v and B |
| Atomic orbital shapes | edu-physics-3d | s/p/d orbitals are three-dimensional spatial distributions |
| Crystal structure/lattice | edu-physics-3d | Three-dimensional spatial arrangement |
| Rigid body rotation/angular momentum | edu-physics-3d | The rotation axis is in three-dimensional space |
| Electromagnetic wave E/B orthogonal | edu-physics-3d | The two fields propagate orthogonally in three-dimensional space |
| Magnetic field (solenoid) | edu-physics-3d | Field lines are distributed in three-dimensional space |
edu-physics outputs a 2D Canvas single-page HTML; edu-physics-3d outputs a Three.js 3D single-page HTML.
The data island formats of the two differ (board vs board3d), see their respective SKILL.md for details.
Dependencies
No external dependencies(no physics engine needed, no sympy needed). The template engine template/board.html is a self-contained single-page
HTML. As long as you can use Python 3 (the standard library is enough) for string replacement, that works, or you can directly inject JSON manually.
Workflow
Step 1: Determine the problem specification
Clarify:
- Physics scenario: projectile motion/collision/oscillation/wave/refraction/electric field/gas change, etc.
- Variable parameters: time t, angle θ, velocity v, temperature T, etc., determine the range and step size
- Physical laws: equations of motion, Newton's laws, conservation of energy/momentum, gas state equation, etc.
- Interaction paradigm: sliders control time/angle/parameters, observe changes in physical quantities + trajectory/vector/conservation verification
- Language: output language follows the prompt language (Chinese/English)
Step 2: Design the physical system
This is the most critical step. Choose convenient system coordinates and write the parameterized expressions of the physical quantities.
Coordinate placement tips:
- For projectile motion, use the launch point as the origin, with x horizontal to the right and y vertical upward
- For simple harmonic motion, use the equilibrium position as the origin
- For light refraction, place the interface on the x-axis
- For an inclined plane, align it along the x-axis
Physical quantity construction patterns:
| Scenario | Coordinate scheme | scalars sequence |
|---|---|---|
| Projectile motion | Origin at the launch point | vx=v₀cosθ, vy=v₀sinθ-gt, x=vx·t, y=vy·t-½gt² |
| Simple harmonic motion | Equilibrium position at the origin | x=A·cos(ωt+φ), v=-Aω·sin(ωt+φ), a=-Aω²·cos(ωt+φ) |
| Block on an inclined plane | Inclined plane along the x-axis | a=g(sinθ-μcosθ), v=at, s=½at² |
| Conservation of momentum | Along the same straight line | v1'=(m1-m2)v1/(m1+m2), v2'=2m1v1/(m1+m2) |
Verify physical correctness(mental check):
- Initial conditions: whether position, velocity, and energy are correct at t=0
- Conservation check: whether mechanical energy Eₖ+Eₚ is constant
- Boundary conditions: whether vy=0 at the highest point and x is correct when y=0 at the landing point
viewport range: leave a 10-15% margin to ensure the complete motion trajectory is visible on the canvas.
Step 3: Assemble the data and inject it into the template
📍 Output location & unique artifact: deliver to the useronly one
.html, write tocurrent working directory (Path.cwd()). Do not leave any other files in cwd—build scripts (.py)、__pycache__, screenshots, etc. put temporary files all in/tmpor delete them after use. Also never write into the skill's own directory.
Data format(three-part JSON, see schema in template/board.html data island __LESSON_DATA__):
{
"lesson": {
"language": "zh-CN",
"title": "页面标题",
"problem": "<p>题面 HTML,公式用 $…$ / $$…$$</p>",
"answer": "$E_k+E_p = \\text{const}$"
},
"steps": [
{ "title": "步骤一", "content": "<p>解析内容...</p>" },
],
"board": {
"view": { "xRange": [-1, 10], "yRange": [-1, 6] },
"points": {
"O": [0, 0],
"P": ["v0*cos(theta*PI/180)*t", "v0*sin(theta*PI/180)*t-0.5*g*t*t"],
// 速度矢量箭头末端 = 当前位置 + 速度方向(缩放),用表达式点驱动
"Vtip": ["x+vx*0.3", "y+vy*0.3"]
},
"param": {
"name": "t",
"label": "时间 $t$ (s)",
"min": 0, "max": 5, "step": 0.05,
"value": 0, "unit": "s",
"ticks": ["0", "2.5", "5"]
},
"scalars": [
{ "name": "v0", "expr": "10" },
{ "name": "theta", "expr": "45" },
{ "name": "g", "expr": "9.8" },
{ "name": "vx", "expr": "v0*cos(theta*PI/180)" },
{ "name": "vy", "expr": "v0*sin(theta*PI/180)-g*t" },
{ "name": "x", "expr": "vx*t" },
{ "name": "y", "expr": "vy*t-0.5*g*t*t" },
{ "name": "Ek", "expr": "0.5*(vx*vx+vy*vy)" },
{ "name": "Ep", "expr": "g*y" },
{ "name": "E", "expr": "Ek+Ep" }
],
"derived": [
// 质点 P(points 里定义的点默认按浅灰渲染;这里用 vector 叠加箭头更醒目)
// 位移矢量:从原点指向质点
{ "type": "vector", "name": "r_vec", "from": "O", "to": "P", "color": "vecA", "label": "$\\vec{r}$" },
// 速度矢量:从质点 P 指向 Vtip(随速度方向变化的箭头)
{ "type": "vector", "name": "v_vec", "from": "P", "to": "Vtip", "color": "vec", "label": "$\\vec{v}$" },
],
"readouts": [
{ "id": "x", "label": "水平位移 $x$", "type": "expr", "expr": "x", "digits": 2, "color": "vecA" },
{ "id": "y", "label": "竖直位移 $y$", "type": "expr", "expr": "y", "digits": 2, "color": "vecB" },
{ "id": "vx", "label": "$v_x$", "type": "expr", "expr": "vx", "digits": 2, "color": "vecA" },
{ "id": "vy", "label": "$v_y$", "type": "expr", "expr": "vy", "digits": 2, "color": "vecB" },
{ "id": "Ek", "label": "$E_k = \\frac{1}{2}mv^2$", "type": "expr", "expr": "Ek", "digits": 2 },
{ "id": "Ep", "label": "$E_p = mgy$", "type": "expr", "expr": "Ep", "digits": 2 },
{ "id": "E", "label": "$E = E_k+E_p$", "type": "expr", "expr": "E", "digits": 4, "highlight": true }
],
// 定值指示(机械能守恒)—— of 指向上面 readouts 里真实存在的 id "E"
"constant": { "of": "E", "label": "$E_k+E_p \\equiv \\text{常数}$" },
// trace 轨迹
"trace": { "of": "P", "color": "locus" },
// 图例
"legend": [
{ "color": "locus", "text": "轨迹" },
{ "color": "vec", "text": "速度 $\\vec{v}$" },
]
}
}
Build script method(Python, recommended):
Place the build script in /tmp, directly perform string replacement:
#!/usr/bin/env python3
import json, sys
from pathlib import Path
sys.dont_write_bytecode = True
SKILL_DIR = Path(".claude/skills/edu-physics")
TEMPLATE = SKILL_DIR / "template" / "board.html"
PLACEHOLDER = "__LESSON_DATA__"
data = {
"lesson": { ... },
"steps": [ ... ],
"board": { ... }
}
template = TEMPLATE.read_text(encoding="utf-8")
out_path = Path.cwd() / "solution-xxx.html"
out_path.write_text(
template.replace(PLACEHOLDER, json.dumps(data, ensure_ascii=False)),
encoding="utf-8"
)
print("written:", out_path)
python3 -B /tmp/build.py && rm -f /tmp/build.py
Note: if at runtime it prompts
template/board.htmlthe path is incorrect, please use an absolute path or derive it fromPath(__file__).
Step 4: Self-check and delivery
- Physical correctness: verify the initial conditions at t=0, that conserved quantities remain constant, and that boundary conditions are correct
- Browser preview: start a local static server, check that there are no console errors, KaTeX works properly, and slider interaction is smooth
- When the slider is dragged, the particle moves along the expected trajectory
- The trace trajectory curve is correct (parabola for projectile motion, sine wave for SHM, etc.)
- Vector direction/magnitude changes correctly with parameters
- The constant indicator remains constant throughout
- Close the port: stop the local server immediately after preview ends
- Cleanup: delete
/tmptemporary scripts in , confirm that cwd contains only.html
Data Format Reference (Core Fields)
Key board Field Descriptions
| Field | Type | Description |
|---|---|---|
view |
{xRange, yRange} |
Mathematical coordinate viewport |
points |
{name: [x,y] 或 {xy,color,label}} |
Key position coordinates |
param |
{name, min, max, step, value, label, unit, ticks} |
Slider definitions |
scalars |
[{name, expr}] |
Physical quantities derived from param |
derived |
Construction sequence | point / vector / segment / polygon, etc. |
readouts |
[{id, label, type, ...}] |
Real-time physical quantity values |
constant |
{of, label} |
Conservation law indicators |
trace |
{of, color} |
Trajectory sampling (160 steps) |
legend |
[{color, text}] |
Legend |
Common readouts types
| type | Field | Displayed content |
|---|---|---|
expr |
expr, digits |
Any physical quantity expression |
distance |
a,b (point) |
Distance between two points |
coord |
of (point) |
Coordinates |
status |
expr, rhs, okText, badText |
Boolean state determination (e.g. "overweight"/"weightless") |
Common derived types
Note: After a particle position is defined in
points, it is automatically rendered (default light gray); if you need to change the color/label, declare it inpointsusing the{xy, color, label}form, rather than using derived'spoint(this type is not implemented). When velocity/force vectors change with the particle, a common approach: define an "arrow endpoint" point inpoints(coordinates using expressions), then usevectorto point from the particle to it (seeVtip)。
| type | Field | Effect |
|---|---|---|
segment |
name, a, b, color, dashed |
Segment (light ray/electric field line/boundary) |
vector |
name, from, to, color, label |
Displacement/force/field strength vector (name required) |
polygon |
pts, color, stroke |
Semi-transparent fill (energy bar/region) |
midpoint |
name, a, b |
Midpoint |
line_through_points |
name, a, b, color |
Line through two points |
line_through_slope |
name, point, slope, color |
Line through one point with slope |
Color semantic names
curve(golden yellow) · line(cyan) · aux(gray auxiliary) · ptA(red) · ptB(blue) · point(light gray) ·
given(purple) · fixed(emerald green) · vecA(red) · vecB(blue) · locus(trajectory purple-red) ·
area(cyan semi-transparent).
You can also write hex directly:#f87171 or rgba(248,113,113,0.25)。
Expression engine
Coordinate values/scalars in the expr supports:+ - * / ^ sqrt cbrt abs sin cos tan asin acos atan atan2 exp log pow min max sign floor ceil hypot PI
Trigonometric functions useradians(angles must be converted first:theta*PI/180).
Parameter names must be valid JS identifiers (e.g. t/v0/theta, cannot use θ and other non-identifiers).
KaTeX Formula Notes
KaTeX formulas in the course text (lesson.problem、steps[].content) and legend (legend[].text)
use $...$(inline) or $$...$$(block) wrapping.
Known incompatible commands:
\\prescript— KaTeX does not support themathtoolspackage's\\prescriptcommand. ✅ Use instead{}^{<上标>}_{<下标>}\\text{<基>}, e.g.:$\\left({}^{4}_{2}\\text{He}^{2+}\\right)$→ $\left({}^{4}_{2}\text{He}^{2+}\right)$
trace Trajectory System
After configuring board in trace: { of: "点名称", color: "颜色" } , the engine samples the [min, max] interval of param uniformly over 160 steps and draws the trajectory path for the specified point. Suitable for:
- Parabolic trajectory of projectile motion
- x-t curve of simple harmonic motion (horizontal axis time, vertical axis displacement)
- Wave envelope
constant value indicator
Configuration constant: { of: "读数id", label: "标签" } Afterward, when the read value changes with the slider and remains constant as a fixed value,
the page displays a green banner prompt. Applicable to:
- Conservation of mechanical energy (
Eₖ+Eₚconstant) - Conservation of momentum (
m₁v₁+m₂v₂constant) - Pythagorean theorem (
a²+b²-c²≡0) - Other identities
Table of contents
template/board.html— Data-driven template (generic 2D renderer + parameter engine + data island__LESSON_DATA__)references/conventions.md— Physics interaction paradigms, construction patterns, self-check checklistexamples/— Example reference