catgo-build-workflow

Tight playbook for assembling a CatGo workflow in one or two MCP round-trips. The default CatBot path explores node_types, node_details, templates, then incrementally adds nodes and edges — that is 8+ MCP calls and the user sees the "Thinking…" indicator for tens of seconds. This skill cuts it to 1–2 calls.

Iron rule: every reaction-mechanism workflow ends in Gibbs free energy

Activities, overpotentials, and barriers reported in catalysis literature are differences in Gibbs free energy at the operating temperature, not DFT electronic energies. So whenever the user asks for a reaction pathway — CO2RR, OER, HER, NRR, ORR, NEB, slow-growth, C–N coupling, anything ending in *RR, anything called "free energy diagram" or "volcano plot" — the workflow must contain a freq node between geo_opt (or md) and free_energy (or the reaction-specific analysis node). Without freq there is no ZPE and no thermal/entropic correction, the resulting numbers cannot be compared to experiment, and the user is silently wrong.

If the user proposes a mechanism workflow without a freq step, add one anyway and tell them one short sentence why ("Inserted a freq step so the ΔG values include ZPE + TS — without it the free-energy diagram is just an electronic-energy diagram"). If they explicitly say "skip freq for now, I just want a quick electronic-energy scan", honour it but flag that the result is not a Gibbs energy.

The freq node must run on the same geometry as the final relaxation it sits after — chaining geo_opt → freq → free_energy keeps the geometries consistent. For adsorbate thermochemistry, use freeze_mode: "adsorbate": freeze the full slab and vibrate only atoms tagged by adsorbate_place.

Clean-slab invariant

Every surface-reaction workflow built from a bulk structure must use structure_input → slab_gen → geo_opt(clean slab) → adsorbate_place. Reuse the same relaxed clean-slab output for every adsorbate branch. Never connect slab_gen directly to adsorbate_place: doing so optimizes only slab+adsorbate states and leaves no consistent relaxed clean-slab reference.

When to use this skill

• User asks to create, build, set up, or make a workflow.
• User names a known reaction or pipeline (CO2RR, OER, HER, NRR, NEB, DOS, slow-growth, bulk→slab→adsorbate).
• User pastes a textual recipe like "structure_input → geo_opt → freq → free_energy".

If the user wants to modify an existing workflow (add a node to one that already exists), prefer a direct catgo_workflow {action:"add_node"} call rather than reloading this skill.

The fast path

1. For stock HER/OER/ORR/NRR/CO2RR workflows, call catgo_quickbuild and stop; its server-side recipes enforce the clean-slab invariant. Use the manual path below only for custom graphs.
2. Pick a recipe from the "Recipes" section below — or assemble one from the node-type table — and prepare the graph_json payload.
3. Call catgo_workflow with action="create", name="<descriptive>", template_id only if you genuinely want the backend's stock template (most of the time you do not, because the recipes here are tighter). Otherwise omit template_id — create will auto-add a structure_input node seeded from the viewer's current structure.
4. Immediately call catgo_workflow with action="batch" and an operations array carrying every add_node + connect step in one round-trip. Do not call add_node one at a time.
5. Confirm with one short sentence ("Built '': N nodes, M edges. Open the Workflow tab to inspect."). Do not list every node — the user can see the graph in the editor.

That is the entire happy path. Do not call templates, node_types, node_details, list_presets, or get before creating unless the user explicitly asks "what templates exist?" — those calls only exist for discovery and the recipes below already cover the common cases.

Recipes

Each recipe gives the operations array you pass to batch. The seed structure_input node is already created for you by create; reference it as "si" in from fields. Use stable short IDs (n1, n2, …) for new nodes — these only need to be unique within the workflow.

CO2RR (CO2 reduction on metal slab)

