v2.0.0

What's Changed

Warning

BREAKING MAJOR RELEASE: AtomisticSkills 2.0.0 completely overhauls the runtime architecture, replacing legacy manual conda environments with unified, deterministic uv projects and container fallbacks, restructuring skills to comply with the standard Agent Skills specification, and consolidating MCP servers. Existing 1.x installations, conda environments, and configurations are not backwards-compatible. Please review the migration guide below.

Repository Stats

Component	v1.3.4	v2.0.0	Added
Skills	129	133	+4
Workflows	9	9	—
MCP Tools	49	49	—
Tool Servers	20	10	—

New Skills

Skill	Description	Author
general-atomisticskills-rules	Working rules for atomistic research with AtomisticSkills -- how to scope a request, set up a research directory and a plan before simulating, run skills and MCP tools, stay within GPU memory, and report results.	@bowen-bd
general-atomisticskills-setup	Set up, check or troubleshoot how AtomisticSkills runs on this machine -- creating its Python environments, connecting its MCP servers, choosing uv or a container runtime, and configuring API keys.	@bowen-bd
general-publisher-access-guard	Avoid bot-blocking publisher websites by routing paper retrieval through legal open-access APIs and mirrors.	@bowen-bd
mat-wannier-tight-binding	Construct and validate Wannier tight-binding models, inspect orbital localization and hopping amplitudes, and interpolate electronic bands from DFT or existing Wannier90 files.	@bowen-bd

Breaking Changes: 1.x to 2.0.0 Overview

Area	1.x	2.0.0
Python Environments	~20 manual conda environments (base-agent, mace-agent, etc.)	Deterministic uv projects (venv/cpu, venv/mlip, venv/fairchem) + pinned research stacks (adit, diffcsp, mattergen, msms, reactot, scd)
Execution Launcher	conda run -n <env> python ..., # Env: annotations	Unified launcher venv/run <venv>[+extra] <cmd>; SKILL commands invoke ${CLAUDE_SKILL_DIR}/../../venv/run
MCP Server Config	Fragmented per-server configs with hardcoded interpreter paths	Consolidated 10 multi-tool servers started via venv/run --server <name>
MCP Shell Fallback	Required running standalone agent scripts	Direct shell CLI fallback: venv/run <venv> python -m src.mcp_server.cli <server> <tool> key=value ... sharing process state
Claude Plugin	Custom layout under .agents/skills, unrecognised spec keys	Root plugin via .claude-plugin/plugin.json, skills at skills/ adhering to standard 6-key Agent Skills spec
Container Images	Custom Dockerfiles (atomisticskills-lightweight, -mace, etc.)	Dual-architecture OCI images (-cpu, -mlip, -fairchem, -generative) locked from uv dependencies with Apptainer support
MatGL & CHGNet	MatGL with DGL backend; 2025 MatPES checkpoint	MatGL ≥ 4 (PyTorch Geometric only); default CHGNet is CHGNet-PES-MatPES-PBE-1M-2026.9
GPU / CUDA	Generic CUDA 12 builds	Dynamic runtime detection: CUDA 13 (driver ≥ 580) vs CUDA 12.6 (drivers 525–579) PyTorch builds

---

Conda to UV & Docker Migration: Runtime Dispatch Rules

Conda environments have been entirely eliminated (conda-envs/ is removed). AtomisticSkills now uses a unified launcher backend driven by venv/run:

1. When is Native uv Used?

By default (ATOMISTIC_RUNTIME=auto), venv/run inspects the host platform and executes natively with uv when:

• The OS is Linux on x86_64 or aarch64.
• The host glibc meets the requirement declared in venv/platforms.tsv for the requested project (e.g. glibc ≥ 2.34 for OpenMM, glibc ≥ 2.32 for generative PyG wheels, glibc ≥ 2.28 for base CPU).
• A host C compiler (gcc / clang) is available for any package source builds.
• Environments sync on-demand inside the repository under venv/<project>/.venv in seconds using Astral uv.

2. When is Container Execution (Docker / Apptainer / Podman) Used?

A container is dispatched automatically or explicitly when:

• Automatic Fallback: The host system does not satisfy the platform criteria (e.g., glibc is older than required, running on non-Linux, or lacking native PyG/CUDA compilers on arm64).
• HPC Environments: On high-performance computing clusters where users lack root/docker permissions, ATOMISTIC_RUNTIME=apptainer builds or reuses SquashFS SIF images directly in ~/.cache/atomisticskills/images/ and passes GPUs via --nv.
• Explicit Override: Setting ATOMISTIC_RUNTIME=docker, podman, or apptainer forces container execution. Host workspaces, project directories, and source checkouts are mounted at identical paths so output file ownership and permissions belong directly to the user.

