AMS Skills for AI Agents

AMS skills provide AI coding assistants and agents like Codex and Claude Code with instructions and reference material for working with AMS.

To use the skills you need AMS2026.103 or later. The skills may change and be tweaked without warning between minor versions.

Starting with AMS2026.106 the skill files are available in $AMSHOME/skills.

Directory tree

skills/
|-- ams2026/
|   |-- agents/
|   |   `-- openai.yaml
|   |-- references/
|   |   |-- engines-and-tasks.md
|   |   |-- installation-license.md
|   |   |-- local-docs-map.md
|   |   |-- scripts-and-reporting.md
|   |   `-- workflow.md
|   `-- SKILL.md
`-- README.md

Files

ams2026/agents/openai.yaml

interface:
  display_name: "Amsterdam Modeling Suite 2026"
  short_description: "Plan and run AMS chemistry workflows"
  default_prompt: "Use $ams2026 to set up and analyze an AMS calculation from my local installation."

policy:
  allow_implicit_invocation: true

ams2026/references/engines-and-tasks.md

# Engines And Tasks

## Tasks

Use these AMS tasks:

- `SinglePoint`
- `GeometryOptimization`
- `PESScan`
- `TransitionStateSearch`
- `MolecularDynamics`
- `NEB`
- `ConformersJob` from `scm.conformers`

If the user asks for a different AMS task, inspect local docs and examples first
instead of guessing.

#### GeometryOptimization and TransitionStateSearch

- `get_main_system()`,
- `get_history_length()`,
- `get_history_property()`,
- PESPointCharacter and NormalModes are expensive; only calculate if required or
  requested, especially for DFT calculations.
  - `readrkf("AMSResults", "PESPointCharacter", file="engine")` # robust
    verification of minimum or TS not sensitive to numerical noise if
    PESPointCharacter or NormalModes requested

#### PESScan, NEB, IRC, PESExploration, Replay

- PESScans, NEB, IRC, and PESExploration are expensive. Use convergence quality
  Normal or Basic unless the user explicitly asks for more accurate settings.
- PESScan: ALWAYS set CalcPropertiesAtPESPoints Yes in the input settings
- PESScan: `get_pesscan_results()` # dictionary with results and PLAMS Molecules
  (not ChemicalSystem)
- NEB: `get_neb_results()` # dictionary with results and PLAMS Molecules (not
  ChemicalSystem)
- IRC: `get_irc_results()` # dictionary with results and PLAMS Molecules (not
  ChemicalSystem)
- PESExploration: `get_energy_landscape()`
- Replay: ALWAYS set Properties Gradients Yes and any other needed properties;
  ALWAYS set StoreAllResultFiles Yes

#### MolecularDynamics

- PLAMS special job types for MD: `AMSNVEJob`, `AMSNVTJob`, `AMSNPTJob`,
- More advanced MD jobs use normal `AMSJob`.
- PLAMS special job types for post-processing: `AMSRDFJob`, `AMSMSDJob`
- `get_history_length()`
- `get_history_property(..., history_section="MDHistory")`

## Engine selection

- Prefer a documented example that already combines the desired engine and task.
- Cheap exploratory engines: `DFTB`, `MLPotential`, `ForceField`.
- More accurate but more expensive engines: `ADF`, `BAND`, `QuantumESPRESSO`.
- Rule of thumb: avoid `ADF` or `BAND` or `QuantumESPRESSO` for systems much
  larger than about 100 atoms unless the user explicitly accepts the cost.

## Relative energies

- Absolute energies from different engines are not directly comparable.
- For reaction energies, conformer ranking, adsorption energies, and similar
  comparisons, keep the important engine settings identical across compared
  jobs.
- Usual exceptions where some settings may differ because they depend on the
  system:
  - k-point sampling for periodic systems,
  - spin polarization in `ADF`,
  - occupation-derived data reused for excitation workflows.

## Important guardrails

- Input validity depends on combinations of settings, not just individual
  keywords.
- Prefer common, example-backed keywords over obscure options.
- Use builtin `Dispersion` for `ADF`, `BAND`, `DFTB`, and Quantum ESPRESSO. Do
  not use `EngineAddon` dispersion there.
- `EngineAddon` dispersion is only for `MLPotential`. `EngineAddon D4Dispersion`
  can be used with Quantum ESPRESSO.

