SchrodingersCattt · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/skills/README.md b/skills/README.md
@@ -0,0 +1,14 @@
+# dpdata agent skills
+
+Start with [`dpdata-workflows`](dpdata-workflows/SKILL.md) to route a request by
+user intent.
+
+- [`dpdata-convert`](dpdata-convert/SKILL.md) converts producer outputs and
+  checks the labeled-data contract.
+- [`dpdata-inspect`](dpdata-inspect/SKILL.md) inspects and validates systems,
+  including the deterministic validator in `scripts/`.
+- [`dpdata-extend`](dpdata-extend/SKILL.md) groups developer references for
+  format plugins, drivers, and minimizers.
+
+The historical `dpdata-cli`, `dpdata-driver`, `dpdata-minimizer`, and
+`dpdata-plugin` directories remain compatibility entry points.
diff --git a/skills/dpdata-cli/README.md b/skills/dpdata-cli/README.md
@@ -1,71 +1,6 @@
-# dpdata CLI Agent Skill
+# dpdata CLI skill (compatibility entry point)
 
-An Agent Skill for using [dpdata](https://github.com/deepmodeling/dpdata) CLI to convert and manipulate atomic simulation data formats.
-
-## Installation
-
-To install this skill, provide the skill's GitHub URL to your agent (e.g., OpenClaw):
-
-```text
-Install the dpdata-cli skill from https://github.com/deepmodeling/dpdata/tree/devel/skills/dpdata-cli
-```
-
-Or manually copy to your agent's skills directory:
-
-```bash
-cp -r skills/dpdata-cli /path/to/your/agent/skills/
-```
-
-## Usage
-
-Once installed, ask your AI agent to work with dpdata:
-
-```text
-Convert my VASP OUTCAR to DeePMD-kit format
-```
-
-```text
-Convert LAMMPS dump file to VASP POSCAR
-```
-
-## Features
-
-- **Format Conversion**: Convert between 50+ DFT/MD formats
-- **DeePMD-kit Support**: Prepare training data for machine learning potentials
-- **Auto-detection**: Automatic format detection for common file types
-- **Multi-system Support**: Handle directories with multiple systems
-
-## Supported Formats
-
-Formats may be updated. See [Formats Reference (stable)](https://docs.deepmodeling.com/projects/dpdata/en/stable/formats.html) for the latest list.
-
-### DeePMD-kit
-
-`deepmd/raw`, `deepmd/comp`, `deepmd/npy`, `deepmd/npy/mixed`, `deepmd/hdf5`
-
-### VASP
-
-`vasp/poscar`, `vasp/contcar`, `vasp/outcar`, `vasp/xml`
-
-### LAMMPS
-
-`lammps/lmp`, `lammps/dump`
-
-### ABACUS
-
-`stru`, `abacus/scf`, `abacus/md`, `abacus/relax`
-
-### And many more...
-
-QE, CP2K, Gaussian, ORCA, PSI4, FHI-aims, SIESTA, PWmat, AMBER, GROMACS, ASE, pymatgen, XYZ, etc.
-
-## Requirements
-
-- [uv](https://docs.astral.sh/uv/) for running dpdata via `uvx`
-
-## References
-
-- [dpdata Documentation](https://docs.deepmodeling.com/projects/dpdata/)
-- [CLI Reference](https://docs.deepmodeling.com/projects/dpdata/en/stable/cli.html)
-- [Formats Reference](https://docs.deepmodeling.com/projects/dpdata/en/stable/formats.html)
-- [GitHub Repository](https://github.com/deepmodeling/dpdata)
+Use [`skills/dpdata-convert`](../dpdata-convert/SKILL.md) for new conversion
+work. It includes the command reference, data-contract checks, and links to
+producer-specific references. The `dpdata-cli` path remains available for
+existing agent installations.
diff --git a/skills/dpdata-cli/SKILL.md b/skills/dpdata-cli/SKILL.md
@@ -1,222 +1,17 @@
 ---
 name: dpdata-cli
-description: Convert and manipulate atomic simulation data formats using dpdata CLI. Use when converting between DFT/MD output formats or preparing DeePMD-kit training data. Supports 50+ formats including deepmd, xyz or extxyz, ABACUS, VASP, LAMMPS, CP2K, etc.
-compatibility: Requires uvx (uv) for running dpdata
+description: Compatibility entry point for the dpdata conversion workflow. Use dpdata-convert for user-facing conversion and data-contract validation.
+compatibility: Requires uvx (uv) for the command examples.
 metadata:
-  author: njzjz-bot
-  version: '1.0'
   repository: https://github.com/deepmodeling/dpdata
 ---
 
-# dpdata CLI
+# dpdata CLI compatibility entry point
 
-dpdata is a tool for manipulating multiple atomic simulation data formats. This skill enables format conversion between various DFT/MD software outputs via command line.
+Conversion requests now use [`dpdata-convert`](../dpdata-convert/SKILL.md),
+which combines the command reference with semantic validation and producer
+contracts. This path remains so existing agents that request `dpdata-cli`
+continue to resolve.
 
-## Quick Start
-
-Run dpdata via uvx:
-
-```bash
-uvx dpdata <from_file> [options]
-```
-
-## Command Line Usage
-
-```text
-dpdata: Manipulating multiple atomic simulation data formats
-usage: dpdata [-h] [--to_file TO_FILE] [--from_format FROM_FORMAT]
-              [--to_format TO_FORMAT] [--no-labeled] [--multi]
-              [--type-map TYPE_MAP [TYPE_MAP ...]] [--version]
-              from_file
-```
-
-### Arguments
-
-| Argument              | Description                                           |
-| --------------------- | ----------------------------------------------------- |
-| `from_file`           | Read data from a file (positional)                    |
-| `--to_file`, `-O`     | Dump data to a file                                   |
-| `--from_format`, `-i` | Format of from_file (default: "auto")                 |
-| `--to_format`, `-o`   | Format of to_file                                     |
-| `--no-labeled`, `-n`  | Labels aren't provided (default: False)               |
-| `--multi`, `-m`       | System contains multiple directories (default: False) |
-| `--type-map`, `-t`    | Type map for atom types                               |
-| `--version`           | Show dpdata version and exit                          |
-
-## Common Examples
-
-### Convert VASP OUTCAR to deepmd format
-
-```bash
-uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw
-```
-
-### Convert LAMMPS dump to VASP POSCAR
-
-```bash
-uvx dpdata dump.lammps -i lammps/dump -O POSCAR -o vasp/poscar
-```
-
-### Convert with type map
-
-```bash
-uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw -t C H O N
-```
-
-### Convert multiple systems
-
-```bash
-uvx dpdata data_dir -i vasp/outcar -O output_dir -o deepmd/comp --multi
-```
-
-### Convert to deepmd/npy (compressed format)
-
-```bash
-uvx dpdata OUTCAR -i vasp/outcar -O deepmd_npy -o deepmd/npy
-```
-
-### Convert to deepmd/hdf5
-
-```bash
-uvx dpdata OUTCAR -i vasp/outcar -O data.h5 -o deepmd/hdf5
-```
-
-## Supported Formats
-
-Formats may be updated. For the complete and latest list, see:
-
-- [Formats Reference (stable)](https://docs.deepmodeling.com/projects/dpdata/en/stable/formats.html)
-
-### DeePMD-kit Formats
-
-| Format Name                  | Description                        |
-| ---------------------------- | ---------------------------------- |
-| `deepmd/raw`                 | DeePMD-kit raw text format         |
-| `deepmd/comp` / `deepmd/npy` | DeePMD-kit compressed numpy format |
-| `deepmd/npy/mixed`           | DeePMD-kit mixed type format       |
-| `deepmd/hdf5`                | DeePMD-kit HDF5 format             |
-
-### VASP Formats
-
-| Format Name                                           | Description          |
-| ----------------------------------------------------- | -------------------- |
-| `vasp/poscar` / `vasp/contcar` / `poscar` / `contcar` | VASP structure files |
-| `vasp/outcar` / `outcar`                              | VASP OUTCAR output   |
-| `vasp/xml` / `xml`                                    | VASP XML output      |
-| `vasp/string`                                         | VASP string format   |
-
-### LAMMPS Formats
-
-| Format Name            | Description      |
-| ---------------------- | ---------------- |
-| `lammps/lmp` / `lmp`   | LAMMPS data file |
-| `lammps/dump` / `dump` | LAMMPS dump file |
-
-### ABACUS Formats
-
-| Format Name                                              | Description           |
-| -------------------------------------------------------- | --------------------- |
-| `stru` / `abacus/stru`                                   | ABACUS structure file |
-| `abacus/lcao/scf` / `abacus/pw/scf` / `abacus/scf`       | ABACUS SCF output     |
-| `abacus/lcao/md` / `abacus/pw/md` / `abacus/md`          | ABACUS MD output      |
-| `abacus/lcao/relax` / `abacus/pw/relax` / `abacus/relax` | ABACUS relax output   |
-
-### Quantum ESPRESSO Formats
-
-| Format Name  | Description      |
-| ------------ | ---------------- |
-| `qe/cp/traj` | QE CP trajectory |
-| `qe/pw/scf`  | QE PWscf output  |
-
-### CP2K Formats
-
-| Format Name        | Description      |
-| ------------------ | ---------------- |
-| `cp2k/output`      | CP2K output      |
-| `cp2k/aimd_output` | CP2K AIMD output |
-
-### Gaussian Formats
-
-| Format Name     | Description                   |
-| --------------- | ----------------------------- |
-| `gaussian/log`  | Gaussian log file             |
-| `gaussian/fchk` | Gaussian formatted checkpoint |
-| `gaussian/md`   | Gaussian MD output            |
-| `gaussian/gjf`  | Gaussian input file           |
-
-### Other Formats
-
-| Format Name                                                         | Description           |
-| ------------------------------------------------------------------- | --------------------- |
-| `xyz`                                                               | XYZ format            |
-| `mace/xyz` / `nequip/xyz` / `gpumd/xyz` / `extxyz` / `quip/gap/xyz` | Extended XYZ variants |
-| `ase/structure`                                                     | ASE structure format  |
-| `ase/traj`                                                          | ASE trajectory        |
-| `pymatgen/structure`                                                | pymatgen structure    |
-| `pymatgen/molecule`                                                 | pymatgen molecule     |
-| `gromacs/gro` / `gro`                                               | GROMACS gro file      |
-| `siesta/output`                                                     | SIESTA output         |
-| `siesta/aimd_output`                                                | SIESTA AIMD output    |
-| `pwmat/output` / `pwmat/mlmd` / `pwmat/movement`                    | PWmat output          |
-| `pwmat/final.config` / `pwmat/atom.config`                          | PWmat config          |
-| `orca/spout`                                                        | ORCA output           |
-| `psi4/out`                                                          | PSI4 output           |
-| `dftbplus`                                                          | DFTB+ output          |
-| `fhi_aims/output` / `fhi_aims/md`                                   | FHI-aims output       |
-| `amber/md`                                                          | AMBER MD              |
-| `n2p2`                                                              | n2p2 format           |
-| `mol_file` / `mol`                                                  | MOL file              |
-| `sdf_file` / `sdf`                                                  | SDF file              |
-| `openmx/md`                                                         | OpenMX MD             |
-| `sqm/out`                                                           | SQM output            |
-| `sqm/in`                                                            | SQM input             |
-| `list`                                                              | List format           |
-| `3dmol`                                                             | 3Dmol visualization   |
-
-### Extended XYZ (extxyz) Format Details
-
-The following format names are **all equivalent** and invoke the same reader/writer:
-
-- `extxyz` — general-purpose extended XYZ
-- `quip/gap/xyz` / `quip/gap/xyz_file` — QUIP/GAP framework datasets
-- `mace/xyz` — MACE model training data
-- `nequip/xyz` — NequIP model training data
-- `gpumd/xyz` — GPUMD simulation data
-
-> **Important:** Plain `xyz` is a **different**, simpler format that stores atom species and coordinates but does not provide per-frame properties such as energies, forces, cell information, or periodic boundary conditions. Do not confuse `xyz` with `extxyz`.
-
-#### CLI Examples for extxyz
-
-```bash
-# Multi-frame extxyz trajectory → deepmd/npy (--multi preserves all frames)
-uvx dpdata data.xyz -i extxyz -O deepmd_data -o deepmd/npy --multi
-
-# Heterogeneous extxyz (mixed compositions) → deepmd/npy/mixed
-uvx dpdata data.xyz -i extxyz -O deepmd_data -o deepmd/npy/mixed --multi
-
-# Convert extxyz to VASP POSCAR (single-frame input only)
-uvx dpdata data.xyz -i extxyz -O POSCAR -o vasp/poscar
-
-# Convert a single-frame extxyz with explicit type map
-uvx dpdata data.xyz -i extxyz -O deepmd_data -o deepmd/npy -t H C N O
-```
-
-#### Tips for extxyz
-
-1. **Use `-i extxyz` explicitly** when working with `.xyz` files that contain extended XYZ data. Using `-i xyz` retains only atom species and coordinates, omitting per-frame properties such as energies, forces, and cell information.
-1. **Use `--multi` for any multi-frame extxyz file.** Without `--multi`, the CLI constructs a `LabeledSystem` that keeps only the first frame. This applies to all multi-frame trajectories, not just heterogeneous (mixed-composition) files. dpdata groups frames by chemical formula internally.
-1. **All alias names behave identically** — `-i mace/xyz`, `-i nequip/xyz`, `-i gpumd/xyz`, `-i quip/gap/xyz`, `-i quip/gap/xyz_file`, and `-i extxyz` produce the same result.
-
-## Tips
-
-1. **Auto-detection**: Use `-i auto` (default) to let dpdata detect format automatically
-1. **Type mapping**: Use `-t` to specify atom type order for deepmd formats
-1. **Multi-system**: Use `--multi` for directories containing multiple systems
-1. **Compressed output**: Use `deepmd/npy` or `deepmd/hdf5` for smaller file sizes
-
-## References
-
-- [dpdata Documentation](https://docs.deepmodeling.com/projects/dpdata/)
-- [CLI Reference](https://docs.deepmodeling.com/projects/dpdata/en/stable/cli.html)
-- [Formats Reference](https://docs.deepmodeling.com/projects/dpdata/en/stable/formats.html)
-- [GitHub Repository](https://github.com/deepmodeling/dpdata)
+For the full command and format table, see
+[`cli-reference.md`](../dpdata-convert/references/cli-reference.md).
diff --git a/skills/dpdata-convert/SKILL.md b/skills/dpdata-convert/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: dpdata-convert
+description: Convert atomistic producer outputs with dpdata while preserving and validating the labeled-data contract. Use for format conversion, dataset preparation, and exports from VASP, CP2K, ABACUS, Quantum ESPRESSO, LAMMPS, or other supported producers.
+compatibility: Requires dpdata and the dependencies of the selected format.
+metadata:
+  repository: https://github.com/deepmodeling/dpdata
+---
+
+# Convert atomistic data
+
+Use this workflow when a user starts with a producer output and wants a
+`dpdata` system, a training dataset, or another file format. The command is
+only one part of the task: the resulting arrays must retain their scientific
+meaning.
+
+## Procedure
+
+1. **Identify the producer contract.** Record the producer and version, input
+   and output paths, parser/`dpdata` version, and whether the source contains
+   energies, forces, and virials/stress. Load the matching reference only when
+   the producer is known:
+   [`CP2K`](references/producers/cp2k.md),
+   [`VASP`](references/producers/vasp.md),
+   [`ABACUS`](references/producers/abacus.md), or
+   [`Quantum ESPRESSO`](references/producers/qe.md).
+1. **Choose the data shape.** Use `LabeledSystem` for data that must carry
+   energies, and `System` for structures without labels. Use `MultiSystems`
+   or `--multi` only when directories contain independent systems. Do not
+   silently turn partial labels into a complete dataset; state which labels
+   are required and what happens when one is absent.
+1. **Convert without discarding the source.** Keep the raw files and write the
+   converted output to a new path. Include an explicit `--from_format` when
+   auto-detection could be ambiguous. Supply `--type-map` when the producer's
+   atom ordering is not self-describing.
+1. **Validate the output.** Check frame alignment, atom ordering, type-map
+   consistency, finite values, cell/PBC assumptions, units, and virial/stress
+   conventions. The reusable checks and their limits are in
+   [`semantic-validation.md`](references/semantic-validation.md); the
+   deterministic validator is part of [`dpdata-inspect`](../dpdata-inspect/SKILL.md).
+1. **Record provenance.** Keep the raw path, producer/version, parser version,
+   command, format, type map, units, and any dropped or missing labels next to
+   the converted data. A successful parser run is not evidence that a dataset
+   is suitable for training.
+
+## Command reference
+
+The CLI uses the same format names as the Python API:
+
+```bash
+uvx dpdata INPUT -i PRODUCER_FORMAT -O OUTPUT -o TARGET_FORMAT
+```
+
+Examples:
+
+```bash
+# A labeled VASP trajectory to DeePMD raw data
+uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw
+
+# A directory containing independent systems
+uvx dpdata data_dir -i vasp/outcar -O output_dir -o deepmd/comp --multi
+
+# Make the atom order explicit when reading a LAMMPS dump
+uvx dpdata dump.lammps -i lammps/dump -O POSCAR -o vasp/poscar -t C H O
+```
+
+For all options and format aliases, load
+[`cli-reference.md`](references/cli-reference.md). The reference is kept
+separate so a conversion request does not require loading every format at
+once.