How to use the pycalphad agent skill for phase equilibria

What is an agent skill, and what does this one make the agent do?

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches the skill's description. The skill's main instructions are in a file called SKILL.md, and it can also include scripts, reference notes and data files.

This skill is for equilibrium calculations only. At a fixed bulk composition, a specified pressure and a list of finite temperatures, the agent runs a bundled script that performs real pycalphad equilibria. The script checks mass balance, repeats the calculation at a higher sampling density and exports each stable composition set separately.

• Reports stable phases and their molar phase fractions at each temperature
• Reports phase compositions as elemental mole fractions
• Checks that phase fractions sum to one and that the reconstructed bulk composition matches the request
• Writes report.json and phase-equilibria.csv to an output directory

Install the pycalphad skill (ZIP or Claude apps)

Option 1, personal install: download the skill ZIP from this page and unzip it into ~/.claude/skills/ so that the pycalphad folder sits inside that directory.

Option 2, single project: unzip the ZIP into the .claude/skills/ folder of your project, so the skill applies only when you work in that project.

Option 3, Claude apps: upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

The skill's calculations run locally. Installing the Python packages needs network access, as noted in the requirements section.

• Personal: ~/.claude/skills/pycalphad/
• Project: .claude/skills/pycalphad/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need before running it?

You need Python 3.12 or newer, the pycalphad library, NumPy and uv. The documented run command uses uv to fetch the pinned pycalphad and NumPy versions, so you do not need to install them separately for that command. The skill is tested with the versions listed in its own requirements.

For real materials you also need a thermodynamic database in TDB format from a licensed or otherwise suitable source. The bundled file assets/ideal-cu-ni.tdb is a hypothetical teaching model, not an assessed Cu-Ni database, so it cannot be used to make real alloy decisions.

• Python 3.12 or newer
• pycalphad and NumPy (pinned in the run command)
• uv, used by the documented run command
• Network access for installation
• A user-supplied TDB database for real materials

Trigger the skill with natural requests

You do not need special syntax. Describe the task in plain words that match the skill's use cases: alloy phase stability, equilibrium temperature sweeps, tie lines, lever-rule checks, or reproducible phase-fraction calculations with explicit components and mole-fraction conditions.

Give the agent the database, the components, the bulk mole fractions, the pressure and the temperatures. The skill asks for mole fractions, so convert weight percentages before you ask.

• Which phases are stable in a Cu-Ni alloy with X(Ni)=0.5 at 900 K, 1100 K and 1300 K, using this TDB file?
• Run an equilibrium temperature sweep for my alloy from 900 K to 1400 K and show phase fractions and compositions.
• Check the lever rule for the two-phase region at 1100 K and show the tie-line endpoints.
• Give me a reproducible phase-fraction calculation with the components listed and the database hash recorded.

Run the tested example

The skill's own example runs from the collection root, the folder that contains skills/pycalphad. If you installed the skill from the ZIP into another location, adjust the paths to match your folder layout. The script takes the database file, a JSON settings file and an output directory. Use a new output directory each time.

For the supplied hypothetical model at X(Ni)=0.5 and 101325 Pa, the skill reports FCC_A1 only at 900 K, a mix of 0.5 FCC_A1 and 0.5 LIQUID at 1100 K (with X(Ni) approximately 0.527307 in the solid and 0.472693 in the liquid), and LIQUID only at 1300 K.

• Output: report.json (settings, file hashes, checks and results) and phase-equilibria.csv (one row per stable phase vertex per temperature)
• The helper performs all calculations locally and does not upload the TDB file

Read the results and their limits

Phase fractions in the CSV are molar fractions. The Gibbs energy column is the whole-system molar Gibbs energy, repeated for each vertex, not the energy of an individual phase.

The checks ask whether the calculation is internally consistent. They do not prove that the database is experimentally accurate, and they do not certify the global minimum. Failed checks stay visible in the report rather than being relabelled as convergence. The skill also asks the agent to state the database source, excluded phases and the limitations of the result.

• Equilibrium only: it does not predict precipitation rates, retained metastable microstructures or properties of phases missing from the database
• Pure-component or ultratrace results from a clipped multicomponent calculation should not be claimed as exact
• Weight percentages must be converted to mole fractions by you before using the helper