## Parallelism defaults

- `ADF`, `BAND`, `DFTB`, `ReaxFF`, `QuantumEspresso`, and `ConformersJob`: use
  defaults.
- `MLPotential`: set `s.runscript.nproc = 1` and preamble lines for
  `OMP_NUM_THREADS=1`.

## ML model availability

Before choosing an ML potential model, verify that it is installed:

- List installed models: `$AMSBIN/amspython $AMSHOME/Utils/check_ml_backends.py`

If a required model is not installed, stop early and ask the user before
suggesting package installation (`$AMSBIN/amspackages list`) or downloads.

ams2026/references/installation-license.md

# Installation

Consult this section only in case of installation problems, for example if AMS
cannot launch, if it fails with a LICENSE INVALID error, or if a required AMS
package is not installed.

`$AMSHOME` should be set to the AMS installation directory.

- Table of contents: `$AMSHOME/Doc/text/Installation/index.txt`

## Platform-specific quickstart

- Windows: `$AMSHOME/Doc/text/Installation/Windows_Quickstart_Guide.txt`
- Linux: `$AMSHOME/Doc/text/Installation/Linux_Quickstart_Guide.txt`
- Mac: `$AMSHOME/Doc/text/Installation/MacOS_Quickstart_Guide.txt`

## General installation

- `$AMSHOME/Doc/text/Installation/Installation.txt`
- `$AMSHOME/Doc/text/Scripting/GettingStarted.txt`

## Package manager

`amspackages` can be used to install optional components like some machine
learning potentials and Quantum ESPRESSO.

- `$AMSHOME/Doc/text/Installation/Optional_Components.txt`
- `$AMSHOME/Doc/text/Installation/Appendix_D_Advanced_Package_Manager_Usage.txt`
- `$AMSBIN/amspackages list`

For ML Potentials:

- `$AMSBIN/amspython $AMSHOME/Utils/check_ml_backends.py`

## License

AMS licenses are either node-bound, floating, or cloud licenses.

- Common: `$SCMLICENSE` is the path to a `license.txt` file with license
  information.
- Cloud license (rare): `$SCMLICENSE` should not be set, `$SCM_CLOUD_CREDS`
  should be set to `<username>:<password>`.

Useful commands:

- Check license on current machine: `$AMSBIN/dirac check`

More information:

- `$AMSHOME/Doc/text/Installation/Installation.txt`

## Troubleshooting

When troubleshooting installation or license issues, always be explicit with the
user about the current values of `$AMSHOME`, `$AMSBIN`, `$AMSRESOURCES`,
`$SCMLICENSE`, `$SCM_CLOUD_CREDS` and the output of `$AMSBIN/dirac check`

In case of `amspackages`, also the value of `$SCM_PYTHONDIR`,
`$SCM_AMSPKGS_ADMIN`.

ams2026/references/local-docs-map.md

# Local Docs Map

Use the local AMS installation as the authoritative reference.

## First places to inspect

- AMS doc root: `$AMSHOME/Doc/text/`
- Documentation index: `$AMSHOME/Doc/text/Documentation/index.txt`
- Python examples: `$AMSHOME/Doc/text/PythonExamples/`
- PLAMS (Settings, AMSJob, AMSResults):
  - `$AMSHOME/Doc/text/plams/interfaces/amssuite.txt`
  - `$AMSHOME/Doc/text/plams/interfaces/ams.txt`
- ChemicalSystem:
  - `$AMSHOME/Doc/text/Scripting/ChemicalSystem/API.txt`
  - Always prefer builtin ChemicalSystem methods over hand-rolling geometry/bond manipulation, analysis, file formats.
- AMS driver docs: `$AMSHOME/Doc/text/AMS/`
- Engine docs: `$AMSHOME/Doc/text/<engine-name>/`
- Generated input definitions: `$AMSBIN/input_def/`
- Units API (REQUIRED) `scm.base.Units`:
  `$AMSHOME/Doc/text/Scripting/LibBase/Units.txt`.

## Useful example starting points

- Water optimization example:
  `$AMSHOME/Doc/text/PythonExamples/water-optimization/water_optimization.py`.
