Skip to content
Conduit

skill

MatClaw

bjzgcai/MatClawcommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/bjzgcai/MatClaw itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 26, 2026

Contents

What is MatClaw?

MatClaw is an AI agent that autonomously performs materials science computations. You describe a task in natural language — it writes Python/shell scripts, runs them inside an isolated Docker container equipped with a full computation stack, and returns the results.

Key Features:

  • Autonomous computation — Understands your task, writes code, executes it, analyzes output, retries on errors
  • 240 built-in skills — 47 skill groups covering computational materials science (electronic structure, phonons, mechanical properties, defects, optics, magnetism, catalysis, batteries, phase diagrams, Monte Carlo, molecular dynamics, and more) plus general research tools (literature search, plotting, document creation, data analysis). Each skill contains complete runnable scripts, parameter guides, and method selection decision trees. See Materials Compute Skills Reference for the full inventory.
  • VASP support — Connect your own VASP installation via SSH (HPC cluster) or local mount. The agent generates inputs, submits jobs, and parses results automatically. See VASP Integration.
  • GPU acceleration — Optional CUDA-enabled container (./container/build.sh --cuda) for GPU-accelerated MACE, CHGNet, SevenNet, and MatGL. Auto-detects GPU at runtime with graceful CPU fallback.
  • Multiple MLIP models — MACE-MP-0 (pre-installed), CHGNet, SevenNet, MatGL — all pre-installed and ready for rapid screening and molecular dynamics
  • All-in-one container — QE 7.5, LAMMPS, RASPA3, MACE, pymatgen, ASE, PyTorch pre-installed and ready
  • Secure isolation — Every computation runs in a disposable Docker container with filesystem isolation
  • Flexible LLM backend — Works with Anthropic Claude, DeepSeek, or any Anthropic-compatible API
  • Multi-channel access — Chat via Feishu, DingTalk, Gmail, WhatsApp, Telegram, Discord, Slack
  • Chat commands — /watch, /status, /stop, /sessions, /new, /resume, /compact — manage sessions, monitor progress, and control the agent directly from chat
  • Real-time dashboard — Web UI at localhost:3210 with live agent activity, parsed transcripts, and container logs
  • Extensible — Conda/pip available inside container; agent can install additional packages on-the-fly

Chat Commands

Control the agent directly from any messaging channel — no terminal or dashboard required.

CommandDescription
/watchSee what the agent is doing right now (recent tool calls, reads, bash commands)
/statusAgent status — running/idle, current session, container name, queued tasks
/stopForce stop a running agent
/sessionsList all conversation sessions (ID, timestamp, size, active marker)
/newStart a fresh conversation with no prior memory
/resume [id]Restore previous session, or switch to any session by ID prefix
/compact [focus]Compress agent memory. Optionally specify what to keep (e.g. /compact keep only VASP config)
/helpShow all available commands

Session management — Every conversation is a resumable session. Use /new to start clean, /sessions to browse history, and /resume to jump back to any previous context. The agent picks up exactly where it left off.

Real-time monitoring — Send /watch at any time to see the agent's recent activity without waiting for it to finish. For a full graphical view, open the built-in dashboard at http://localhost:3210.

Built-in Computation Skills

MatClaw ships with 240 SKILL.md files across 47 skill groups, covering the full spectrum of computational materials science plus general research tools. Each skill contains complete runnable scripts, parameter guides, method selection decision trees, and troubleshooting tables — enabling the agent to autonomously execute any mainstream materials computation workflow.

47 groups / 195 sub-skills / 240 SKILL.md files

