3. ABCluster SKILL: Generating ABCluster Input with AI Coding Agents

Tip

This tutorial shows how to let an AI agent write your geom input files for you. We use Cursor together with the abcluster-geom-input-generator Skill as the example. After reading it, you will be able to describe a cluster structure prediction problem in plain language and obtain a ready-to-run geom calculation in seconds. Of course, this skill can be used for other ABCluster modules and other AI coding agents like Claude or Codex, as well.

3.1. What is a Skill?

A Skill is a small package of expert knowledge that you give to an AI coding agent. It is a folder containing a SKILL.md file that describes when the skill should be used and how to perform the task. When your request matches the skill, the agent reads the SKILL.md and follows its instructions, so you get answers from someone who already knows all the keywords, defaults, and pitfalls of the task.

ABCluster has provided a set of skills for all modules, you can find them in the skills folder of the ABCluster distribution:

  • abcluster-atom-input-generator for atom

  • abcluster-rigidmol-input-generator for rigidmol

  • abcluster-isomer-input-generator for isomer

  • abcluster-geom-input-generator for geom

The abcluster-geom-input-generator skill encapsulates everything in Input File for geom, Flexibility, and the worked examples of this manual. Given a natural-language description, it produces:

  • a complete geom.inp;

  • the auxiliary .xyz files for each component (and a topgen bonding file if a unit is flexible);

  • the exact command to run the job;

  • a checklist of the assumptions it made.

3.2. Prerequisites

Before you start, make sure you have:

  • Cursor installed (any recent version with Agent mode);

  • a working ABCluster installation, so that the geom and topgen commands are on your PATH (see Introduction);

  • the skill placed where Cursor can find it, namely inside your project at:

    <your-project>/.cursor/skills/abcluster-geom-input-generator/SKILL.md

Tip

Skills are discovered automatically. As long as SKILL.md lives under .cursor/skills/ in the folder you open in Cursor, the agent will load it when your request is relevant. You can also keep skills globally under ~/.cursor/skills/ to make them available in every project.

3.3. Step 1: Open your working folder in Cursor

Create an empty folder for the calculation and open it in Cursor ( File → Open Folder…). This folder is where the agent will write geom.inp and the .xyz files, and where you will later run geom.

Then open the chat panel (Ctrl/Cmd + L) and make sure the mode selector at thebottom of the chat is set to Agent, not Ask. Only the Agent mode is allowed to create files on disk.

3.4. Step 2: Describe your problem

Now simply tell the agent what you want, in plain language. You do NOT have to remember any ABCluster keyword. For example, type into the chat:

Use the abcluster-geom-input-generator skill to prepare a geom calculation
that searches for the global minimum of NaCl(H2O)10 with GFN1-xTB.

A few notes about this prompt:

  • Mentioning the skill name (abcluster-geom-input-generator) is the most reliable way to trigger it, but it is optional: phrases like “prepare an ABCluster geom calculation” or “conformation search with ABCluster” also match the skill’s description and let Cursor pick it up on its own.

  • You can be as vague or as precise as you like. If you omit details such as the number of calculations, the skill will choose sensible defaults (see the Defaults table in Input File for geom) and tell you what it assumed.

Tip

You can also drag a structure file into the chat, e.g. “here is my ligand.xyz, put 6 of them as a shell around this fixed core.xyz“. The agent will reuse your files instead of inventing coordinates.

3.5. Step 3: Review what the agent generated

The agent reads SKILL.md, then writes the files into your folder and summarizes them in the chat. For the prompt above you will get an input file equivalent to:

naclh2o10.inp
 1lm_dir          naclh2o10 # Save the local minima to this folder.
 2num_calcs       2000      # Total number of calculations.
 3do_coarse_opt   yes       # Coarse pre-optimization (recommended).
 4min_energy_gap  1.E-4     # Energies closer than this are treated as identical.
 5max_geom_iters  3000      # Max iterations for each local optimization.
 6
 7components
 8    h2o.xyz 10
 9    random 0 0 0 8 8 8
10    ****
11    na.xyz 1
12    random 0 0 0 8 8 8
13    ****
14    cl.xyz 1
15    random 0 0 0 8 8 8
16    ****
17end
18
19xtb
20    0 0 1                 # charge, unpaired electrons, GFN type (1 = GFN1-xTB)
21end
22
23commands
24    $xTB$
25end

together with the three component files:

h2o.xyz
13
2water
3O                  0.00000000    0.00000000   -0.11081188
4H                  0.00000000   -0.78397589    0.44324751
5H                 -0.00000000    0.78397589    0.44324751
na.xyz
11
2Na
3Na  0 0 0
cl.xyz
11
2Cl
3Cl  0 0 0

In xtb block in naclh2o10.inp is where the charge, the number of unpaired electrons, and the GFN Hamiltonian type are set. Read the agent’s summary and check that these match your chemistry. The skill always ends with an assumptions checklist such as “box size 8×8×8 Å, neutral system, GFN1 because it is an ionic atomic-like cluster” — a quick glance there is usually enough to confirm the input is what you intended.

Tip

If something is wrong, just say so in the chat: “use GFN2 instead”, “increase num_calcs to 5000”, or “the system charge should be -1”. The agent will edit the files in place. This conversational refinement is the main advantage over writing the input by hand.

3.6. Step 4: Run the calculation

Once you are happy with the files, run geom exactly as in the other tutorials. You can do this in Cursor’s built-in terminal (Ctrl/Cmd + :kbd:`) or any shell:

$ export OMP_STACKSIZE=4G        # recommended when using the built-in xTB
$ geom naclh2o10.inp > naclh2o10.out

Tip

You can even ask the agent to run it for you: “now run this calculation”. In Agent mode, Cursor will execute the command in the terminal and report back when it finishes.

The local minima are written to the lm_dir folder (here naclh2o10/), and the energy ranking is printed at the end of naclh2o10.out:

naclh2o10.out
 -- Result Report --
Results are energy-increasingly reordered.
Structures of energies within 1.000E-04 are treated as degenerate.
All minima are saved to "naclh2o10".
-------------------------------------------------------------------
     #  index               Energy            NaiveRMSD
-------------------------------------------------------------------
     0    410         -78.90900677           0.00000000
     1   1315         -73.85642855          11.13424019
     ... omitted ...
    33    859         -62.49102429           9.53495472

As explained in geom with xTB, you should always inspect the low-lying structures (here naclh2o10/410.xyz and so on): unphysically low energies can come from un-converged SCF on bad initial guesses. You can ask the agent to help here too, e.g. “open naclh2o10/863.xyz and tell me if it looks reasonable”.

3.7. Summary

The workflow is always the same:

  1. Open your calculation folder in Cursor (Agent mode), with the skill under .cursor/skills/.

  2. Describe the cluster and the method in plain language.

  3. Review the generated geom.inp and .xyz files against the assumptions checklist; refine by chatting.

  4. Run geom (optionally letting the agent run it), then inspect the resulting structures.

The skill turns the knowledge spread across this whole geom chapter into a single conversation, while you stay in full control of the final input.