feat: add DeePMD installation agent skill

Author: OutisLi

README.md

@@ -212,9 +212,27 @@ plugins. Applications can therefore open the backend required by a model
 without directly linking every framework.
 
 > [!NOTE]
-> Working with an AI coding or scientific agent? DeePMD-kit ships
+> Working with an AI coding or scientific agent? Start with
+> [Install with an AI agent][agent-install], or browse the
 > [official Agent Skills][agent-skills] for model selection, training,
 > fine-tuning, Python inference, and LAMMPS workflows.
+>
+> ```bash
+> npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \
+>     --skill deepmd-install -y
+> ```
+>
+> If direct GitHub access fails, use `gh-proxy.com` for a public, read-only
+> clone, then install from the local checkout. Do not send credentials or
+> private repository URLs through the proxy.
+>
+> ```bash
+> git clone --depth 1 \
+>     https://gh-proxy.com/https://github.com/deepmodeling/deepmd-kit.git \
+>     deepmd-kit-skill-source
+> npx -y skills add ./deepmd-kit-skill-source/skills \
+>     --skill deepmd-install -y
+> ```
 
 ## 📚 Documentation and community
 
@@ -251,6 +269,7 @@ that matches the version used and the method-specific papers listed in
 DeePMD-kit is licensed under the
 [GNU Lesser General Public License v3.0 or later](./LICENSE).
 
+[agent-install]: https://docs.deepmodeling.com/projects/deepmd/en/latest/install/install-with-agent.html
 [agent-skills]: https://docs.deepmodeling.com/projects/deepmd/en/latest/agent-skills.html
 [ase]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/ase.html
 [backends]: https://docs.deepmodeling.com/projects/deepmd/en/latest/backend.html

doc/agent-skills.md

