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. .. contents:: :local: 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 :doc:`geom-input`, :doc:`geom-bonding`, 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. 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 :doc:`introduction`); - the skill placed where Cursor can find it, namely inside your project at:: /.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. Step 1: Open your working folder in Cursor --------------------------------------------- Create an empty folder for the calculation and open it in Cursor ( :guilabel:`File` → :guilabel:`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 (:kbd:`Ctrl/Cmd` + :kbd:`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. 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: .. code-block:: text 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 :doc:`geom-input`) 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. 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: .. code-block:: bash :linenos: :caption: naclh2o10.inp lm_dir naclh2o10 # Save the local minima to this folder. num_calcs 2000 # Total number of calculations. do_coarse_opt yes # Coarse pre-optimization (recommended). min_energy_gap 1.E-4 # Energies closer than this are treated as identical. max_geom_iters 3000 # Max iterations for each local optimization. components h2o.xyz 10 random 0 0 0 8 8 8 **** na.xyz 1 random 0 0 0 8 8 8 **** cl.xyz 1 random 0 0 0 8 8 8 **** end xtb 0 0 1 # charge, unpaired electrons, GFN type (1 = GFN1-xTB) end commands $xTB$ end together with the three component files: .. code-block:: bash :linenos: :caption: h2o.xyz 3 water O 0.00000000 0.00000000 -0.11081188 H 0.00000000 -0.78397589 0.44324751 H -0.00000000 0.78397589 0.44324751 .. code-block:: bash :linenos: :caption: na.xyz 1 Na Na 0 0 0 .. code-block:: bash :linenos: :caption: cl.xyz 1 Cl Cl 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. 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 (:kbd:`Ctrl/Cmd` + :kbd:`````) or any shell: .. code-block:: bash $ 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``: .. code-block:: bash :caption: 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 :doc:`eg-geom-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"*. 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.