- ChemicalSystem versus PLAMS Molecule comparison:
  `$AMSHOME/Doc/text/PythonExamples/chemicalsystem-plams-molecule-comparison.txt`
- Visualization:
  `$AMSHOME/Doc/text/PythonExamples/visualization/visualization.py`.

## What to inspect for specific questions

- Valid input keywords: local engine and AMS Driver docs and input definitions.
- Supported task and engine combinations: Python examples first, docs second.
- ML potential applicability:
  `$AMSHOME/Doc/text/MLPotential/ModelsAndBackends.txt`.
- Whenever AMS reports a license invalid error:
  - Run `$AMSBIN/dirac check`
  - Read `$AMSHOME/Doc/text/Installation/Installation.txt`

When searching the local docs, exclude `*.ams` files and `$AMSHOME/Doc/text/PythonExamples/*/index.txt`.

Always find one or more close examples and adapt them rather than scanning large
keyword references end to end.

ams2026/references/scripts-and-reporting.md

# Scripts And Reporting

## Run scripts

- Execute AMS Python with `$AMSBIN/amspython`.
- Start each generated script with:
  - shebang `#!/usr/bin/env amspython` when creating a standalone executable
    script,
  - `from __future__ import annotations`,
  - type hints.
- Prefer `scm.base.ChemicalSystem` for systems.
- For scripts that run jobs, call
  `scm.plams.init(folder="<script-name>_workdir")`.
- NEVER set the `path` argument of `scm.plams.init()`.
- NEVER use Python booleans with `scm.plams.Settings`; Use the strings "Yes" and
  "No".

### Settings validation

Validate the input with `scm.base.InputParser`. The parser raises an input error
for unknown blocks, keys, or invalid values. This catches errors before
launching AMS. Do it as a quick sanity check on your input settings, if needed.
Do not include this validation in the final script.

```python
from scm.base import InputParser
from scm.plams import AMSJob, Settings

settings = Settings()
settings.input.ams.Task = "GeometryOptimization"
settings.input.dftb.Model = "GFN1-xTB"

input_text = AMSJob(settings=settings).get_input()
InputParser().to_dict("ams", input_text)
```

Use the input-definition name that matches the program which consumes the
serialized text:

- `AMSJob`: `"ams"`
- `ConformersJob`: `"conformers"`
- `SimpleActiveLearningJob`: `"simple_active_learning"`

For ParAMS, use the validation built into `ParAMSJob.get_input()`.

AMS and the other programs may still reject scientifically or operationally
incompatible combinations later.

# Report

## Reporting requirements

- Always produce a reporting script, typically `report.py`.
- Always use files from the latest workdir (`workdir`, `workdir.002`,
  `workdir.003` etc.) - plams may create multiple of those.
- `report.py` must load cited jobs with the matching `load_external(...)` API,
  typically `AMSJob.load_external(...)` or `ConformersJob.load_external(...)`.
- Do not add an intermediate file or analysis layer between the AMS job
  directories and `report.py`.
- Store a brief justification next to each loaded job so later readers know why
  it exists.
- Extract raw numbers programmatically from AMS results before writing the
  markdown report.
- Compute any derived values inside `report.py` from the loaded jobs.
- Include the calculation input for cited jobs via `job.get_input()` surrounded
  by markdown triple backticks with the `ams` language.
- Keep the report focused on calculations that support the conclusions.

### Units and conversions

- Do NOT hard-code conversion factors.
- Do NOT use `scm.plams.Units.convert(...)`.
- Use `scm.base.Units.conversion_factor(...)`.

### Tables

- Create a subdirectory `tables/` to store any tables in .csv format.
- Use pandas for meaningful tables or sortable comparisons.
- Render data frames to markdown with `df.to_markdown()`. Assume it is
  available.

### Figures and visualization

- Create a subdirectory `figures/`
- Use object-oriented matplotlib for graphs: `fig, ax = plt.subplots(...)`
- Always call
  `scm.plams.view(system, guess_bonds=len(system.bonds)==0, ..., picture_path="picture.png")`
  to include pictures of relevant representative structures (at least one)
- Never set the `backend` argument to `scm.plams.view(..., backend=...)`, always
  rely on the default.