3. Why Three Shared Environments + Pinned Research Stacks?

Rather than a single bloated environment, three shared uv projects resolve fundamental package incompatibilities:

1. venv/cpu: Fast, lightweight environment for ASE, pymatgen, RDKit, pycalphad, MDAnalysis (Python 3.12, NumPy 2.5+, no PyTorch).
2. venv/mlip: MACE and MatGL (PyTorch 2.14.1, mace-torch 0.3.16 pinning e3nn==0.4.4, matgl 4.1.0, NumPy 2.3.5).
3. venv/fairchem: FairChem foundation models (PyTorch 2.13.0, fairchem-core 2.23.0 requiring e3nn>=0.5, NumPy 2.3.5).
4. Pinned Research Stacks: Stacks requiring legacy PyTorch versions or custom C++/CUDA extensions (adit, diffcsp, mattergen, msms, reactot, scd) run in isolated uv projects replicating their exact verified dependency sets without perturbing shared foundations.

---

Modernized Model Context Protocol (MCP) Integration

• 10 Consolidated Multi-Tool Servers: Replaced 20 fragmented single-purpose servers with 10 coherent domain servers: base, atomate2, drugdisc, smol, mace, matgl, fairchem, adit, diffcsp, and mattergen.
• Unified Server Launcher: Every server is started through the launcher:

  venv/run --server <server_name>

  configure_mcp.py automatically generates compliant configurations for Claude Desktop, Claude Code, Gemini CLI, Cursor, and Windsurf.
• Headless Shell CLI Fallback: Any MCP tool can be invoked directly from the terminal without an active MCP JSON-RPC connection:

  venv/run <venv> python -m src.mcp_server.cli <server> <tool> key=value ...

  Multiple tools chained in a single invocation share process memory, allowing stateful workflows (e.g., load_model followed immediately by relax_structure).
• Harness Separation: Agent harness utilities (task_boundary, notify_user) are strictly decoupled from the MCP server interfaces.

---

Claude Plugin Architecture & Spec Compliance

• Standard Plugin Layout: Configured via .claude-plugin/plugin.json and .claude-plugin/marketplace.json at repository root.
• Spec-Compliant Frontmatter: All skills now reside at skills/<skill_name>/SKILL.md (with .agents/skills maintained as a compatibility symlink). Frontmatter strictly follows the 6-key Agent Skills specification; categories are nested under metadata.category and required environments under metadata.venv.
• Self-Locating Executables: Skill command templates use ${CLAUDE_SKILL_DIR}/../../venv/run <venv> python ..., ensuring flawless path resolution across project skills, personal skills, and plugin installations.
• Runtime Configuration Options: Plugin users can configure runtime preferences via plugin settings: runtime (auto, uv, docker, apptainer), image_registry, and image_tag. Simulation artifacts write directly into the active user workspace rather than internal plugin directories.

---

Upgrade Instructions

For Claude Plugin Users

claude plugin marketplace update atomistic-skills
claude plugin update atomistic-skills@atomistic-skills

Restart Claude Code. Environments are generated automatically on first use or initialized ahead of time via venv/run --setup.

For Clone / Local Users

git pull origin main
venv/run --setup           # Initializes venv/cpu, venv/mlip, and venv/fairchem
venv/run --doctor          # Validates runtime status and detected CUDA drivers
python configure_mcp.py    # Rewrites agent MCP configurations

---

Other Highlights & Enhancements

• MLIP Models & Weights: Upgraded MatGL to 4.x (PyTorch Geometric backend, dropping DGL), defaulted CHGNet to the latest CHGNet-PES-MatPES-PBE-1M-2026.9 checkpoint, and added opt-in batched GPU inference via NValchemi.
• Elasticity Refactor: Overhauled mat-elasticity to use pymatgen ElasticTensor and ComplianceTensor directly with relaxed-ion defaults and off-axis compliance verification.
• Equation of State: Corrected Birch-Murnaghan minimum parameter fit extraction and energy-volume curve export in mat-equation-of-state.
• Spectrometry: Ported chem-msms-predict to ICEBERG 2.1 (ms-pred 2.1) on a dedicated uv project with automated MassSpecGym weights download.
• LAMMPS Integration: Added dedicated build scripts in mat-lammps-md targeting venv/mlip (mlip+lammps) and fairchem+lammps.
• DFT Robustness: Fixed Atomate2Handler.check_status job lookup by UUID via JobController's custom query interface.