#Skill GroupSub-SkillsContents
12d-materials4band-edges, layer-manipulation, stacking-energy, vacuum-resize
2advanced-electronic5gw-approximation, hubbard-u, spin-orbit-coupling, topological-invariants, van-der-waals
3agent-browser0(browser automation, non-computation)
4alloy-disorder2cluster-expansion, sqs-generation
5band-advanced33d-band-structure, band-unfolding, hybrid-dft-bands
6battery-electrode2intercalation-voltage, ion-diffusion
7biomolecular-md1openmm-simulation
8bonding-analysis10bader2pqr, bader-charge, charge-density, charge-density-difference, charge-format-conversion, elf-analysis, lobster-cohp, orbital-projection, planar-charge, stm-simulation
9catalysis-electrochem6band-center, imaginary-freq-correction, implicit-solvation, neb-analysis, reaction-kinetics, thermal-corrections
10catalyst-screening3d-band-center, overpotential, scaling-relations
11code-interfaces5boltztrap-interface, ifc-analysis, phonopy-interface, vasp-qe-converter, wannier90-interface
12deepchem0(molecular ML: property prediction, GNNs, transfer learning)
13defects-reactions13activation-relaxation-technique, adsorption-energy, configuration-coordinate, defect-thermodynamics, interstitial-defect, migration-barrier, neb-transition-state, point-defect, reaction-pathway, substitution-defect, surface-adsorption, surface-energy, vacancy-formation
14dft-corrections3hubbard-u, spin-orbit-coupling, vdw-correction
15electronic-structure8band-structure, convergence-testing, density-of-states, inverse-participation-ratio, projected-dos, scf-relax, spatially-resolved-dos, vasp-bands
16electron-phonon4deformation-potential, electronic-transport, elph-coupling, superconductivity
17fermi-surface32d-fermi-surface, 3d-fermi-surface, projected-fermi-surface
18ferroelectric5born-effective-charge, dielectric-tensor, ferroelectric-switching, piezoelectric, polarization
19general-tools16(see General Research Tools below)
20high-throughput8batch-calculations, batch-screening, convergence-automation, materials-filtering, matpes-dual-static, phase-stability, property-prediction, screening-workflow
21interface2grain-boundary, heterostructure
22kpath-utilities51d-kpath, 2d-kpath, bulk-kpath, cp2k-kpath, phonopy-kpath
23magnetic-properties3magnetic-anisotropy, magnetic-ordering, spin-polarized
24materials-compute0(root skill: QE/LAMMPS/MACE environment reference)
25materials-databases22d-semiconductors, materials-project
26mechanical-properties5angular-mechanics, elastic-constants, energy-strain-method, equation-of-state, stress-strain-method
27mlip-guide4mace-advanced, mlip-validation, torchsim-batch, universal-mlip
28molecular-qchem1gaussian-qchem-workflow
29monte-carlo5adsorption-isotherm, gas-adsorption, gas-separation, gcmc-simulation, pore-analysis
30optical-properties6absorption-spectrum, dielectric-function, joint-dos, optical-conductivity, slme, transition-dipole
31phase-diagram2convex-hull, pourbaix-diagram
32phase-transition6amorphous-structure, melting-point-coexistence, metadynamics, mpmorph-melting, order-parameter, phase-diagram
33piezoelectric1piezoelectric-tensor
34potential-analysis3macroscopic-average, planar-average, work-function
35rdkit0(cheminformatics: SMILES, descriptors, fingerprints, similarity)
36semiconductor-kit4angular-effective-mass, band-gap, effective-mass, fermi-velocity
37spectroscopy2raman-ir, xas-xanes
38spin-texture22d-spin-texture, 3d-spin-texture
39structure-models8alloy-builder, defect-builder, heterostructure, moire-superlattice, nanowire-nanotube, quantum-dot, supercell-builder, surface-builder
40structure-tools8advanced-optimization, format-conversion, input-generation, pdf-analysis, structure-editing, structure-matching, symmetry-analysis, xrd-pattern
41surface-energy2surface-energy-calc, wulff-construction
42thermal-properties13anharmonicity, bond-distribution, free-energy-calculation, gruneisen-qha, md-trajectory-tools, molecular-dynamics, msd-diffusion, phonon, phonon-from-outcar, quasi-harmonic-debye, rdf-analysis, thermal-conductivity, vacf-vdos
43thermoconductivity1lattice-thermal-conductivity
44topological2berry-curvature, z2-invariant
45transport-properties2boltzmann-transport, kpoints-transport
46wannier-functions1wannier90-workflow
47wavefunction-analysis2real-space-wavefunction, wavefunction-parity

