calphy-skills

Agent skills for calphy, the free-energy calculation code built on LAMMPS. Each skill is a SKILL.md folder in the Agent Skills format and works with OpenAI Codex and Claude Code. The skills help an AI agent install calphy, write a valid input, pick the right calculation, run it on a laptop or cluster, read the results, and judge whether they can be trusted.

Written against calphy 2.1.2. The keyword table and error messages were taken from the calphy source and the test inputs were run against a real LAMMPS binary.

Skills

skill	use it for
`calphy-install`	conda/pip/source install, which LAMMPS packages are needed, `lmp` resolution, preflight, library backend, smoke test
`calphy-choose-mode`	mapping a physics question to `fe`, `ts`, `tscale`, `pscale`, `alchemy`, `composition_scaling`, or `melting_temperature`, and when calphy is not applicable
`calphy-input-file`	the v2 `calculations:` layout, a validated template, recipes by intent, full keyword reference with defaults and validation errors
`calphy-free-energy`	`mode: fe` and `fe-qtb`: workflow, settings, report fields, trust checklist
`calphy-temperature-sweep`	`ts`, `tscale`, `pscale`: windows, phase-transition detection, sweep files, transition temperatures, entropy and cp
`calphy-melting-temperature`	automated and manual melting points, bracket choice, what makes a Tm unreliable
`calphy-alchemy`	potential-to-potential switching, upsampling, composition scaling and its missing mixing entropy
`calphy-run`	`calphy` vs `calphy_kernel`, local/SLURM/SGE, MPI cores, monitoring, rerunning, library backend, Python API
`calphy-analyse-results`	`report.yaml`, sweep files, `gather_results`, `find_transition_temperature`, combining runs, phase-diagram workflow
`calphy-troubleshoot`	error text to cause to fix, hangs, and how to tell a finished-but-wrong run

Install

Claude Code plugin

/plugin marketplace add thermoatoms/calphy-skills
/plugin install calphy@calphy-skills

Skills are then available as /calphy:calphy-install, /calphy:calphy-input-file, and so on, and are also picked up automatically when a request matches a description.

OpenAI Codex plugin

In Codex CLI, enter /plugins, choose Add Marketplace, and add https://github.com/thermoatoms/calphy-skills. Install calphy, then start a new Codex session. The same marketplace is compatible with both Claude Code and Codex. The equivalent terminal commands are:

codex plugin marketplace add thermoatoms/calphy-skills
codex plugin add calphy@calphy-skills

Installed skills can be selected with /skills or mentioned as $calphy-install, $calphy-input-file, and so on. Codex can also select them automatically when a request matches a skill description. Plugins are available in Codex CLI and the ChatGPT desktop app; for the Codex IDE extension, use standalone skill folders.

Standalone skill folders

Copy any skills/<name>/ directory into the location used by your agent:

host	all projects	one project
OpenAI Codex	`~/.agents/skills/`	`.agents/skills/`
Claude Code	`~/.claude/skills/`	`.claude/skills/`

Codex also supports installing skills from a GitHub repository with $skill-installer.

Layout

.codex-plugin/plugin.json         Codex compatibility manifest
.claude-plugin/plugin.json        plugin manifest
.claude-plugin/marketplace.json   marketplace for Claude Code and Codex
plugin.json                       portable Agent Plugins manifest
skills/<name>/SKILL.md            one skill per folder
skills/calphy-input-file/references/keywords.md   full keyword table
skills/calphy-install/scripts/    setup checker and smoke-test input

Keeping the skills current

The skills state calphy behaviour precisely, so they go stale when calphy changes. On each calphy release:

Diff calphy/input.py against skills/calphy-input-file/references/keywords.md.
Run skills/calphy-install/scripts/smoke_input.yaml and confirm the free energy.
Grep the calphy source for the error strings quoted in calphy-troubleshoot.
Bump version in plugin.json, .codex-plugin/plugin.json, and the Claude plugin and marketplace manifests.

Validate every skill with Codex's quick_validate.py (from skills/.system/skill-creator/scripts/ in the openai/skills repository), validate the Codex plugin manifest, and run claude plugin validate . before release.

License

MIT. calphy itself is distributed under the Academic Software Licence; see the calphy repository.