How to use the pymatgen Materials Toolkit agent skill

What the pymatgen skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches its description. This one covers compositions, molecules, periodic structures, computed entries, symmetry, phase diagrams and electronic-structure files, using the pymatgen library.

The skill asks the agent to state whether an object is a non-periodic Molecule or periodic Structure, state units and coordinate mode, inspect every parser warning, report partial occupancies and oxidation states, and sweep symmetry tolerances rather than picking one that gives a preferred answer. Every derived file is treated as a new artifact with parent and child checksums.

• Validate compositions and structures, including CIF parser and Python warnings
• Report space-group symmetry across a range of tolerances
• Plan format conversions before any file is written
• Build phase diagrams from energies you supply
• Optionally query the Materials Project database with an API key

Install the pymatgen skill

Download the ZIP from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder.

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill needs Python 3.11+ and the uv package manager. The SKILL.md file lists pinned packages (pymatgen==2026.9.24, pymatgen-core==2026.9.23, mp-api==0.46.5) that are installed for local scientific execution. Create a project environment with uv only when you are ready to run analysis.

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

How to trigger the skill with natural requests

The agent loads the skill when your request matches its description: phase diagrams, symmetry sensitivity, electronic-structure I/O, format conversion, structure validation or bounded Materials Project queries. You do not need to name the skill, but naming pymatgen makes it more likely to be used.

Give the file, the composition or the question. The more specific you are about what you want checked, the more the agent can follow the skill's workflow.

• "Validate this CIF with pymatgen and list any parser warnings and partial occupancies."
• "Check the space group of structure.cif across symprec 0.001, 0.01 and 0.1 Å."
• "Plan how to convert this structure to another format without overwriting the input."
• "Build a phase diagram from these supplied energies and state the correction scheme."

Run the bundled helper scripts

The skill ships small command-line helpers. The validator and planning tools use only the Python standard library. Local scientific execution lazily requires the pinned pymatgen packages.

The structure analyzer reports symmetry for a file, and the symmetry sensitivity report sweeps tolerances. The distance report compares distinct sites under periodic boundary conditions, but it is not a complete check for contacts across very short lattice vectors.

• scripts/composition_structure_validator.py: validate a composition or structure
• scripts/structure_analyzer.py: analyze a structure, optionally with symmetry
• scripts/symmetry_sensitivity_report.py: sweep symprec and angle tolerance
• scripts/io_conversion_plan.py: plan a conversion before any file is opened
• scripts/phase_diagram_generator.py: build a phase diagram from supplied entries
• scripts/mp_query.py: bounded Materials Project query, only with approval
• scripts/artifact_manifest.py: record checksums and provenance

Understand what the skill needs and what it can touch

The skill runs local Python scripts. Materials Project access additionally needs explicit network approval and the single named secret MP_API_KEY. Without that approval and key, the database queries are not run. The MIT license covers the skill; pymatgen and pymatgen-core are MIT, mp-api declares BSD-3-Clause-LBNL, and Materials Project data is generally CC BY 4.0, with contributed data owned by its contributors.

Parsers process the contents of the files you give them. Do not parse untrusted CIF or structure files on a machine that holds sensitive credentials, and use isolation with CPU, memory, disk and time limits.

• Python 3.11+ and uv
• Optional: MP_API_KEY secret for Materials Project access
• Network approval is required for any Materials Project query
• Pickle is not used; the skill expects schema-validated JSON

Example workflow: validate a structure and check symmetry

Start by validating the file so warnings are visible before any analysis. Then sweep symmetry tolerances and read the space group at each setting. If the answer changes between tolerances, report that instead of choosing one.

Keep the input file unchanged. Any converted or transformed output should go to a new path, and the artifact manifest should record the input, parameters, software versions and checksums.

• Validate the composition and structure
• Read parser warnings and occupancy reports
• Run the symmetry sensitivity report
• Record the artifact manifest

Tips for reliable results

Units and coordinate mode matter. Structure coordinates are fractional unless you say otherwise, and Molecule coordinates are Cartesian. Ask the agent to state both before trusting a result.

A computed phase diagram is only as good as the entries you supply. Use compatible total energies and the same correction scheme for all entries.

• Pin the lock file and keep uv.lock with your results
• Compare symmetry across tolerances; the Materials Project pipeline uses symprec 0.1 Å while the pymatgen default is 0.01 Å
• Ask for a sensitivity report instead of tuning tolerance until an answer looks right