Agent-TIS: agent skills for using PyRETIS

Agent-TIS is the guidance that PyRETIS provides to AI agents, so that an agent uses the library correctly as a tool. The agent is the one the user chooses and runs: a coding agent such as Claude Code, or any large language model (LLM) agent that reads local files and runs commands. Agent-TIS consists of:

  • two agent skills, structured folders of Markdown files that the agent loads for a task:

    • skills/pyretis-pathsampling/, the user skill: set up, run and analyse path-sampling simulations (TIS, RETIS, REPPTIS, permeability, infinite swapping);

    • skills/pyretis-development/, the developer skill: change, test and validate the PyRETIS code;

  • llms.txt, a machine-readable index of this documentation.

The skills carry the PyRETIS-specific procedural knowledge: method selection, move choice, interface placement, engine validation, the test gates, and the primary literature behind each choice. The researcher keeps the scientific decisions: the question, the order parameter, the states, and the judgement of convergence and uncertainty. The skills are in the folder skills/ of the repository.

How a skill is structured

A skill is a folder of Markdown files with three levels:

  • SKILL.md opens with a YAML frontmatter that holds the name of the skill and a description of the tasks it serves. Its body holds the rules the agent always follows, an overview, the workflow, and a table of the topic files with the moment to read each one.

  • The topic files next to SKILL.md each cover one part of the work: choosing the method, placing the interfaces, running the test gates, re-generating engine references, citing the literature.

  • The sub-directories hold material for specific cases: the notes on specific systems (examples/ of the user skill) and the role prompts for sub-agents (roles/ of the developer skill).

How an agent uses a skill

An agent works through a skill in three steps:

  1. It loads SKILL.md when the description matches the task, and keeps its rules for the whole task.

  2. It reads a topic file when the work reaches the step that the table of SKILL.md names for it.

  3. For work that needs a clean context, such as writing the tests of new code or reviewing a change, it launches a sub-agent and gives it a role file of roles/ as its prompt, with the inputs or the files that the role file names.

The agent thus holds the rules from the start and reads each procedure when the work needs it.

The user skill: run and analyse simulations

skills/pyretis-pathsampling/ guides the configuration, execution and interpretation of path-sampling calculations. Its SKILL.md holds:

  • the rules: the scientist decides the question, the order parameter and the states A and B; a convergence claim comes with its evidence (the rate with its statistical error, the crossing probability of each interface, the input file, the commands, and the PyRETIS and engine versions); runs work on a copy of the input; pyretis analyse reads the input file that was run; keywords come from the skill or the documentation; each method choice comes with its reason and its reference;

  • a minimal recipe for a small or locally hosted model: a decision table for the method, a base input per engine, the keys to change, and the exact commands to run and analyse;

  • the workflow for a capable model: the sampling task (TIS, RETIS, REPPTIS, permeability), the MD engine (internal or TurtleMD, GROMACS, LAMMPS, CP2K, OpenMM), the order parameter and the interface ladder, the sampling controls, the initial paths, the run with pyretis run, and the analysis of crossing probabilities and rates with pyretis analyse;

  • the calls most often got wrong, each with the topic file that gives its reason and reference.

Table 58 Topic files of the user skill

File

Read when

methods.md

choosing the task, the moves and their controls, high acceptance, priority shooting, infinite swapping or permeability

order-parameters.md

defining the order parameter, the states A and B, or extra collective variables

interfaces.md

placing or re-spacing the interfaces, by hand or with pyretis tools init

engines.md

configuring an MD engine

running.md

getting initial paths, running, monitoring, restarting, using several workers

analysis.md

reading the report, WHAM, the REPPTIS MSM, skipping cycles

diagnosis.md

a result looks wrong or a run stops, e.g. a local crossing probability of zero

checking.md

deciding whether to trust a setup, a rate or a speed-up: a known case with an analytical rate, invariance checks, efficiency

references.md

citing the method behind a choice

examples/

