How to use the PyBaMM battery experiments agent skill

What is an agent skill, and what does the pybamm skill do?

An agent skill is a folder of instructions, reference files and scripts that an AI agent can load when a task matches it. The pybamm skill covers one job: simulating a single lithium-ion cell under a constant-current charge, discharge or rest protocol.

The agent turns your requested protocol into a validated JSON file, runs a bundled Python script that uses PyBaMM, and checks the output by re-running the simulation with tighter solver tolerances and a finer mesh. It can also compare predicted voltage curves with a CSV file of your measured data and report the residual errors.

• Models: SPM or DFN electrochemical models
• Protocols: charge, discharge and rest steps defined by C-rate, duration and optional voltage cutoff
• Provenance: records the parameter set and base parameters used
• Numerical checks: baseline versus tighter tolerances, and original versus doubled mesh
• Comparison: voltage and current residuals against measured cycling data

How do you install the pybamm skill?

Download the ZIP file from this page and unzip it. You can install the skill for yourself or for a single project. For yourself, place the unzipped pybamm folder in ~/.claude/skills/. For one project, place it in the project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

The skill needs a Python environment with PyBaMM and its IDAKLU solver. The commands below create one with uv. Run them from the skill directory. Installation needs network access.

• Requires Python 3.12, PyBaMM and pybammsolvers (IDAKLU solver)
• NumPy and CasADi are installed automatically as part of PyBaMM
• The tested setup uses the exact pinned releases shown in the commands

How do you ask the agent to use the pybamm skill?

You do not need special syntax. Describe the cell, the protocol and what you want to learn in ordinary language. The skill is meant for requests that mention battery modeling terms such as SPM, DFN, C-rate, voltage cutoff, parameter study or numerical validation.

Give the agent the details it needs: the model, the protocol steps with C-rates and durations, the starting state of charge and temperature, and the parameter set. If you have measurements, say which file holds them and what columns it uses.

• "Simulate a 0.5C discharge to 3.0 V on an SPM model, then charge back at 0.5C for 600 s."
• "Check whether my DFN results change if I refine the mesh. Is the voltage difference under 1 mV?"
• "Compare the predicted voltage from this SPM run with measured.csv and report RMSE and bias."

Run the example and read the results

The skill includes a reference protocol that discharges at 0.5C for 600 s, rests for 120 s and charges at 0.5C for 600 s, starting from 80% state of charge at 298.15 K. It is a synthetic case built on a published parameter set. It is a worked example, not a claim about your cell.

To compare with measurements, the CSV needs time_s, voltage_V and current_A columns. The output directory must be new. The skill writes the files listed below.

• curve.csv: baseline time, step, voltage, current and net discharge capacity
• tight-tolerance.csv: same mesh with a tighter solver
• refined-mesh.csv: doubled mesh with the tighter solver
• parameters.json: base parameters after state-of-charge initialization
• report.json: protocol checksum, package versions, parameter source, numerical comparisons and terminations
• measurement-residuals.csv: prediction minus measurement, when measurements are supplied

How should you interpret the numerical checks?

Read the two comparisons separately. The tighter-tolerance run isolates solver error. The doubled-mesh run isolates discretization error. Compare voltage and event-time differences with the accuracy your question needs. One mesh doubling does not prove convergence, so refine again if the differences are still large.

In the reference case, tightening the tolerances changed voltage by about 1 microvolt, while doubling the mesh from 20 to 40 points changed it by about 2.17 mV. The skill therefore does not support any claim of sub-millivolt mesh accuracy.

• Check the measured current, time origin, temperature, state of charge and capacity before reading residuals.
• A small voltage error under a mismatched input current does not validate the model.
• The comparison checks curves. It does not identify unique kinetic parameters from voltage alone.

What are the safety limits and network notes?

The skill runs Python scripts on your machine and uses the network to install packages and, optionally, to retrieve upstream datasets. The bundled simulations and CSV comparisons run locally and need no credentials. The skill disables PyBaMM usage telemetry unless you have set that variable yourself.

The skill is not a battery controller. It does not drive a battery cycler and does not set safe operating limits for hardware. The models are isothermal and exclude aging, plating, mechanics and pack control. Degradation or lifetime predictions are outside its scope, and copying degradation parameters between cells can be misleading.

• Runs scripts: yes
• Uses network: yes, for installation and optional dataset retrieval
• Do not use the output to set charging limits on real hardware