version: "1.0.0" name: gpumdkit-skill description: Use GPUMDkit, GPUMD, and NEP end to end. Use when installing or exploring GPUMDkit; converting, sampling, splitting, filtering, analyzing, calculating, or plotting atomistic datasets; preparing batch or active-learning workflows; creating model.xyz, run.in, or nep.in; setting up, running, validating, or post-processing GPUMD simulations; training, fine-tuning, or evaluating NEP models; performing diffusion, ionic-conductivity, Arrhenius, thermal-transport, or related workflows; or maintaining GPUMDkit code, documentation, and skills.

GPUMDkit

Use this skill as the single entry point for GPUMDkit utilities, GPUMD simulations, NEP training and evaluation, validation, and post-processing. Load only the references required by the current task.

Mandatory rules

• Read the relevant reference file before giving commands, editing inputs, running tools, or interpreting results. Do not rely on memory when a local reference or help command is available.
• Ask the user whenever an unresolved choice can affect scientific meaning, numerical stability, data selection, units, cost, files, or interpretation. Never invent a plausible parameter.
• Do not choose potentials, species/type mappings, charges, temperatures, time steps, ensembles, pressures, constraints, run lengths, sampling intervals, fit windows, cutoffs, seeds, or convergence criteria without user input or an explicitly identified existing project setting.
• Distinguish documented defaults, project conventions, recommendations, and user decisions. Do not silently turn a default into a production choice.
• Do not overwrite inputs, discard structures, launch GPUMD/NEP/DFT, submit scheduler jobs, or start long/expensive calculations unless the user explicitly authorizes that action.
• Before generating or translating a GPUMD run.in, identify the GPUMD version. For GPUMD 5.7 and later, use dump_xyz for the output roles formerly handled by the removed dump keywords; keep dump_position, dump_velocity, dump_force, and dump_exyz only as explicitly labeled pre-5.7 migration syntax in references/gpumd-outputs.md.
• Stop on parser errors, NaN/Inf values, missing outputs, unstable behavior, or unexplained warnings. Report the evidence and ask before changing scientific parameters or retrying.
• Preserve original data and unrelated worktree changes. Record transformations, filters, exclusions, commands, versions, and assumptions.
• Run smoke tests in isolated temporary directories and remove every temporary file, directory, cache, and generated test output before handoff. Resolve and delete only paths created by the current work; never use a broad cleanup target that could remove user data.

Reference router

Read one or more references according to the task. Do not load every file by default.

For cross-module work, load every relevant reference. Examples:

• Arrhenius study: read gpumd.md, gpumd-inputs.md, gpumd-ensembles.md, gpumd-computes.md, gpumd-outputs.md, arrhenius.md, calculators.md, and visualization.md; also read format-conversion.md if preparing model.xyz.
• NEP training pipeline: read nep.md, nep-data.md, nep-parameters.md, nep-outputs.md, format-conversion.md, analyzers.md, sampling.md, and visualization.md.
• MD/FPS active-learning iteration: read gpumd.md, the GPUMD parameter references used by the protocol, workflows.md, sampling.md, analyzers.md, format-conversion.md, nep.md, nep-data.md, nep-outputs.md, and visualization.md; also read nep-parameters.md when preparing or changing the training configuration.
• New GPUMDkit command: read contributing.md plus the reference for the affected module.
• New or restyled plot: read visualization.md, plotting-style.md, and contributing.md; also read the scientific reference for the quantity being plotted.

Source priority

Use evidence in this order:

1. The self-contained GPUMD and NEP references bundled with this skill.
2. Local executable help, parser messages, and version output.
3. GPUMDkit gpumdkit.sh -h, module help, and target Python script -h output.
4. Existing project inputs confirmed to work with the same executable version.
5. Version-specific documentation supplied by the user when local behavior differs from this bundled snapshot.

If sources disagree, show the exact conflict, executable version, and parser evidence, then ask which software version governs the task. Do not guess version-specific syntax. Treat old standalone GPUMD/NEP skills as non-authoritative.

Operating workflow

1. Classify the request and load the smallest sufficient set of references.
2. Inspect available files, executable versions, local help, and existing project conventions.
3. List missing decisions as concise questions. Continue safe read-only inspection, but do not fill scientific gaps yourself.
4. Present the resolved file plan, commands, expected outputs, and validation criteria before expensive execution.
5. Prefer gpumdkit.sh CLI commands when documented. Use direct scripts under ${GPUMDkit_path}/Scripts/ only when the reference identifies a menu-only/debug path or no CLI route exists.
6. When execution is authorized, capture the exact command, working directory, version, exit status, and warnings. Use a user-approved smoke test first when appropriate.
7. Validate file structure and physical behavior before downstream analysis. Separate equilibration from production and report exclusions.
8. Deliver results with units, provenance, convergence/fit evidence, uncertainty, and limitations.

Portability

• Resolve all links relative to this skill directory. The skill does not require a product-specific activation tool.
• Use standard Markdown, YAML frontmatter, shell commands, and repository-relative resources so any Agent Skills-compatible client can load it.
• Treat agents/openai.yaml as optional interface metadata; never depend on it for instructions or behavior.
• Use ${GPUMDkit_path} for repository resources when available. If it is unset, locate the repository with the user or from the current workspace instead of guessing a path.