v1.3.4

What's Changed

Repository Stats

Component	v1.3.3	v1.3.4	Added
Skills	128	129	+1
Workflows	9	9	—
MCP Tools	49	49	—
Tool Servers	20	20	—

New Skills

Skill	Description	Author
mat-edi-mobility	Compute defect-limited carrier mobility and electron-defect scattering matrix elements in 2D and 3D semiconductors from first principles with Quantum ESPRESSO and the EDI plugin.	@cz2014

Other Highlights

• Defect-Limited Mobility: Added the mat-edi-mobility skill to compute defect-limited carrier mobility and electron-defect scattering matrix elements in 2D/3D semiconductors using Quantum ESPRESSO and the EDI plugin.
• QHA Thermal Expansion: Exposed --fmax and --max_steps in mat-qha-thermal-expansion to prevent convergence stalls on MLIP forces; added optional --volume_window control while preserving field-standard volume window defaults and updating strain convention documentation.
• Toxicity & Hazard Triage: Added GHS acute oral toxicity category profiling and consensus GHS code extraction to chem-hazard-toxicity.
• Claude Code Native Integration: Registered .agents/skills as native Claude Code project skills when configuring agent integrations.
• Synthesis Recommendation: Enhanced Materials Project API compatibility in mat-synthesis-recommendation for newer mp-api synthesis endpoints.
• Linter & Code Hygiene: Configured ruff per-file-ignores for E402 in pyproject.toml and removed redundant inline noqa comments across MCP servers and skill scripts.
• Documentation & Citations: Updated the paper citation in README.md to reflect publication year 2026.

v1.3.3

What's Changed

Repository Stats

Component	v1.3.2	v1.3.3	Added
Skills	127	128	+1
Workflows	9	9	—
MCP Tools	49	49	—
Tool Servers	20	20	—

New Skills

Skill	Description	Author
mat-epw-mobility	Compute carrier mobility and mode-resolved electron-phonon coupling in 2D materials from first principles with Quantum ESPRESSO and EPW.	@cz2014

Other Highlights

• Uncertainty Quantification: Added detailed guidance and critical warnings to the committee uncertainty skill (ml-committee-uncertainty) regarding heterogeneous ensembles (multi-foundation models). Clarified that absolute energy standard deviation is not a valid disagreement signal when models do not share a common energy reference scale ($E_0$), and directed users to rank using force disagreement instead.
• Electron-Phonon Coupling: Added the mat-epw-mobility skill to run Quantum ESPRESSO + EPW calculations for 2D semiconductors.

v1.3.2

What's Changed

Repository Stats

Component	v1.3.1	v1.3.2	Added
Skills	127	127	—
Workflows	9	9	—
MCP Tools	49	49	—
Tool Servers	20	20	—

Other Highlights

• NValchemi batched MD gating: Re-benchmarked sequential vs. batched MD serially (no GPU contention) and found NValchemi batched MD is a win only for MACE (4.90x). Added a _nvalchemi_supports_batch_md flag that routes TensorNet and FairChem MD to the faster sequential path. TensorNet's light forward exposes a torch.compile/Warp neighbor-list stream race (officially supported by matgl.ext.alchmtk, so a hardware limitation, not an incompatibility) and is ~0.88x even when forced; FairChem uma-s-1p2's forward scales superlinearly per atom (1.57 ms/atom at batch=1 → 2.43 at batch=20) so batched MD is 0.64x.
• FairChem cutoff fix: Corrected the NValchemi FairChem wrapper's cutoff inference, which fell back to 12 Å / 500 neighbors instead of the model's true 6 Å / 300 (wrong attribute paths), making adapt_input build ~530 edges/atom of work that uma-s-1p2 discards (it runs with external_graph_gen=False). Added a robust _find_backbone walk.
• NValchemi fixed-batch relaxation: Switched to standard form cell mapping and scaled FIRE2 optimizer to prevent cell distortion during relaxation. Fixed trailing post-convergence step handling and enabled native convergence masking in fixed-batch mode. Disabled inflight batching for TensorNet to prevent neighbor-list OOB errors.
• MCP Server memory optimization: Implemented automatic GPU memory cleanup (gc.collect() and torch.cuda.empty_cache()) within MACE, MatGL, and FairChem relaxation and molecular dynamics handlers to prevent VRAM accumulation.
• Skills & documentation: Re-documented the NValchemi skill with corrected batched vs. sequential MD benchmarks for MACE, MatGL (TensorNet), and FairChem (UMA), and added a serial run_md_benchmark.py harness. Refined category tags on mass spectrometry and spectrum-matching skills.