[
  {"op":"add_node","id":"opt","type":"geo_opt","x":300,"y":200,"params":{"software":"vasp","encut":520,"ediffg":-0.03}},
  {"op":"add_node","id":"freq","type":"freq","x":520,"y":200,"params":{"software":"vasp","freeze_mode":"adsorbate"}},
  {"op":"add_node","id":"fe","type":"free_energy","x":740,"y":200,"params":{"temperature":298.15,"reference":"CHE"}},
  {"op":"connect","from":"si","to":"opt"},
  {"op":"connect","from":"opt","to":"freq"},
  {"op":"connect","from":"freq","to":"fe"}
]

For multi-intermediate CO2RR (CO2* → COOH* → CO* → CHO* …), duplicate geo_opt + freq per intermediate, all wired to the same free_energy node which aggregates ΔG values.

OER (4-electron water oxidation)

[
  {"op":"add_node","id":"opt","type":"geo_opt","x":300,"y":200,"params":{"software":"vasp","encut":520}},
  {"op":"add_node","id":"freq","type":"freq","x":520,"y":200,"params":{"software":"vasp"}},
  {"op":"add_node","id":"oer","type":"oer_analysis","x":740,"y":200,"params":{"reference":"CHE","pH":0}},
  {"op":"connect","from":"si","to":"opt"},
  {"op":"connect","from":"opt","to":"freq"},
  {"op":"connect","from":"freq","to":"oer"}
]

If the OER analysis node type is not registered, fall back to free_energy and tell the user to flip the analysis mode in the node panel.

HER (hydrogen evolution)

[
  {"op":"add_node","id":"opt","type":"geo_opt","x":300,"y":200,"params":{"software":"vasp","encut":520}},
  {"op":"add_node","id":"freq","type":"freq","x":520,"y":200,"params":{"software":"vasp"}},
  {"op":"add_node","id":"fe","type":"free_energy","x":740,"y":200,"params":{"reference":"CHE","target":"H"}},
  {"op":"connect","from":"si","to":"opt"},
  {"op":"connect","from":"opt","to":"freq"},
  {"op":"connect","from":"freq","to":"fe"}
]

NEB / transition state

[
  {"op":"add_node","id":"r_opt","type":"geo_opt","x":300,"y":120,"params":{"software":"vasp","label":"reactant"}},
  {"op":"add_node","id":"p_opt","type":"geo_opt","x":300,"y":320,"params":{"software":"vasp","label":"product"}},
  {"op":"add_node","id":"neb","type":"neb","x":540,"y":220,"params":{"software":"vasp","n_images":7,"climbing":true}},
  {"op":"add_node","id":"freq","type":"freq","x":760,"y":220,"params":{"software":"vasp"}},
  {"op":"connect","from":"si","to":"r_opt"},
  {"op":"connect","from":"si","to":"p_opt"},
  {"op":"connect","from":"r_opt","to":"neb","handle":"reactant"},
  {"op":"connect","from":"p_opt","to":"neb","handle":"product"},
  {"op":"connect","from":"neb","to":"freq"}
]

NEB needs two structure_input nodes if reactant and product are different structures. Ask the user before assuming the seed structure is one endpoint. If they confirm two endpoints, add a second structure_input in the operations array and skip the auto-seeded one (or repurpose it as the reactant).

DOS / Band structure

[
  {"op":"add_node","id":"opt","type":"geo_opt","x":300,"y":200,"params":{"software":"vasp","encut":520}},
  {"op":"add_node","id":"sp","type":"single_point","x":520,"y":200,"params":{"software":"vasp","encut":520}},
  {"op":"add_node","id":"dos","type":"dos_analysis","x":740,"y":200,"params":{"emin":-10,"emax":5,"d_band_center":true}},
  {"op":"connect","from":"si","to":"opt"},
  {"op":"connect","from":"opt","to":"sp"},
  {"op":"connect","from":"sp","to":"dos"}
]

Add a second single_point for band structure with a denser k-path if the user asks for both.

Slow-growth AIMD (constrained MD with ICONST)