the user works on a specific system: one file of notes per system, with its order parameter, states, interface ladder, engine settings and pitfalls

The calls most often got wrong, in the skill’s list:

  • RETIS includes the initial-flux contribution and is the standard choice; plain TIS serves a single ensemble or a custom flux treatment.

  • The order parameter determines the quality of the result, and the interface placement (a crossing probability of about 0.2–0.5 per interface) is the main lever on convergence.

  • Sub-trajectory moves (Wire Fencing, Stone Skipping and Web Throwing) serve barriers where shooting stalls, at an additional computational cost.

  • High acceptance is the default and stays on.

  • REPPTIS serves long-lived intermediates and very slow permeation.

  • Infinite swapping, with several workers, serves large parallel calculations and is analysed with WHAM.

  • With one worker, the same input repeats its paths on the Langevin and VelocityVerlet integrators and on TurtleMD, and on an external engine as far as the MD program repeats its numbers. With several workers, the kicked first paths repeat, the run follows the order in which the workers finish, and runs are compared by their rates, within the error.

Example requests

Set up a RETIS simulation for the 1-D double well, run it, and report
the rate with its statistical error and the crossing-probability curve.

I have a GROMACS system for ligand unbinding. Help me pick an order
parameter and interface ladder, write the retis.toml, and launch RETIS.

My intermediate state is metastable and the permeation is very slow —
is REPPTIS the right method here, and what do I lose vs RETIS?

Analyse this finished run and tell me whether the crossing probabilities
overlap well or whether I need more steps or better-placed interfaces.

Ensemble [3^+] reports a crossing probability of zero. Why, and what
should I change?

The developer skill: change, test and validate the code

skills/pyretis-development/ guides changes to the PyRETIS code under its deterministic-science conventions: results are correct and reproducible, and a clear failure is preferred over a wrong pass. Its SKILL.md holds:

  • the rules: a failing test stops the work and is judged by a session with a clean context; comments and docstrings describe the code as it stands; the user guide tells the person who runs PyRETIS what to set and what happens; the tests of new code come from a separate session; reference data move only with a named cause; test-easy.sh runs before every commit, the tests it leaves out (marked heavy) before every push, and test-heavy.sh and every push wait for the maintainer’s permission; commits reach the stable branches through reviewed merges; a value without evidence is reported as unverified, or the work stops;

  • the codebase map: core, engines, simulation, input and output, analysis, and the command-line interface;

  • the workflow: change, test gate, tests from a separate session, engine validation, re-generation of references, method validation, commits by kind, review before the push, leaving the machine and the hosts clean.

Engine references are graded by build version. A run on the reference build of an engine compares its output with the committed references; a run on another build is an execution smoke test and reports the suite as NOT VALIDATED. References are re-generated deliberately, with OMP_NUM_THREADS=1, by the generation command that examples/tests/reference_provenance.json records for each suite, and checked by running the suite twice, for bit-identical output, and comparing it with the new references. The heavy suite can run on a remote host through devtools/remote_validate.sh.

Table 59 Topic files of the developer skill

File

Read when

style.md

writing or editing code, comments, docstrings or the user guide

testing.md

running the gates, committing the tree that passed, a test fails, judging failing tests, tests are needed for new code, or a failure shows only in the full gate

validation.md

engine reference suites, re-generating references, remote hosts, the method-validation suite

engines.md

adding or changing an MD engine

scheduler.md

changing the scheduler, the moves, the output layout, the input schemas or restarts

agents.md

several agents work at the same time, or work is handed to sub-agents

review.md

reviewing a change or a range of commits, verifying findings, a fix round, or changing what earlier files mean

merging.md

merging a development branch into a stable branch in chunks

commits.md

committing a change by kind, the CHANGELOG, moving uncommitted work onto a new tip

roles/

launching a sub-agent: the prompts of the reviewer, verifier, fixer, test writer, test judge, docs auditor and docs checker

Role prompts for sub-agents