- Molecules: `scm.plams.view(system, direction="along_pca3", ...)`
- Crystals and surfaces: `scm.plams.view(system, direction="tilt_x", ...)`
- Multiple structures in a single image: `scm.plams.plot_image_grid`

### Rendered report behavior

- Write the rendered report to `report.md`.
- Include a short title, introduction, and conclusion.
- Make the report self-contained and understandable by other people. Do NOT
  reference the prompt with phrases like "as requested".
- Use dry, specific, professional language.
- Make result provenance unambiguous.

ams2026/references/workflow.md

# Workflow

## Default execution loop

1. Restate the chemistry goal in operational terms: system, property,
   comparison, or workflow output.
2. Inspect local AMS examples before choosing settings.
3. Pick the simplest valid workflow that answers the question.
4. Validate settings before execution.
5. Run AMS outside the sandbox and monitor progress.
6. If another calculation depends on earlier results, load the earlier job
   directly from disk and extract only the needed values in that next script.
7. Update `report.py` so it reads cited jobs directly from disk with
   `AMSJob.load_external(...)`, then render `report.md`.

## Building workflows

- For trivial one-off jobs, one script can build, run, and analyze.
- For expensive or iterative work, split into logical stages:
  - setup or calculations,
  - follow-on calculations,
  - reporting.
- Use two-digit numeric prefixes so execution order is obvious.
- Match the PLAMS workdir to the script name, for example
  `01-geometry-opt_workdir`.

## Reusing prior results

- Load completed jobs with `AMSJob.load_external("/path/to/job")`.
- Load completed conformer workflows with
  `ConformersJob.load_external("/path/to/job")`.
- Use loaded results as provenance-bearing inputs for later scripts.
- Prefer extracting just the needed structure or scalar results instead of
  copying large outputs.

## Reporting boundary

- Do not create an intermediate results file, cache, or postprocessed data layer
  between AMS job directories and `report.py`.
- `report.py` must read directly from the individual job files and directories
  via `AMSJob.load_external(...)`.
- If derived values are needed, compute them inside `report.py` from the loaded
  jobs before writing `report.md`.

## Monitoring

- Do not start another local AMS run while one is active.
- If a job shows no progress for an extended period, ask the user whether to
  keep waiting or stop it.
- For supported tasks such as `GeometryOptimization`, `NEB`,
  `MolecularDynamics`, and `TransitionStateSearch`, AMS can be asked to stop
  cleanly between structure updates by writing `Stop` to `interactive.in` next
  to `ams.rkf`.
- Treat long or expensive jobs as checkpoints: keep reporting current status
  rather than waiting silently.

ams2026/SKILL.md

---
name: ams2026
description: Use when a task involves setting up, running, monitoring, or analyzing Amsterdam Modeling Suite (AMS) calculations or PLAMS workflows. Guides the agent to use only AMS tools, inspect the user's local AMS documentation and Python examples, ask conservative clarification questions for ambiguous chemistry or costly settings, generate `amspython` run scripts and `report.py` reports, and require escalated execution outside the sandbox for AMS jobs.
---

# Amsterdam Modeling Suite

Use this skill for AMS and PLAMS work only. Do not solve chemistry tasks with ORCA, Gaussian, LAMMPS, ASE workflows, or other external engines unless the user explicitly changes the requirement.

## Core rules

- Require `$AMSHOME`, `$AMSBIN`, `$AMSRESOURCES`, and either `$SCMLICENSE` or `$SCM_CLOUD_CREDS` (secret) to be set before continuing. Otherwise, ask for the AMS installation directory and offer to source its `amsbashrc.sh` or `ams_command_line.bat` to set the environment.
- AMS execution must happen outside the sandbox. Before running AMS commands, request escalation and state that AMS needs elevated permissions.
- Never run multiple AMS calculations simultaneously on the local machine.
- Always use the user's local AMS installation as the source of truth. Inspect `$AMSHOME/Doc/text/` and the generated definitions in `$AMSBIN/input_def`. Do not invent settings.
- Be conservative. Ask the user when system definition, charge, spin, engine choice, task choice, or expensive settings are unclear.
- Always reuse existing AMS PythonExamples as starting points instead of inventing large settings blocks from scratch.

## Workflow