@@ -2,7 +2,7 @@
 
 DeePMD-kit provides official [Agent Skills](https://agentskills.io/what-are-skills) that help AI agents run
 DeePMD-kit workflows in a reproducible way. These skills capture
-project-specific operating knowledge—such as training inputs, model
+project-specific operating knowledge—such as installation, training inputs, model
 selection, deployment, LAMMPS integration, and Python inference patterns—so an
 agent can turn a high-level request into concrete files, commands, and
 validation steps.
@@ -14,6 +14,14 @@ in the DeePMD-kit repository under `skills/`.
 
 ## List of skills
 
+- `deepmd-install`: Install DeePMD-kit for users. The skill probes the machine,
+  records the selected environment and build in a validated plan, then follows
+  either an easy path (conda, pip, Docker, offline, `dp1s`) or a source build of
+  the Python package, C/C++ interface, and LAMMPS. Kokkos builds use one
+  `Kokkos_ARCH_*` flag per binary. DPA4/SeZM uses `deepmd/kk`; DPA4C uses
+  `dpa4spin/kk` with a compact canonical graph artifact. Detailed recipes live
+  under `skills/deepmd-install/references/` and are loaded only for the selected
+  path or a matching failure mode.
 - `deepmd-train`: Choose a DeePMD-kit model family, then train from scratch.
   The skill uses progressive disclosure: the top-level workflow handles common
   training steps and model selection, while model-specific configuration lives
@@ -40,6 +48,10 @@ paper:
 
 ## Install skills
 
+To have an agent install DeePMD-kit itself, send
+[Install with an AI agent](install/install-with-agent.md) and ask it to load
+`deepmd-install`.
+
 ### If you are a user
 
 The easiest way is to send this page to your agent and ask it to install the
@@ -51,23 +63,34 @@ If you already have a DeePMD-kit checkout, run this command from the repository
 root:
 
 ```bash
-npx -y skills add ./skills -a openclaw -y
+npx -y skills add ./skills --skill '*' -y
 ```
 
 If you do not have a checkout, the same skills can also be installed directly
 from GitHub:
 
 ```bash
 npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \
-    -a openclaw -y
+    --skill '*' -y
+```
+
+If direct GitHub access fails, use `gh-proxy.com` for a public, read-only clone
+and install from that checkout. Do not send credentials or private repository
+URLs through the proxy.
+
+```bash
+git clone --depth 1 \
+    https://gh-proxy.com/https://github.com/deepmodeling/deepmd-kit.git \
+    deepmd-kit-skill-source
+npx -y skills add ./deepmd-kit-skill-source/skills --skill '*' -y
 ```
 
-The examples above require Node.js/npm so that `npx` is available, and they
-install the skills for OpenClaw. Replace `openclaw` with the target agent name
-when installing for another agent. The GitHub command lets the skill CLI fetch
-the repository for you. For large repositories or slow networks, this can take
-longer than installing from an existing local checkout. Refresh or restart the
-session afterward so the installed skills are reloaded.
+The examples require Node.js/npm so that `npx` is available. The Skills CLI
+installs every official skill for the detected agent. To target one product,
+add its agent name, for example `--agent cursor` or `--agent claude-code`. The
+GitHub command lets the CLI fetch the repository; installing from an existing
+checkout avoids that download. Refresh or restart the session afterward so the
+installed skills are reloaded.
 
 ## Minimal verification
 
@@ -80,3 +103,6 @@ without launching an expensive calculation. For example:
   water dataset and draft a training input, but do not start training.”
 - “Use the `lammps-deepmd` skill to prepare an NVT LAMMPS input file for a
   DeePMD-kit model, and explain each command.”
+- “Use the `deepmd-install` skill to plan a PyTorch CUDA source install, but
+  ask me for the CUDA toolkit path, PyTorch wheel, and install prefix first.
+  Do not start compiling.”

doc/index.rst

@@ -276,8 +276,8 @@ New and noteworthy
       :link-type: doc
       :shadow: sm
 
-      Give AI agents reproducible guidance for training, fine-tuning,
-      inference, and LAMMPS workflows.
+      Give AI agents reproducible guidance for installation, training,
+      fine-tuning, inference, and LAMMPS workflows.
 
 Documentation map
 =================

doc/install/easy-install.md

@@ -2,6 +2,8 @@
 
 There are various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections.
 
+An AI agent can perform the same installation. See [Install with an AI agent](install-with-agent.md).
+
 After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to train models or run LAMMPS in parallel.
 
 > [!NOTE]

doc/install/index.rst

@@ -5,6 +5,7 @@ Installation
    :maxdepth: 1
 
    easy-install
+   install-with-agent
    install-from-source
    install-from-c-library
    install-lammps

doc/install/install-from-source.md

@@ -1,5 +1,8 @@
 # Install from source code
 
+An AI agent can walk through this source build, including the C++ interface
+and LAMMPS with Kokkos. See [Install with an AI agent](install-with-agent.md).
+
 Please follow our [GitHub](https://github.com/deepmodeling/deepmd-kit) webpage to download the source code of a specific version or the [development version](https://github.com/deepmodeling/deepmd-kit/tree/master).
 
 Or get the DeePMD-kit source code by `git clone`

doc/install/install-lammps.md

@@ -1,5 +1,9 @@
 # Install LAMMPS
 
+An AI agent can build LAMMPS with the DeePMD-kit module and Kokkos. DPA4/SeZM
+uses `pair_style deepmd/kk`; DPA4C uses `pair_style dpa4spin/kk`. See
+[Install with an AI agent](install-with-agent.md).
+
 There are two ways to install LAMMPS: the built-in mode and the plugin mode. The built-in mode builds LAMMPS along with the DeePMD-kit and DeePMD-kit will be loaded automatically when running LAMMPS. The plugin mode builds LAMMPS and a plugin separately, so one needs to use `plugin load` command to load the DeePMD-kit's LAMMPS plugin library.
 
 ## Install LAMMPS's DeePMD-kit module (built-in mode)

doc/install/install-with-agent.md

@@ -0,0 +1,63 @@
+# Install with an AI agent
+
+DeePMD-kit ships an official Agent Skill, `deepmd-install`, that walks an AI
+agent through installing the package. The skill covers easy methods (conda,
+pip, Docker, offline installers, `dp1s`) and source builds of the Python
+package, the C++ interface, and LAMMPS with Kokkos (`pair_style deepmd/kk`,
+used by DPA4/SeZM, and `pair_style dpa4spin/kk`, used by DPA4C).
+
+The skill probes the machine, asks only for decisions required by the selected
+installation path, and records concrete paths and versions in a validated
+plan. It does not assume a host path, package mirror, CUDA toolkit, or backend
+version.
+
+The full skill catalog is in [Agent Skills](../agent-skills.md). For a
+manual install, use [Easy install](easy-install.md) or
+[Install from source](install-from-source.md).
+
+## If you are a user
+
+Send this page to your agent and ask it to install the official
+`deepmd-install` skill, then install DeePMD-kit. You do not need to run the
+commands below yourself.
+
+## If you are an agent
+
+Install `deepmd-install` first, then follow its probe, validated plan, and
+gate workflow.
+
+If this machine already has a DeePMD-kit checkout, run from the repository
+root:
+
+```bash
+npx -y skills add ./skills --skill deepmd-install -y
+```
+
+If there is no checkout, install the same skill from GitHub:
+
+```bash
+npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \
+    --skill deepmd-install -y
+```
+
+If direct GitHub access fails, use `gh-proxy.com` for a public, read-only clone
+and install from the local checkout. Do not send credentials or private
+repository URLs through the proxy.
+
+```bash
+git clone --depth 1 \
+    https://gh-proxy.com/https://github.com/deepmodeling/deepmd-kit.git \
+    deepmd-kit-skill-source
+npx -y skills add ./deepmd-kit-skill-source/skills \
+    --skill deepmd-install -y
+```
+
+The examples require Node.js/npm so that `npx` is available. The Skills CLI
+uses the detected agent. To target one product, add `--agent cursor`,
+`--agent claude-code`, or another supported agent name. Refresh or restart the
+session afterward so the skill is reloaded.
+
+Then use the `deepmd-install` skill: probe the machine, ask only for missing
+decisions, validate `install-plan.json`, and execute one gate at a time. A
+CUDA LAMMPS build uses exactly one `Kokkos_ARCH_*` flag per binary and verifies
+the pair styles required by the selected model family.

pyproject.toml

@@ -493,6 +493,8 @@ runtime-evaluated-base-classes = ["torch.nn.Module"]
 "**/*.ipynb" = ["T20"]  # printing in a nb file is expected
 # Example / demo scripts are run directly: top-level imports and prints are fine.
 "examples/**/*.py" = ["T20", "TID253"]
+# Skill helper CLIs print probe and verification reports.
+"skills/**/*.py" = ["T20"]
 
 [tool.pytest.ini_options]
 markers = "run"

skills/deepmd-install/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: deepmd-install
+description: Install or rebuild DeePMD-kit with conda, pip, dp1s, offline packages, Docker, or a source checkout. Use for CPU, NVIDIA CUDA, or ROCm environments; PyTorch, TensorFlow, JAX, or Paddle backends; the C/C++ interface; and DeePMD-enabled LAMMPS, including Kokkos pair styles for DPA4 and DPA4C.
+---
+
+# Install DeePMD-kit
+
+Install the smallest runtime that satisfies the user's goal. Probe first, keep
+all decisions in a validated plan, execute one self-contained gate at a time,
+and verify the requested public interface rather than package presence alone.
+
+## Supported workflows
+
+| Path                                            | Scope                                                                                          |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| conda, pip                                      | Stable Python installs for PyTorch, TensorFlow, JAX, and Paddle; optional packaged host LAMMPS |
+| `dp1s`, offline package, Docker                 | Official release artifacts selected by the user or matching documentation                      |
+| source Python                                   | PyTorch, TensorFlow, JAX, and Paddle with backend-specific dependencies and verification       |
+| source C/C++                                    | Backend-enabled C/C++ libraries installed into a dedicated prefix                              |
+| source LAMMPS host                              | Built-in DeePMD module with exact pair-style verification                                      |
+| source LAMMPS Kokkos CUDA                       | PyTorch graph artifacts: `deepmd/kk` for DPA4/SeZM and `dpa4spin/kk` for DPA4C                 |
+| ROCm source, Windows source, LAMMPS plugin mode | Follow the version-matched documentation in the selected checkout                              |
+
+## Hard rules
+
+1. Resolve the absolute directory containing this `SKILL.md` as `SKILL_ROOT`.
+   Invoke every bundled script through that absolute path.
+1. Run the read-only probe before choosing versions, paths, or accelerators.
+1. Ask only for a missing value that changes the selected path. Do not ask
+   source, compiler, CUDA, or LAMMPS questions for an unrelated easy install.
+1. Record all decisions in `install-plan.json` and validate it before an
+   install, checkout, compile, download, or environment modification.
+1. Use the plan's absolute Python executable. Never substitute a bare
+   `python`, `pip`, or an assumed conda activation.
+1. Make every shell call self-contained. Do not rely on an `export`, `cd`, or
+   `conda activate` from a previous agent tool call.
+1. Render commands with concrete plan values. Stop if a plan placeholder,
+   empty required value, unexpected path, or shell variable not assigned
+   earlier in the same command block remains.
+1. Never run `git reset --hard`, `git clean`, recursively remove an install
+   prefix, or edit shell rc files as part of this workflow. Use a new build
+   directory or versioned install prefix instead.
+1. Use documentation from the selected checkout for version-sensitive source
+   options. Do not apply `latest` documentation blindly to an older ref.
+1. Confirm before piping a remote script to a shell. Use fail-on-HTTP-error
+   downloads and verify a checksum whenever the plan contains one.
+1. Check GPU occupancy and bind the confirmed physical device explicitly
+   before a GPU smoke test.
+1. On failure, stop the current gate and read
+   [`references/failure-modes.md`](references/failure-modes.md). Do not restart
+   the entire install or wipe caches.
+
+## Workflow
+
+### 0. Probe
+
+Run with an available Python 3.10+ interpreter:
+
+```bash
+"<absolute-python>" "<absolute-skill-root>/scripts/probe_env.py" --json
+```
+
+Use the report to identify the OS, libc, Python environments, compilers,
+toolkits, driver, GPU compute capabilities and visibility mask, disk/RAM, and
+existing DeePMD-kit/PyTorch installs. The probe does not select versions.
+
+### 1. Select one path
+
+- Prefer an easy method for a stable release without local source changes,
+  custom C/C++ libraries, or Kokkos device pair styles.
+- Use source Python for a branch/fork, unreleased feature, local toolkit build,
+  or customized OPs.
+- Add source C/C++ only when a C/C++ client, source-built LAMMPS, or i-PI needs
+  it.
+- Add source LAMMPS only after the C/C++ gate passes.
+
+### 2. Create and validate the plan
+
+Read [`references/plan-schema.md`](references/plan-schema.md), write the plan to
+a stable scratch path outside the source/build trees, and validate it:
+
+```bash
+"<absolute-python>" "<absolute-skill-root>/scripts/validate_plan.py" \
+    "<absolute-plan-path>"
+```
+
+Present a concise summary only when the request or probe leaves a meaningful
+choice unresolved. If the user already specified the method, backend, version,
+and target, proceed without asking them to reconfirm their own request.
+
+### 3. Execute the selected references
+
+| Selection                           | Read                                                         |
+| ----------------------------------- | ------------------------------------------------------------ |
+| conda, pip, `dp1s`, offline, Docker | [`references/easy-install.md`](references/easy-install.md)   |
+| source Python                       | [`references/source-python.md`](references/source-python.md) |
+| source C/C++                        | [`references/source-cpp.md`](references/source-cpp.md)       |
+| source LAMMPS                       | [`references/source-lammps.md`](references/source-lammps.md) |
+| failed gate                         | [`references/failure-modes.md`](references/failure-modes.md) |
+
+Read only the references required by the plan. Within each gate, render one
+command block with absolute values so that directory and environment state
+cannot leak across calls.
+
+### 4. Enforce the gates
+
+| Gate        | Required evidence                                                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Plan        | `validate_plan.py` exits zero and prints the normalized plan                                                                      |
+| Environment | The selected package manager and absolute interpreter target the planned environment                                              |
+| Python      | `verify_python.py` passes for the selected backend and accelerator; source builds also match the expected build variant           |
+| C/C++       | Expected libraries and headers exist, dynamic dependencies resolve, and the build cache records the requested accelerator/backend |
+| LAMMPS      | `verify_lammps.py` finds the exact pair styles required by the model family and no unresolved dynamic dependency                  |
+| Smoke       | The selected short example finishes on the explicitly bound device and emits its documented success signal                        |
+
+For PyTorch source builds, install the intended PyTorch before DeePMD-kit and
+use `--no-build-isolation`. Set both `DP_ENABLE_PYTORCH` and
+`DP_ENABLE_TENSORFLOW` explicitly in the same command that invokes pip.
+
+## LAMMPS model contract
+
+| Model/runtime       | Host pair style | Kokkos CUDA pair style                                      | Artifact requirement                                      |
+| ------------------- | --------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
+| conventional models | `deepmd`        | `deepmd/kk` when the model supports device edge/graph input | Compatible frozen model; `/kk` requires edge/graph `.pt2` |
+| DPA4 / SeZM         | `deepmd`        | `deepmd/kk`                                                 | Target-specific graph `.pt2`                              |
+| DPA4C native spin   | `dpa4spin`      | `dpa4spin/kk`                                               | `atom_style spin` and compact canonical graph `.pt2`      |
+
+Do not accept `deepmd/kk` as proof that DPA4C is available. Do not substitute
+LAMMPS `PKG_GPU` for Kokkos.
+
+## Completion report
+
+Report:
+
+- plan path and resolved source commit, when applicable;
+- environment activation or absolute Python path;
+- installed DeePMD-kit/backend versions and accelerator visibility;
+- C/C++ prefix and LAMMPS binary, when applicable;
+- each gate command and observed result;
+- any validation gate that was not run and the concrete reason;
+- no claim of success beyond the gates that actually passed.