[
  {"op":"add_node","id":"opt","type":"geo_opt","x":300,"y":200,"params":{"software":"vasp"}},
  {"op":"add_node","id":"equil","type":"md","x":520,"y":200,"params":{"software":"vasp","ensemble":"nvt","temperature":300,"nsw":2000,"potim":0.5}},
  {"op":"add_node","id":"sg","type":"slow_growth","x":740,"y":200,"params":{"software":"vasp","iconst":"<user-provided>"}},
  {"op":"add_node","id":"barrier","type":"md_analysis","x":960,"y":200,"params":{"mode":"barrier"}},
  {"op":"connect","from":"si","to":"opt"},
  {"op":"connect","from":"opt","to":"equil"},
  {"op":"connect","from":"equil","to":"sg"},
  {"op":"connect","from":"sg","to":"barrier"}
]

The iconst template depends on the reaction coordinate — for C–N coupling use R 1 2 0 (where 1 and 2 are the atom indices and the trailing 0 increments per step). Confirm the indices with the user before submitting.

Bulk → Slab → Adsorbate

[
  {"op":"add_node","label":"bulk_opt","node_type":"cell_opt","params":{"software":"vasp","encut":520}},
  {"op":"add_node","label":"slab","node_type":"slab_gen","params":{"miller":"1,1,1","layers":4,"vacuum":15}},
  {"op":"add_node","label":"slab_opt","node_type":"geo_opt","params":{"software":"vasp","frozen_layers":2}},
  {"op":"add_node","label":"ads","node_type":"adsorbate_place","params":{"species":"CO","site":"ontop"}},
  {"op":"add_node","label":"ads_opt","node_type":"geo_opt","params":{"software":"vasp","frozen_layers":2}},
  {"op":"connect","from_id":"si","to_id":"bulk_opt"},
  {"op":"connect","from_id":"bulk_opt","to_id":"slab"},
  {"op":"connect","from_id":"slab","to_id":"slab_opt"},
  {"op":"connect","from_id":"slab_opt","to_id":"ads"},
  {"op":"connect","from_id":"ads","to_id":"ads_opt"}
]

Node-type cheat sheet

When the user asks for something not in the recipes above, you can usually compose it from these node types. Do not call node_types to refresh this list unless the user reports a node-type error.

Type	Purpose	Common params
structure_input	Seed structure (POSCAR/CIF/MP-ID)	mp_id, structure_json
cell_opt	Cell + ion relaxation (ISIF=3)	software, encut, ediffg
geo_opt	Ion-only relaxation (ISIF=2)	software, encut, ediffg, frozen_layers
single_point	Static SCF	software, encut, ismear
md	Molecular dynamics	ensemble, temperature, nsw, potim
slow_growth	Constrained AIMD via ICONST	iconst, nsw
freq	Vibrational frequencies	freeze_mode, freeze_layers
neb	NEB / CI-NEB TS search	n_images, climbing
ts_search	Sella / DIMER TS	software, mode
slab_gen	Cut slab from bulk	miller, layers, vacuum, supercell
adsorbate_place	Place adsorbate on slab	species, site, height
dos_analysis	DOS / PDOS / d-band	emin, emax, d_band_center
free_energy	ΔG with ZPE + TS corrections	temperature, reference, target
md_analysis	RDF / MSD / barrier from trajectory	mode, pairs
condition	If/else branching	expression
loop	Iterate over a list	variable, values
merge	Barrier / join branches	—

When to deviate

• If the user asks for an obscure pipeline ("slab convergence sweep across layer counts 3, 4, 5, 6"), you still build it in one batch call — just use a loop node with variable=layers and values=[3,4,5,6].
• If a node type errors as unknown, then and only then call catgo_workflow {action:"node_types"} to refresh the catalogue. Don't preemptively check.
• If the user explicitly asks for a stock backend template, call templates first to look up the template_id and pass it to create.

What to tell the user when done

One sentence. State the workflow name, node count, and that the workflow is open in the editor for inspection. Do not dump the operations array, the graph_json, or per-node parameter lists — the editor visualises all of that. Example:

Built "CO2RR on Cu(100)": 4 nodes, 3 edges. Opened in the Workflow tab — review and click ▶ Run when ready.