feat: add DeePMD installation agent skill (#5974)

## Summary

- add the `deepmd-install` Agent Skill with concise routes for pip,
conda, dp1s, offline packages, Docker, source builds, C/C++, and LAMMPS
- fetch version-matched official documentation before rendering
version-sensitive commands, using exact-ref raw Markdown from GitHub or
the official Gitee mirror
- treat dynamic command values as literal process arguments rather than
shell source
- pin pip and Conda installations to the selected release and fail
verification on a normalized version mismatch
- make source runtime and compiled-backend selection explicit, including
the documented backend-neutral C/C++ route
- keep a compact failure-mode reference for environment identity,
backend and accelerator selection, source builds, native loader checks,
Docker, and LAMMPS
- document skill installation in the README and installation docs, using
the official Gitee mirror as the network fallback

## Design

The skill provides route selection, safety boundaries, and verification
criteria without duplicating the installation manual. It assumes no
local source checkout. The agent opens the direct official page first,
resolves a release to its tag, and falls back to the corresponding
Markdown at that exact tag or commit when versioned web documentation is
unavailable.

Source installation remains the recommended path when a compiler is
available and build time is acceptable. TensorFlow, PyTorch, JAX,
Paddle, and backend-neutral C/C++ libraries are represented, while
version-specific package, accelerator, and build commands remain owned
by the official documentation.

## Validation

- official `quick_validate.py skills/deepmd-install`
- repository pre-commit hooks for all changed files
- shell-free argv round-trip with spaces, command-substitution syntax,
backticks, semicolons, and option-looking values
- PEP 440 release normalization and exact pip requirement parsing
- Conda exact-version MatchSpec parsing, including rejection of the
fuzzy single-equals form
- direct GitHub and official Gitee raw-documentation fetch at an exact
upstream commit
- official Gitee and upstream `master` commit identity check
- source build environment-assignment shell check
- local Git checkout checks for both a normal ref and an option-looking
ref
- `git diff --check`

Author: OutisLi

README.md

@@ -230,9 +230,26 @@ 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, clone the official Gitee mirror and install
+> from the local checkout:
+>
+> ```bash
+> git clone --depth 1 \
+>     https://gitee.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
 
@@ -269,6 +286,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,11 @@ in the DeePMD-kit repository under `skills/`.
 
 ## List of skills
 
+- `deepmd-install`: Select a pip, conda, `dp1s`, offline, Docker, or source
+  installation path, load the official documentation matching the requested
+  version, and verify the requested Python, C/C++, or LAMMPS interface. A
+  compact failure-mode reference covers issues not resolved by the install
+  pages.
 - `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 +45,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 +60,33 @@ 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, clone the official Gitee mirror and install from
+that checkout:
+
+```bash
+git clone --depth 1 \
+    https://gitee.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 +99,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 install the current stable release with
+  PyTorch and CUDA. Read the matching official documentation before choosing
+  packages, then verify a tensor operation on the GPU.”

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,62 @@
+# 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.
+
+The skill inspects the target machine, asks only for decisions required by the
+selected installation path, reads the official documentation matching the
+requested version, and verifies the requested interface. Version-specific
+package and build commands remain in the installation documentation instead
+of being duplicated in the skill.
+
+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 load it and install DeePMD-kit with the
+required backend, accelerator, and optional native interfaces.
+
+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, clone the official Gitee mirror and install from
+the local checkout:
+
+```bash
+git clone --depth 1 \
+    https://gitee.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. The agent selects one installation method,
+loads the version-matched official documentation, executes its commands in the
+chosen environment, and verifies the requested Python, C/C++, or LAMMPS
+interface.