Coverage: electronic structure, mechanics, thermodynamics, phonons, defects, optics, magnetism, topology, catalysis, batteries, phase diagrams, ferroelectric/piezoelectric, transport, surfaces, interfaces, 2D materials, alloys, Monte Carlo, molecular dynamics, machine learning potentials, biomolecular simulation, quantum chemistry, cheminformatics, and more. Verified against atomate2, aiida-quantumespresso, and aiida-vasp — all workflow capabilities are covered. See Materials Compute Skills Reference for detailed descriptions of each skill.

General Research Tools

Beyond materials computation, MatClaw includes 16 general-purpose research skills for literature search, visualization, document creation, and data analysis — grouped under general-tools.

CategorySkillsDescription
Literature & Citationarxiv-database, openalex-database, citation-managementSearch arXiv / OpenAlex (240M+ papers), DOI → BibTeX
Visualizationmatplotlib, plotly, seaborn, scientific-visualizationPublication-quality plots, interactive charts, journal figures
Documentsscientific-writing, pptx, docx, pdf, latex-posters, xlsxManuscripts, presentations, posters, spreadsheets
Data Analysisstatistical-analysis, exploratory-data-analysis, sympyStatistical tests, EDA for 200+ formats, symbolic math

All general tools run locally with no external API keys required.

Basic Usage

Send a natural language task via any connected channel (Feishu, WhatsApp, Gmail, etc.) or directly via Docker:

echo '{
  "prompt": "Calculate the band gap of silicon using DFT (Quantum ESPRESSO)",
  "groupFolder": "test",
  "chatJid": "test@g.us",
  "isMain": false,
  "secrets": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}' | docker run -i -v ./workspace:/workspace/group matclaw-agent:latest

The agent will autonomously:

  1. Parse your request and plan the computation
  2. Write input files and scripts
  3. Run the simulation (DFT, MD, MC, or MLIP)
  4. Analyze results, generate plots, and report back
  5. Retry with adjustments if errors occur

Results — including figures, data files, and structured summaries — are returned directly.

Examples

Benchmark tasks adapted from QUASAR. All executed autonomously — the agent writes scripts, runs simulations, and reports results. See examples/ for full details.

Basic Tasks

Cu K-point Convergence (DFT / Quantum ESPRESSO)

Converge bulk Cu energy to < 1 meV/atom. Agent runs 8 QE calculations and plots the convergence curve.

Water Density (MD / LAMMPS)

Calculate the density of water at 298 K, 1 bar. Agent builds a SPC/E water box, runs NPT, and reports with diagnostic plots.

IRMOF-1 Void Fraction (MC / RASPA3)

Compute helium-accessible void fraction for IRMOF-1 at 298 K. Agent configures RASPA3 Widom insertion MC.

Workflow Orchestration

NiO Band Gap (DFT+U / Quantum ESPRESSO)

Calculate the electronic band gap of NiO. Agent recognizes a strongly correlated system and autonomously applies DFT+U.

[!TIP] The agent was only asked to "calculate the band gap of NiO" — it independently decided DFT+U was necessary for a correlated oxide, chose appropriate U values, and ran the full SCF → NSCF → DOS workflow.

CO₂ Adsorption in UiO-66 (MC / RASPA3)

Calculate CO₂ adsorption isotherm at 4 pressure points. Agent runs GCMC simulations and generates the isotherm plot.

Al Melting Point (MD / LAMMPS)

Determine the melting point of aluminum via two-phase coexistence. Agent builds an 8000-atom system and analyzes with bond-order parameters.

