How to use the Marine Carbonate Chemistry agent skill

What the skill makes the agent do

Given two independent seawater carbonate measurements, such as total alkalinity (TA) and dissolved inorganic carbon (DIC), the agent calculates a speciation table. The outputs include total-scale pH, seawater pCO2 or fCO2, carbonate ion levels, and aragonite and calcite saturation states, using the PyCO2SYS library version 1.8.3.4.

The skill can also convert results from laboratory temperature and pressure to specified ocean conditions, and propagate stated measurement uncertainties into the results. It is scoped to seawater carbonate equilibria. It is not designed for freshwater, porewater with uncharacterized alkalinity, or estimating air-sea CO2 flux.

Install the skill

Download the skill ZIP from this page and unzip it into one of two locations. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

Set up the Python environment

The skill requires Python 3.13, PyCO2SYS 1.8.3.4, and NumPy 2.5.3. The skill recommends uv for creating the environment. Run these commands in your working directory:

• On Windows, the interpreter is at .venv/Scripts/python.exe instead of the POSIX path shown here.
• Set the shell variable SKILL_DIR to the installed skill's directory before running the solver.
• Keep your input files and generated outputs in the working directory.

Prepare your measurements in the right units

Most errors come from units and scales, not from the arithmetic. The skill expects TA and DIC in micromol per kg of seawater, salinity as Practical Salinity, temperature as in-situ temperature in degrees Celsius, and pressure as sea pressure in dbar, where a surface sample is 0. pCO2 and fCO2 are in microatm and are different quantities. pH must declare its scale, and a column named only pH is not enough.

Use two independent carbonate parameters. pCO2 plus fCO2 is not an independent pair. Supply phosphate and silicate explicitly; zero is an assumption you must justify, not a placeholder for missing data. Do not convert missing values or rejected measurements to zero.

• Keep a separate source table with station, depth, timestamps, methods, reference materials and original QC codes, joined by sample ID.
• Convert source missing-value codes such as -999 before creating the input file.

Trigger the skill with a natural request

You do not need special syntax. Describe the measurements and the result you want, and name the chemistry if you know it. The agent should pick the skill from its description when your request mentions seawater carbonate work. Include the two measured parameters, their units, the salinity and temperature basis, and the outputs you need.

• "I have TA and DIC for six bottle samples in micromol/kg. Calculate total-scale pH, pCO2 and aragonite saturation at the sample conditions."
• "Check whether my measured TA and pH are internally consistent, using total pH scale."
• "Convert these lab-measured carbonate results to 10 C and 1000 dbar and report the aragonite saturation state."

Run a worked example

The skill includes a synthetic example with two samples that differ only in DIC. Save the table as samples.csv in your working directory. Both samples are measured at 25 C and 0 dbar, and results are requested at 10 C and 1000 dbar. Run the solver from that directory.

For the baseline sample, the tested version gives total pH 8.045886, pCO2 396.958 microatm and aragonite saturation 3.386201 at input conditions. At the output conditions, total pH is 8.241241 and aragonite saturation is 2.605691. These are regression checks for this exact setup, not universal seawater benchmarks. The solver writes carbonate.csv and provenance.json into the output directory.

Review flags and the gas pressure caveat

A successful solve does not validate your sample, constants or method. Check calibration-range and gas-pressure flags, carbonate balance, and residuals against any third measured parameter. The worked example's rows carry gas_pressure_correction_disabled_output, which means output pH and mineral saturation include pressure effects, but the reported pCO2 and fCO2 do not include hydrostatic corrections. Do not compare those gas values directly with a pressure-corrected subsurface sensor.

• Results ending in _out describe the output temperature and pressure; unsuffixed results describe input conditions.
• Report the parameter pair, pH scale, units, constants, nutrient assumptions, software versions and any excluded samples with the results.