edu-chem-reaction

Original：🇨🇳 Chinese

Translated

3 scriptsChecked / no sensitive code detected

Turn a chemical reaction into a self-contained microscopic 3D interactive demonstration webpage: The left/top section features a Three.js interactive molecular animation (drag the slider to view bond breaking, bond forming, and atomic recombination with step-by-step highlighting), while the right section includes KaTeX reaction equations + step-by-step explanations + atom conservation counting + optional energy-reaction progress curves. Three entry methods are supported—given text reactions/equations, random question generation, and demonstration after image upload and recognition. It covers combustion, combination/decomposition/single displacement/double displacement reactions, redox reactions (electron transfer visualization), and organic reaction mechanisms (esterification and other reactions involving catalysts and transition states). It is precisely driven by sympy: automatically balance equations, verify atom conservation and atomic mapping, deduce bond breaking/forming, ensuring consistency between answers and geometric models. Two built-in engines are available with automatic selection: morph (atomic deformation, demonstrating atom conservation) and mechanism (mechanism keyframes, demonstrating catalysis/transition states). Hybrid geometry: uses a self-built VSEPR molecular library by default; if RDKit is installed in the environment, it can generate conformations from SMILES (never installed automatically). Other agents can also call this skill to generate such webpages. Its form is parallel to edu-solid-geometry / edu-analytic-geometry, but uses Three.js + KaTeX to demonstrate molecular reactions. Trigger words: chemical reaction, microscopic demonstration, molecular animation, combustion, methane combustion, hydrogen combustion, water electrolysis, redox reaction, electron transfer, esterification reaction, reaction mechanism, bond breaking and forming, atom conservation, mass conservation, chemical equation balancing, solve this chemical reaction, generate a random chemical reaction, the chemical reaction in this image; chemistry reaction, microscopic/molecular animation, combustion, electrolysis, redox electron transfer, esterification mechanism, bond breaking and forming, atom conservation, balance equation, interactive chemistry reaction page.

2installs

Sourcewy51ai/edulab

Added on2026-08-23

NPX Install

npx skill4agent add wy51ai/edulab edu-chem-reaction

SKILL.md Content (Chinese)

View Translation Comparison →

Microscopic Demonstration of Chemical Reactions → Interactive Webpage

What This Skill Produces

A single-page HTML file that can be directly opened in a browser: One side displays the corresponding 3D molecular animation (powered by Three.js, rotatable and scalable; drag the "reaction progress" slider to view chemical bond breaking/formation and atomic recombination frame by frame, with step-by-step highlighting + floating molecular labels), while the other side includes KaTeX reaction equations + step-by-step explanations + atom conservation counter, with optional overlays such as energy-reaction progress curves, flames, catalyst protons, and electron transfer. Its form is consistent with

template/reaction.html

Dependencies (Important)

The core calculation module

lib/reaction_kernel.py

depends on sympy (for equation balancing). Before running the script, ensure you have a

python3

environment that can import sympy: run

python3 -c "import sympy"

(local example:

/opt/homebrew/bin/python3.11

Handling Missing Libraries (Important): If an import error occurs (applies to sympy or any other library used later), ask the user for permission before installation. Install the library only after obtaining consent (using

python3 -m pip install <library name>

) or switch to another interpreter; do not install without user approval. RDKit is optional: If installed, the hybrid geometry will use it to generate real conformations from SMILES; if not installed, the self-built VSEPR library will be used—both options are functional, and this skill will never automatically install RDKit.

Workflow

Step 1: Obtain Reaction Spec (Unified Three Entry Methods)

Organize the reaction into a structured spec (see

references/problem-schema.md

for format): reactants/products, atomic mapping or explicit atoms, conditions (ignition/electrification/catalysis/reversibility), category, step-by-step explanations, and language.

Text Reaction/Equation: Directly extract reactants and products, and call the kernel to automatically balance the equation.
Image: Use visual recognition to extract the equation, and display the recognized reaction to the user for confirmation (equation/conditions/category/language) before proceeding.
Random Question Generation: Select a reaction from the registry, or combine species from the library, balance using
```
balanced_coefficients
```
, and standardize the answer before use.

Output Language Follows Prompt Language: English prompts → English webpage, Chinese prompts → Chinese webpage. Record
meta.language
in the spec.

Step 2: Precise Calculation with Kernel (Do Not Calculate Manually)

Follow the modeling conventions in

references/conventions.md

and call

lib/reaction_kernel.py

```
balanced_coefficients(...)
```
uses sympy's null space to automatically balance equations (equation coefficients are guaranteed);
```
assemble_data(spec)
```
expands molecular instances, verifies atom conservation and bijective atomic mapping, deduces bond breaking/forming (difference set), calculates the world coordinates of each atom in reactant/product states, and generates
```
data
```
to be injected into the template.

You can perform a command-line self-check first:

bash

python3 lib/reaction_kernel.py     # Self-check for balancing + conservation + bond difference
python3 lib/molecules.py           # Self-check for molecular library

Step 3: Write build_* Functions to Assemble Spec and Inject into Template

📍 Output Location (Important): The final HTML file must be written to the user's current working directory (
Path.cwd()
), unless the user explicitly specifies a path. Never write to the skill's own directory (such as
skills/edu-chem-reaction/output/
)—that is the internal development sample directory for the skill.