NaCl Solution Density (MD / LAMMPS + packmol)

Calculate density of 1 mol/L NaCl solution. Agent autonomously installs packmol (not pre-installed), builds the system, and runs MD.

[!TIP] packmol was not pre-installed in the container. The agent detected the missing dependency, downloaded and compiled it from source (retrying 3 times with different approaches), then proceeded with the simulation.

Results Summary

ExampleMethodEngineReferenceAgent Result
Cu k-point convergenceDFTQE< 1 meV/atomConverged at 12×12×12
Water densityMDLAMMPS0.997 g/cm³0.985 g/cm³
IRMOF-1 void fractionMCRASPA30.79880.8025
NiO band gapDFT+UQE4.0 eV2.11 eV
CO₂ in UiO-66MCRASPA35.98 mmol/g5.48 mmol/g
Al melting pointMDLAMMPS933 K~850–880 K
NaCl solution densityMDLAMMPS1.038 g/cm³1.033 g/cm³

Computation Stack

EngineVersionMethodUse Cases
Quantum ESPRESSO7.5DFTElectronic structure, band gaps, DOS, phonons, elastic constants
LAMMPS2021MDThermal properties, diffusion, mechanical properties, phase transitions
RASPA33.0.16MCGas adsorption in MOFs/zeolites, isotherms, Henry constants
VASP5.x / 6.xDFTFull-featured DFT via external connection (setup guide)
MACE-MP-0latestMLIPUniversal ML potential, fast energy/force/stress predictions
PackagePurpose
pymatgenCrystal structures, phase diagrams, electronic structure analysis
ASEAtoms objects, calculators, optimization, molecular dynamics
MACE-torchUniversal ML interatomic potentials
mp-apiMaterials Project database access
spglibSpace group / symmetry analysis
PyTorchML framework (CPU)
numpy, scipy, matplotlib, pandas, seabornScientific computing & visualization

Quick Start

One-command setup (recommended)

git clone https://github.com/DingyangLyu/MatClaw.git
cd MatClaw
npm install && npm run setup

The interactive wizard guides you through environment check, container setup, API configuration, smoke test, and channel selection — step by step.

Prerequisites

  • Linux (Ubuntu 24.04+ recommended) or macOS
  • Docker
  • An Anthropic-compatible API key (Claude, DeepSeek, or 44 other providers)

Manual setup

1. Get the container

Option A — Pull pre-built image (recommended):

docker pull ghcr.io/dingyanglyu/matclaw-agent:latest
docker tag ghcr.io/dingyanglyu/matclaw-agent:latest matclaw-agent:latest

For GPU support:

docker pull ghcr.io/dingyanglyu/matclaw-agent:cuda
docker tag ghcr.io/dingyanglyu/matclaw-agent:cuda matclaw-agent:cuda

Option B — Build from source:

git clone https://github.com/DingyangLyu/MatClaw.git
cd MatClaw
./container/build.sh          # CPU
./container/build.sh --cuda   # GPU (requires NVIDIA Container Toolkit)

[!NOTE] Building from source takes ~10 minutes (compiles QE 7.5). Pulling the pre-built image is much faster.

2. Run a computation

echo '{
  "prompt": "Calculate the energy of bulk silicon using MACE-MP-0",
  "groupFolder": "test",
  "chatJid": "test@g.us",
  "isMain": false,
  "secrets": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}' | docker run -i -v ./workspace:/workspace/group matclaw-agent:latest

3. Full agent setup with messaging channels

npm install
npm run dev

Configure at least one messaging channel to chat with your agent:

  • Feishu (飞书) — WebSocket connection, no public URL needed. Recommended for China users.
  • DingTalk (钉钉) — Stream Mode (WebSocket), no public URL needed. Auto-registers groups on first message.
  • Gmail — Send computation tasks via email, receive results back.
  • WhatsApp — Add via /add-whatsapp skill, QR code authentication.
  • Telegram — Add via /add-telegram skill, Bot API.
  • Discord / Slack — Add via /add-discord or /add-slack skill.