v1.3.1

What's Changed

Repository Stats

Component	v1.3.0	v1.3.1	Added
Skills	127	127	—
Workflows	9	9	—
MCP Tools	49	49	—
Tool Servers	20	20	—

Other Highlights

• NValchemi Stability: Fixed batch relaxation memory issues; added PositionWrappingHook and ForceStressClippingHook to prevent exploding trajectories during GPU-parallel relaxation.
• NValchemi Cell Relaxation: Switched to FIRE2VariableCell with dt=0.05 for more stable variable-cell relaxations.
• M3GNet / CHGNet: Added _nvalchemi_supports_relax=False flag to skip NValchemi dispatch for models that do not support it; neighbor-list overflow and OOM errors now fall back gracefully to sequential relaxation.
• Tooling: Updated configure_mcp.py to expose AtomisticSkills skills globally for all registered agents.

v1.3.0

What's Changed

Repository Stats

Component	v1.2.0	v1.3.0	Added
Skills	126	127	+1
Workflows	9	9	—
MCP Tools	49	49	—
Tool Servers	20	20	—

New Skills

Skill	Description	Author
ml-mlip-nvalchemi	GPU-accelerated batched inference for MACE, MatGL (TensorNet/M3GNet/CHGNet), and FairChem MLIPs using NValchemi, enabling parallel static, relax, and MD workflows across multiple structures simultaneously.	@bowen-bd

Other Highlights

• NValchemi Integration: Integrated NVIDIA's NValchemi toolkit into base wrapper dispatch for GPU-parallel batch static, relax (FIRE), and MD (NVT/NPT/NVE) runs.
• Inflight batching: Implemented an evict-and-replace rolling GPU window (inflight batching) for FIRE relaxations to budget VRAM for very large structure sets.
• Model Wrappers: Created custom NValchemi wrappers for MatGL (M3GNet/CHGNet) and FairChem (UMA). Fixed MACE multi-head indexing to select the correct selected head (e.g., omat_pbe = head 5) instead of defaulting to head 0.
• Environments & CI: Upgraded mace-agent to Python 3.12 and added nvalchemi-toolkit dependencies to all MLIP conda environments.
• Test Stability: Fixed import-time NameErrors on HostMemory in basic environments, resolved M3GNet/CHGNet test assertions, and automated wrong-environment test skips via class-scoped autouse pytest fixtures.

v1.2.0

What's Changed

Repository Stats

Component	v1.1.0	v1.2.0	Added
Skills	121	126	+5
Workflows	9	9	—
MCP Tools	48	49	+1
Tool Servers	19	20	+1

New Skills

Skill	Description	Author
chem-msms-predict	Predict LC-MS/MS (MS2, tandem mass spectra) from SMILES via ICEBERG, a two-stage deep neural network.	@mlederbauer
chem-spectrum-matcher	Match an experimental spectrum (1H NMR, 13C NMR, IR) against predicted or database reference spectra for candidate ranking and structure confirmation.	@mlederbauer
general-biorxiv-search	Search and retrieve preprint metadata from bioRxiv and medRxiv APIs for biological and medical research.	@mlederbauer
general-fair-data-review	Review a manuscript or code repository for FAIR data compliance (Findable, Accessible, Interoperable, Reusable), producing a structured report with pass/fail per principle and actionable remediation steps.	@mlederbauer
mat-synthesis-extraction	Extract structured synthesis procedures from a folder of PDFs using the LeMat-Synth GeneralSynthesisOntology schema, producing one JSON file per paper with per-material synthesis records.	@mlederbauer

New MCP Tools

Tool	Server	Description	Author
get_atomate2_project_status	atomate2	Get an aggregated status summary of all jobs in the active jobflow-remote project.	@bowen-bd
predict_bandgap	matgl	Predict the bandgap for a structure using MEGNet-BandGap-mfi.	@bowen-bd

Other Highlights

• Chemistry skills: Added MS/MS prediction (ICEBERG) and spectrum matching skills for NMR/IR/MS workflows
• General skills: Added bioRxiv/medRxiv API search and FAIR data review skills
• Materials skills: Added LeMat-Synth-based synthesis extraction from PDF corpora
• matgl: Upgraded matgl-agent to Python 3.12 and matgl 4.x (PyG-only, DGL removed); added MEGNet-BandGap predict_bandgap tool with task_name support
• atomate2: Added get_atomate2_project_status for project-wide job status aggregation
• Fixes: Graceful src import fallback in skill scripts; msms-agent pytorch channel switched to conda-forge for ARM compatibility; fixed erroneous DGL uv package version ordering
• Docs: Added README skill-usage guide; added links to coding agents