The folder roles/ holds the prompts that the agent gives to the sub-agents it launches. A sub-agent starts as a fresh agent, with none of the context of the session that launches it, and receives its role file and the inputs that the file names. Each role file names the inputs the sub-agent receives, or the files it may read, its method, and the report it writes. With this separation, the tests of new code are written from their specification, and failing tests are judged, by agents that hold none of the reasoning of the session that wrote the code. The topic file agents.md describes how the work is divided among the agents.

Table 60 Role files of the developer skill

File

The sub-agent

reviewer.md

reviews part of a commit range for defects before it is merged

verifier.md

tries to refute one review finding, or a fix, and confirms it when it reproduces it

test-writer.md

writes the tests of new code from its specification

test-judge.md

rules on existing tests that fail after a production change: the code is wrong, or the change moved the pinned behaviour on purpose

fixer.md

makes the production pass of one item of a fix round

docs-auditor.md

audits pages of the user guide for passages that got worse for a user

docs-checker.md

checks a documentation change before it is committed: every statement verified, written for the user, rendered

Example requests

Add a new order-parameter class, have its unit tests written by a
test-writer sub-agent, and run the fast gate.

My LAMMPS reference test reports NOT VALIDATED. Is my LAMMPS build the
reference build, and how do I get a numerical validation?

Re-generate the CP2K references on my local CP2K build and confirm that
run-all-cp2k.sh reports the suite as validated.

Review the commits since the last merge with reviewer sub-agents, have
each finding checked by a verifier, and list the confirmed ones.

Add streaming support to the <engine> engine, mirroring the GROMACS
streaming/relaunch pair, and verify streaming == relaunch on the mock.

Installing a skill

Place the skill folder, with all its files and sub-directories, in the skills directory of the agent: for Claude Code, .claude/skills/<name>/ of a project. A checkout of the repository holds .claude/skills/pyretis-pathsampling and .claude/skills/pyretis-development as links to the folders of skills/, so an agent started in the checkout finds both skills. Any other agent that reads local files uses the same folders: point it to the SKILL.md of the skill that fits the task.

Work from the conda environment of the project. Both skills start from the smoke test devtools/smoke_test.sh, which checks the import of PyRETIS, the analysis API, and a pyretis run followed by pyretis analyse, in a few seconds. The agent runs pyretis run and pyretis analyse, or the test gates, and copies an example to a scratch directory before running it, so the tracked source tree stays clean.

The documentation index: llms.txt

llms.txt is a compact, machine-readable index of this documentation for agents and search tools: the core links (this page, the develop and stable documentation, the source repository, the license), one line per documentation page with its description, and the conventions for generated answers (the pyretis command, the TOML input format, the citations). llms-full.txt holds the text of the written guides in one file. Both are built with the documentation.

Choosing an LLM

Choose a model by its demonstrated capabilities: tool use, code quality and scientific reasoning. For either skill, have the agent keep the input files, commands, software versions and analysis output needed to audit its result.

Table 61 Recommended model capabilities

Skill

Recommended model type

Minimum practical capability

User path-sampling skill

A general-purpose reasoning model that can use local tools, read scientific documentation, and generate TOML and Python reliably.

Follows multi-step instructions, preserves units and file paths, can run shell commands in the project environment, and reports the uncertainty of each result.

Developer skill

A software-engineering or coding agent with shell access, repository navigation, patch generation, test debugging, and the launch of sub-agents for the role prompts.

Reads a multi-file code change in context, executes tests, interprets failures, and reports the exact validation performed. A stronger coding model suits engine integrations and numerical-reference changes.

For either skill, the agent cites the method references below for scientific claims, and backs a convergence claim with the evidence that the user skill asks for.

Method references

The user skill cites the following primary sources (references.md), so an agent attributes each method-level claim to the relevant literature.

Foundations

Moves and sampling

Memory reduction and long timescales

The PyRETIS software

See Scientific results for application papers (autoionization of water, DNA binding, atmospheric reactions, …).