Channels are added via the skill system — run the corresponding /add-* command inside claude CLI.

Architecture

┌──────────────────────────────────────────────────────┐
│  Host (Node.js)                                      │
│  ┌────────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │  Channels   │→│  SQLite   │→│  Container Runner │ │
│  │  (WhatsApp, │  │  (msgs,   │  │  (spawns Docker  │ │
│  │  Telegram,  │  │  tasks,   │  │   containers)    │ │
│  │  Discord…)  │  │  state)   │  └────────┬─────────┘ │
│  └────────────┘  └──────────┘           │           │
└──────────────────────────────────────────┼───────────┘
                                           │ stdin/stdout JSON
┌──────────────────────────────────────────┼───────────┐
│  Container (Ubuntu 24.04)                │           │
│  ┌───────────────────────────────────────┘         │ │
│  │  Agent Runner (Claude Agent SDK)                │ │
│  │  ┌─────────────────────────────────────────┐    │ │
│  │  │  LLM ←→ Tool Use (bash, browser, MCP)  │    │ │
│  │  └─────────────────────────────────────────┘    │ │
│  │                                                  │ │
│  │  Computation Tools:                              │ │
│  │  ┌─────────┐ ┌────────┐ ┌───────┐ ┌──────┐     │ │
│  │  │ QE 7.5  │ │ LAMMPS │ │RASPA3 │ │ MLIP │     │ │
│  │  └─────────┘ └────────┘ └───────┘ └──────┘     │ │
│  │  ┌──────────────────────────────────────────┐   │ │
│  │  │ Python: pymatgen, ASE, torch, numpy, …   │   │ │
│  │  └──────────────────────────────────────────┘   │ │
│  └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

How it works:

  1. User sends a natural language prompt (via stdin JSON or messaging channel)
  2. Host orchestrator routes it to a fresh Docker container
  3. Inside the container, Claude Agent SDK receives the prompt and iteratively:
    • Writes computation scripts (Python, shell, QE input files, LAMMPS scripts…)
    • Executes them via bash tool
    • Reads and analyzes output
    • Retries or adjusts if errors occur
  4. Final results returned to user via stdout markers

For full architecture details, see docs/SPEC.md. For the security model and container isolation design, see docs/SECURITY.md.

API Keys

MatClaw works with any Anthropic-compatible API. Pass credentials via stdin JSON:

