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.