v1.1.0

What's Changed

Repository Stats

Component	v1.0.0	v1.1.0	Added
Skills	119	121	+2
Workflows	9	9	—
MCP Tools	48	48	—
Tool Servers	19	19	—

New Skills

Skill	Description	Author
ml-bayesian-optimization	Iteratively optimize expensive black-box objectives — such as materials properties, experimental yields, or simulation outputs — by learning from past evaluations to select the most promising next candidates.	@bowen-bd
drug-pocket-detection	Identify and rank ligandable pockets on a protein structure or model using geometry (fpocket) or ML (P2Rank). Returns ranked pockets with lining residues, geometric center, volume, and druggability score.	@mcox3406
drug-mmpbsa-gbsa (renamed from drug-mmgbsa)	Compute single-trajectory MM-GBSA and/or MM-PBSA binding free energy estimates from a protein-ligand MD trajectory. Two backends: fast OpenMM GBn2 and AmberTools MMPBSA.py supporting both GB and PB.	@mcox3406

Other Highlights

• MCP: Atomate2 job tracker enhanced with sub-job aggregation and error extraction; research standards refactored with intent classification
• Skills: Off-equilibrium sampling now caches input parameters; ASE ExpCellFilter import compatibility fixed
• Sorption: Fixed unphysical repulsion via spin/charge normalization; ODAC Widom spin handling corrected (PR #31)
• GCMC: Fixed finite_or_none naming inconsistency and config path resolution
• Drug discovery: PBC correction in drug-mmgbsa; fpocket added to drugdisc-agent
• Config: Multi-agent support in configure_mcp.py
• Docs & CI: Documentation website launched; GitHub Pages deployment; pre-commit hooks with ruff; README updated with video demo, arXiv badge, and citation

Initial Release

AtomisticSkills is a composable framework for AI-driven atomistic materials research. Built on the hierarchical decomposition of complex scientific tasks into Workflows → Skills → Tools, it enables coding AI agents to autonomously conduct multi-stage materials, chemistry, and drug discovery research by combining modular, reusable capabilities.

The framework integrates state-of-the-art Machine Learning Interatomic Potentials (MLIPs), DFT calculations, generative AI, database APIs, and advanced simulation methods through the Model Context Protocol (MCP) tools and Skills, making advanced materials research accessible to AI copilots.

Included in this release

• 9 Workflows: End-to-end research campaign templates that combine multiple skills to solve high-level scientific goals.
• 119 Skills: Pre-configured tutorials and scripts covering an extensive range of research tasks in chemistry, materials science, and drug discovery.
• 48 MCP Tools: Fundamental research primitives directly callable by AI agents, spanning molecular dynamics, DFT preparation, relaxation, and analysis.
• 19 Tool Servers: Specialized backend integrations providing unified interfaces to MACE, MatGL, FAIRCHEM, Atomate2, MatterGen, SMOL, ADiT, DiffCSP, and more.

Key Features

• Simulation Infrastructure: Multi-framework MLIP support with unified APIs for relaxation, MD, and fine-tuning. Includes DFT integration via Atomate2 and ORCA, and cluster expansion via SMOL.
• Database APIs: Query structures, properties, bioactivity data, and literature from Materials Project, ChEMBL, PDB, PubChem, and ArXiv.
• Property Evaluation: Extensive tools for computing thermodynamic stability, phase diagrams, phonons, QHA thermal expansion, elastic tensors, melting points, ionic diffusion, NEB barriers, surface energies, and more.
• Experimental & Machine Learning Tools: Features for synthesis recommendation, XRD calculation, ADMET prediction, molecular docking, MLIP fine-tuning, benchmarking, and generative crystal design via MatterGen.

Contributors

A huge thank you to everyone who contributed skills to this release:

• Bowen Deng (76 skills)
• Matthew Cox (17 skills)
• Miguel Steiner (3 skills)
• Jesus Diaz Sanchez (3 skills)
• Juno Nam (3 skills)
• Yu Yao (3 skills)
• Artur Lyssenko (3 skills)
• Nofit Segal (2 skills)
• Sathya Edamadaka (2 skills)
• Sauradeep Majumdar (2 skills)
• ChazzBM3 (1 skill)
• Mingrou Xie (1 skill)
• Ty Perez (1 skill)
• Bohan Li (1 skill)
• Jurģis Ruža (1 skill)