{
  "secrets": {
    "ANTHROPIC_API_KEY": "your-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

Tested providers:

ProviderBase URLNotes
Anthropichttps://api.anthropic.comClaude models, recommended
DeepSeekhttps://api.deepseek.com/anthropicCost-effective, tool_use support

Environment Variables

VariableDefaultDescription
CONTAINER_RUNTIMEdockerContainer runtime (docker, podman, nerdctl)
MAX_CONCURRENT_CONTAINERS5Max parallel agent containers
AGENT_TIMEOUT300Agent execution timeout (seconds)

Contributing

We welcome contributions — especially new computation skills! Adding a skill is as simple as writing a single SKILL.md file with runnable scripts and parameter guides. No need to touch core code.

container/skills/<group>/<your-skill>/SKILL.md

See CONTRIBUTING.md for the full guide, including the SKILL.md template, testing instructions, and PR workflow.

Acknowledgments

MatClaw is built on NanoClaw and relies on the following open-source projects:

  • Quantum ESPRESSO — DFT calculations
  • LAMMPS — Molecular dynamics
  • RASPA3 — Monte Carlo simulations
  • MACE — Machine learning interatomic potentials
  • pymatgen — Python materials analysis
  • ASE — Atomic simulation environment
  • Claude Agent SDK — AI agent framework
  • QUASAR — Benchmark test cases referenced from this project
  • claude-scientific-skills by K-Dense AI — General research tools (RDKit, DeepChem, arXiv, matplotlib, scientific writing, and more)

The built-in computation skills were designed and verified against the following workflow frameworks:

  • atomate2 — Materials Project's computational workflows (VASP, QE, force fields, and more)
  • pyiron_atomistics — Integrated materials science workflow platform (Murnaghan EOS, QHA, SQS, Debye model, ART, metadynamics, and more)
  • VASPKIT — VASP pre-/post-processing toolkit
  • AiiDA — Automated Interactive Infrastructure and Database for Computational Science
  • aiida-quantumespresso — AiiDA plugin for Quantum ESPRESSO workflows
  • aiida-vasp — AiiDA plugin for VASP workflows
matclaw/
├── src/                        # Host orchestrator
│   ├── index.ts                # Main loop: messages, agents, scheduling
│   ├── container-runner.ts     # Spawns isolated Docker containers
│   ├── db.ts                   # SQLite (messages, tasks, state)
│   ├── channels/               # Messaging channel registry
│   └── ...
├── container/
│   ├── Dockerfile              # Multi-stage build (QE builder + runtime)
│   ├── agent-runner/           # Claude Agent SDK runner (inside container)
│   └── skills/                 # 240 skills (47 groups)
│       ├── materials-compute/  # Root: computation engine docs
│       ├── electronic-structure/  # Band structure, DOS, SCF
│       ├── thermal-properties/    # Phonons, QHA, MD, thermal transport
│       ├── mechanical-properties/ # Elastic constants, EOS
│       ├── defects-reactions/     # Defects, NEB, adsorption, CCD
│       ├── optical-properties/    # Dielectric function, absorption
│       ├── magnetic-properties/   # Spin ordering, MAE
│       ├── topological/           # Z2, Berry curvature
│       ├── catalysis-electrochem/ # Reaction kinetics, d-band
│       ├── monte-carlo/           # GCMC, gas adsorption (RASPA3)
│       ├── rdkit/                 # Cheminformatics (SMILES, fingerprints)
│       ├── deepchem/              # Molecular ML (GNNs, property prediction)
│       ├── general-tools/         # Research tools (arXiv, plotting, docs)
│       ├── ...                    # 33 more groups
│       └── agent-browser/         # Browser automation
└── groups/                     # Per-group isolated memory

Documentation

DocumentDescription
Architecture SpecFull system architecture and design
Security ModelContainer isolation and trust model
RequirementsOriginal requirements and design decisions
TroubleshootingDocker build, WSL, runtime, channel, and computation issues
Feishu SetupFeishu channel configuration guide
DingTalk SetupDingTalk channel configuration guide
Gmail SetupGmail channel configuration guide
SDK Deep DiveClaude Agent SDK internals
Materials Compute SkillsFull inventory of 240 built-in skills
VASP IntegrationConnect your VASP installation (SSH or local)
Creating SkillsHow to create a new skill (template included)
Skills ArchitectureHow the skill system works (internals)

Roadmap

  • GPU support (CUDA 12.8 container for PyTorch/MACE — ./container/build.sh --cuda)
  • More MLIP models (CHGNet, SevenNet, MatGL pre-installed)
  • Materials Project integration (set MP_API_KEY in .env — query structures, phase diagrams, properties)
  • Workflow automation (multi-step calculation pipelines)
  • Jupyter notebook generation for reproducibility

Citation

If you use MatClaw in your research, please cite:

@software{matclaw2026,
  title  = {MatClaw: AI-Powered Autonomous Materials Science Agent},
  author = {Dingyang Lyu and Baole Wei and Hongwei Du and Yongheng Li and Feng Yu},
  email  = {s-ldy25@bza.edu.cn, weibaole@zgci.ac.cn, duhongwei@zgci.ac.cn},
  year   = {2026},
  url    = {https://github.com/DingyangLyu/MatClaw}
}

License

Apache License 2.0

↑↓ navigate openesc close