1. Clarify the scientific goal, required outputs, and whether the user wants a quick estimate or a more reliable calculation.
2. Inspect local AMS examples and docs that match the target workflow. Start with the paths in `references/local-docs-map.md`.
3. Choose a compatible system, engine, and AMS task. Use `references/engines-and-tasks.md` for scope and guardrails.
4. Generate Python scripts that follow `references/scripts-and-reporting.md`.
5. Validate PLAMS `Settings` before execution. Serialize AMS, Conformers, and Simple Active Learning settings with the matching job class and parse the text with `scm.base.InputParser`; use `ParAMSJob.get_input()` for ParAMS' built-in validation.
6. Run AMS with `$AMSBIN/amspython` outside the sandbox, monitor progress, and stop to ask the user if a job appears stalled. `$AMSBIN/amspython` is a shell script; on Windows it can be executed with the `sh` interpreter on PATH provided by `ams_command_line.bat`.
7. Generate or update `report.py`, and have it read directly from individual job directories with the matching `load_external(...)` API before rendering `report.md`. Always execute `report.py` outside the sandbox.

## Script conventions

- Always execute AMS Python scripts with `$AMSBIN/amspython`.
- Add `from __future__ import annotations` at the top of generated scripts.
- Use type hints.
- Prefer `scm.base.ChemicalSystem` over `scm.plams.Molecule`.
- For scripts that run jobs, call `scm.plams.init(folder="<script-name>_workdir")`.
- Use two-digit filename prefixes for multi-step workflows such as `01-setup.py`, `02-report.py`.
- When loading prior finished jobs, use `AMSJob.load_external(...)` or `ConformersJob.load_external(...)` as appropriate.

Read `references/scripts-and-reporting.md` before writing any AMS script or report.

## Scope

Support these workflows:

- `SinglePoint`
- `GeometryOptimization`
- `PESScan`
- `TransitionStateSearch`
- `MolecularDynamics`
- `scm.conformers.ConformersJob`

## When to read references

- Read `references/workflow.md` for orchestration, job sequencing, monitoring, and reuse of previous results.
- Read `references/engines-and-tasks.md` when selecting engines, matching supported tasks, handling relative energies, or checking ML model availability.
- Read `references/scripts-and-reporting.md` when writing any run script or report.
- Read `references/local-docs-map.md` to find the right local AMS docs or examples quickly.
- Read `references/installation-license.md` to troubleshoot installation issues or license issues.

README.md

# Amsterdam Modeling Suite skills for coding agents

This repository contains an `ams2026` skill for writing Python code to run and analyze
AMS calculations with coding agents like Codex and Claude.

## Caveats

- **AMS cannot run in the Codex sandbox**. It will fail either with license errors or
  obscure MPI errors. Elevated permissions are required. Make sure that you understand
  the security implications. Read the code that Codex writes before executing.

- Only the AMS Driver and Engines are currently covered. Excluded from this skill:
  COSMO-RS, Bumblebee, Zacros.

- The skill is not "stable" but may be updated to fix issues or change behavior. Feel
  free to manually modify the skill and use your own version that is more tailor-made
  for your own workflows and application areas.

## Installation

**Requirements**:

- An AMS installation on the machine running the coding agent, with the environment
  variables `$AMSHOME`, `$AMSBIN`, and `$SCMLICENSE` set before the coding agent is
  launched.

- Text version of the AMS documentation in `$AMSHOME/Doc/text/`. (Only available in
  AMS2026.103+)

**How to install**:

- Copy or symlink `$AMSHOME/skills/ams2026` to `$HOME/.agents/skills/ams2026`
  or `$HOME/.claude/skills/ams2026`. This makes it available in every Codex or
  Claude session. Invoke it by typing `$ams2026` in Codex or `/ams2026` in
  Claude.

## Usage

- **Use /plan mode!** Plan your work. Ask for specifics about levels of theory and
  methods to construct the initial structure. Guide the agent as much as possible.

- If you are unsure about something, **ask** what your options are and a recommendation.

- Be as explicit as possible about your request (levels of theory, methods, structures),
  and any necessary data or figures to go into the report.

- Preferably invoke the skill explicitly:

```
$ams2026 I want to calculate the dihedral torsion profile of biphenyl with DFTB. 
What do you recommend?
```

- One-shot examples can be found in
  `$AMSHOME/Doc/text/PythonExamples/*/instructions.md`.