Modify the

build_*

functions in

scripts/generate.py

as needed, then call

render_html(K.assemble_data(spec), out)

python

from pathlib import Path
out = Path.cwd() / "reaction-<brief-reaction-description>.html"   # Saved in user's current directory
render_html(K.assemble_data(spec), out)

Examples (Copy and Modify Directly):

```
build_combustion_ch4
```
(Methane Combustion · morph · Flame · Energy) — A template for high-level
```
species + atom_map
```
;
```
build_redox_na_cl2
```
(Sodium + Chlorine · Redox · Electron Transfer) — With
```
electrons
```
overlay;
```
build_esterification
```
(Esterification · mechanism · Catalyst · Transition State) — A template for low-level
```
atoms + fragments + keyframes
```
.

generate.py

can directly generate registered reactions; if no path is specified, it defaults to writing to cwd:

bash

python3 <skill-directory>/scripts/generate.py combustion_ch4 ./reaction.html
python3 <skill-directory>/scripts/generate.py list

Step 4: Self-Check (Corresponding Correctness Plan)

sympy balanced coefficients == equation display coefficients == number of each molecular instance (already asserted in
```
assemble_data
```
).
Atomic mapping is a bijection between reactant and product atoms, with consistent elements; all bond endpoints exist (verified by the kernel).
The atom conservation counter remains unchanged before and after the reaction (catalysts are not included).
Start a local static server (serving the directory where the output file is located) for preview checks: no console errors, KaTeX equations render correctly, and bond breaking/forming highlights match step-by-step explanations when dragging the slider.

⚠️ Must Close Opened Ports/Services: Stop the local server immediately after preview checks are completed, never leave port-occupied processes running. If using the preview tool: run
preview_stop
right after checking. Confirm the port is released before delivering the result to the user.

Step 5: Delivery

The final product is saved in the user's current working directory (cwd) with a name like

reaction-<brief-reaction-description>.html

. Inform the user of the path, which can be directly opened in a browser. Before delivery, confirm: (1) The final product is in cwd, not in the skill directory; (2) No local services/ports opened during this preview are left running.

Two Engines and Automatic Selection

The template has a built-in unified renderer and two frame-by-frame positioning methods (sharing bond difference rendering/labels/overlays/UI):

morph (Atomic Deformation): Each atom interpolates from the reactant state to the product state, naturally demonstrating atom conservation/recombination, suitable for any reaction.
mechanism (Mechanism Keyframes): Atoms belong to rigid fragments, and move as a whole according to K0/K1/K2 keyframes. Functional groups do not deform, suitable for organic mechanisms involving catalysts/transition states/leaving groups.

assemble_data

selects the engine based on

meta.engine

(

auto

morph

mechanism

): When set to

auto

, if the category is

organic

or includes

fragments

, it uses the mechanism engine; otherwise, it uses the morph engine. All overlays are data-driven switches (see schema):

flame

(combustion/strong exothermic reactions),

catalyst

(catalyst protons + switch),

transitionGlow

(transition state energy glow),

electrons

(redox electron transfer),

energy

(energy-reaction progress curve), and atom conservation counter (enabled by default).

Color Scheme: Overall bright color scheme (textbook ball-and-stick style: atoms with dark strokes + soft shadows + white background panels). Each reaction uses

meta.accent

to distinguish accent colors (amber for combustion, indigo for esterification, violet for sodium-chlorine reactions, etc.).

Expansion

Add Reactions: Add a
```
build_*
```
function (high-level
```
species+atom_map
```
or low-level
```
atoms+fragments
```
) to
```
generate.py
```
and register it in
```
REGISTRY
```
.
Add Molecules/Ions: Add an entry to
```
_LIBRARY_BUILDERS
```
in
```
lib/molecules.py
```
(VSEPR geometry + display metadata + internal bonds).
Add Overlays: Add an optional module driven by the
```
data
```
field in
```
template/reaction.html
```
.