From a6eced5cbd5e43e42d0c623d7c070b2592f65674 Mon Sep 17 00:00:00 2001
From: trvachov <120140748+trvachov@users.noreply.github.com>
Date: Fri, 16 Oct 2026 07:15:24 +0000
Subject: [PATCH] chore: sync skills from source repos
---
library-skills/nvmolkit-usage/BENCHMARK.md | 136 +++++++++++
library-skills/nvmolkit-usage/SKILL.md | 220 +++++++++++-------
.../nvmolkit-usage/evals/evals.json | 23 +-
.../nvmolkit-usage/evals/trigger_evals.json | 7 +-
.../references/advanced-usage.md | 79 +++++++
library-skills/nvmolkit-usage/skill-card.md | 85 +++++++
library-skills/nvmolkit-usage/skill.oms.sig | 1 +
.../kermt-add-cmim-pretrain/skill-card.md | 77 ++++++
.../kermt-continue-pretrain/skill-card.md | 77 ++++++
.../kermt/kermt-embed/skill-card.md | 69 ++++++
.../kermt/kermt-finetune/skill-card.md | 78 +++++++
.../kermt/kermt-infer/skill-card.md | 74 ++++++
.../kermt/kermt-monitor/skill-card.md | 70 ++++++
.../kermt-pretrain-scratch/skill-card.md | 77 ++++++
.../kermt/kermt-setup/skill-card.md | 69 ++++++
.../complexa-design/SKILL.md | 24 +-
.../complexa-design/evals/trigger_evals.json | 27 ---
.../complexa-design/skill-card.md | 80 +++++++
.../complexa-evaluate-pdbs/SKILL.md | 23 +-
.../evals/trigger_evals.json | 20 --
.../complexa-evaluate-pdbs/skill-card.md | 75 ++++++
.../proteina-complexa/complexa-setup/SKILL.md | 6 +-
.../config/skillspector-baseline.yml | 23 --
.../complexa-setup/reference/downloads.md | 13 +-
.../complexa-setup/skill-card.md | 68 ++++++
.../proteina-complexa/complexa-sweep/SKILL.md | 2 +-
.../complexa-sweep/reference/SWEEP.md | 10 +-
.../complexa-sweep/reference/sweep_axes.md | 6 +-
.../complexa-sweep/skill-card.md | 75 ++++++
.../complexa-target/skill-card.md | 70 ++++++
.../skills/complexa-design/SKILL.md | 24 +-
.../complexa-design/evals/trigger_evals.json | 27 ---
.../skills/complexa-design/skill-card.md | 80 +++++++
.../skills/complexa-evaluate-pdbs/SKILL.md | 23 +-
.../evals/trigger_evals.json | 20 --
.../complexa-evaluate-pdbs/skill-card.md | 75 ++++++
.../skills/complexa-setup/SKILL.md | 6 +-
.../config/skillspector-baseline.yml | 23 --
.../complexa-setup/reference/downloads.md | 13 +-
.../skills/complexa-setup/skill-card.md | 68 ++++++
.../skills/complexa-sweep/SKILL.md | 2 +-
.../skills/complexa-sweep/reference/SWEEP.md | 10 +-
.../complexa-sweep/reference/sweep_axes.md | 6 +-
.../skills/complexa-sweep/skill-card.md | 75 ++++++
.../skills/complexa-target/skill-card.md | 70 ++++++
.../kermt-add-cmim-pretrain/skill-card.md | 77 ++++++
.../kermt-continue-pretrain/skill-card.md | 77 ++++++
.../skills/kermt-embed/skill-card.md | 69 ++++++
.../skills/kermt-finetune/skill-card.md | 78 +++++++
.../skills/kermt-infer/skill-card.md | 74 ++++++
.../skills/kermt-monitor/skill-card.md | 70 ++++++
.../kermt-pretrain-scratch/skill-card.md | 77 ++++++
.../skills/kermt-setup/skill-card.md | 69 ++++++
.../skills/nvmolkit-usage/SKILL.md | 220 +++++++++++-------
.../skills/nvmolkit-usage/evals/evals.json | 23 +-
.../nvmolkit-usage/evals/trigger_evals.json | 7 +-
.../references/advanced-usage.md | 79 +++++++
57 files changed, 2698 insertions(+), 408 deletions(-)
create mode 100644 library-skills/nvmolkit-usage/BENCHMARK.md
create mode 100644 library-skills/nvmolkit-usage/references/advanced-usage.md
create mode 100644 library-skills/nvmolkit-usage/skill-card.md
create mode 100644 library-skills/nvmolkit-usage/skill.oms.sig
create mode 100644 open-models-skills/kermt/kermt-add-cmim-pretrain/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-continue-pretrain/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-embed/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-finetune/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-infer/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-monitor/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-pretrain-scratch/skill-card.md
create mode 100644 open-models-skills/kermt/kermt-setup/skill-card.md
delete mode 100644 open-models-skills/proteina-complexa/complexa-design/evals/trigger_evals.json
create mode 100644 open-models-skills/proteina-complexa/complexa-design/skill-card.md
delete mode 100644 open-models-skills/proteina-complexa/complexa-evaluate-pdbs/evals/trigger_evals.json
create mode 100644 open-models-skills/proteina-complexa/complexa-evaluate-pdbs/skill-card.md
delete mode 100644 open-models-skills/proteina-complexa/complexa-setup/config/skillspector-baseline.yml
create mode 100644 open-models-skills/proteina-complexa/complexa-setup/skill-card.md
create mode 100644 open-models-skills/proteina-complexa/complexa-sweep/skill-card.md
create mode 100644 open-models-skills/proteina-complexa/complexa-target/skill-card.md
delete mode 100644 skills/bionemo-agent-toolkit/skills/complexa-design/evals/trigger_evals.json
create mode 100644 skills/bionemo-agent-toolkit/skills/complexa-design/skill-card.md
delete mode 100644 skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/evals/trigger_evals.json
create mode 100644 skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/skill-card.md
delete mode 100644 skills/bionemo-agent-toolkit/skills/complexa-setup/config/skillspector-baseline.yml
create mode 100644 skills/bionemo-agent-toolkit/skills/complexa-setup/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/complexa-sweep/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/complexa-target/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-add-cmim-pretrain/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-continue-pretrain/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-embed/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-finetune/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-infer/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-monitor/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-pretrain-scratch/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/kermt-setup/skill-card.md
create mode 100644 skills/bionemo-agent-toolkit/skills/nvmolkit-usage/references/advanced-usage.md
diff --git a/library-skills/nvmolkit-usage/BENCHMARK.md b/library-skills/nvmolkit-usage/BENCHMARK.md
new file mode 100644
index 00000000..600671e9
--- /dev/null
+++ b/library-skills/nvmolkit-usage/BENCHMARK.md
@@ -0,0 +1,136 @@
+# Skill Benchmark: nvmolkit-usage
+
+> ✅ **Overall verdict: PASS — Recommended for publication**
+
+## Publication Recommendation
+
+Recommended for publication based on the completed evaluation evidence in this report.
+
+## Evaluation Metadata
+
+- Skill: `nvmolkit-usage`
+- Evaluation date: 2026-09-22
+- Evaluator version: `1.5.6`
+- Agents: Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`), Codex (`openai/openai/gpt-5.5`)
+- Tasks: 12 evaluation tasks (12 positive)
+- Dataset digest: `sha256:ce8098e0dd2fc0698933b7d4d303fe13bdd1d9be7e87d142bdfc44baae7a9f90` (skill-evaluator-dataset-snapshot/1)
+- Attempts per task: 3
+- Environment: `k8s-sandbox`
+- Tier 2 evidence: required for publication
+- Tier 3 evidence: required for publication
+
+Each task attempt ran in its own isolated sandbox pod.
+
+## What This Report Answers
+
+The three-tier evaluation checks whether the skill:
+
+- is safe to use;
+- produces correct answers;
+- is discovered and activated when needed;
+- helps the agent complete the user's goal and expected workflow; and
+- avoids wasted skill and tool usage.
+
+## Results at a Glance
+
+| Measure | Claude Code (Baseline → Skill Uplift) | Codex (Baseline → Skill Uplift) |
+|---|---:|---:|
+| Overall | 91.1% — baseline ran, but no comparable score was available; uplift unavailable | 92.3% — baseline ran, but no comparable score was available; uplift unavailable |
+| Security | 66.7% → 91.7% (+25.0 points) | 100.0% → 100.0% (±0.0 points) |
+| Correctness | 95.0% → 100.0% (+5.0 points) | 96.7% → 96.7% (±0.0 points) |
+| Discoverability | 91.7% — baseline ran, but no comparable score was available; uplift unavailable | 95.0% — baseline ran, but no comparable score was available; uplift unavailable |
+| Effectiveness | 91.4% → 92.6% (+1.2 points) | 82.9% → 85.4% (+2.5 points) |
+| Efficiency | 79.5% — baseline ran, but no comparable score was available; uplift unavailable | 84.6% — baseline ran, but no comparable score was available; uplift unavailable |
+
+**How to read this table:** baseline is the same task attempted without the target skill. Scores are rounded to one decimal; threshold-adjacent values use additional precision so their displayed band matches the verdict. Uplift is derived from those displayed scores and shown in percentage points.
+
+Example: `47.0% → 92.0% (+45.0 points)` means the skill-assisted run scored 92.0%, 45.0 percentage points above its 47.0% no-skill baseline.
+
+## Token Usage
+
+Actual Tier 3 execution usage is reported for every observed agent/case pair and both conditions.
+
+| Agent | Dataset case | With skill | Without skill | Delta | Change | Coverage |
+|---|---|---:|---:|---:|---:|---|
+| claude-code | All cases | 6,493,519 | 7,705,207 | -1,211,688 | -15.73% | skill 12/12; base 12/12 |
+| claude-code | nvmolkit-usage-001 | 155,960 | 499,586 | -343,626 | -68.78% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-002 | 1,444,045 | 251,086 | +1,192,959 | +475.12% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-003 | 360,067 | 1,104,712 | -744,645 | -67.41% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-004 | 397,086 | 997,159 | -600,073 | -60.18% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-005 | 1,032,516 | 813,303 | +219,213 | +26.95% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-006 | 201,515 | 899,766 | -698,251 | -77.60% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-007 | 354,878 | 826,660 | -471,782 | -57.07% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-008 | 1,120,265 | 332,364 | +787,901 | +237.06% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-009 | 68,769 | 328,077 | -259,308 | -79.04% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-010 | 587,346 | 1,087,974 | -500,628 | -46.01% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-011 | 69,433 | 62,607 | +6,826 | +10.90% | skill 1/1; base 1/1 |
+| claude-code | nvmolkit-usage-012 | 701,639 | 501,913 | +199,726 | +39.79% | skill 1/1; base 1/1 |
+| codex | All cases | 943,466 | 734,327 | +209,139 | +28.48% | skill 12/12; base 12/12 |
+| codex | nvmolkit-usage-001 | 42,367 | 42,161 | +206 | +0.49% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-002 | 41,746 | 56,617 | -14,871 | -26.27% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-003 | 74,002 | 77,309 | -3,307 | -4.28% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-004 | 93,170 | 35,798 | +57,372 | +160.27% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-005 | 132,697 | 34,827 | +97,870 | +281.02% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-006 | 94,449 | 28,675 | +65,774 | +229.38% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-007 | 71,719 | 64,534 | +7,185 | +11.13% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-008 | 142,524 | 89,073 | +53,451 | +60.01% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-009 | 30,802 | 20,599 | +10,203 | +49.53% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-010 | 118,378 | 29,444 | +88,934 | +302.04% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-011 | 30,667 | 18,603 | +12,064 | +64.85% | skill 1/1; base 1/1 |
+| codex | nvmolkit-usage-012 | 70,945 | 236,687 | -165,742 | -70.03% | skill 1/1; base 1/1 |
+| ALL AGENTS | Dataset aggregate | 7,436,985 | 8,439,534 | -1,002,549 | -11.88% | skill 24/24; base 24/24 |
+
+Prompt tokens include cached reads, so total tokens are `prompt + completion` (cached is not added twice). The Efficiency score uses `(prompt - cached) + completion`. N/A means the relevant trajectory counters were not available; coverage is never estimated.
+
+## Tier Status
+
+| Tier | Purpose | Status | Evidence |
+|---|---|---|---|
+| Tier 1 | Static validation | **PASSED WITH OBSERVATIONS** | 11 validator(s); 1 finding(s) |
+| Tier 2 | Semantic deduplication | **PASSED** | 2 validator(s); 0 finding(s) |
+| Tier 3 | Live agent evaluation | **PASS** | 2 agent(s); 12 task(s) |
+
+## Findings and Observations
+
+
+Show detailed findings and successful checks
+
+- **LOW** SCHEMA/author_format: Author must be of the form 'Name ' (`skills/nvmolkit-usage/SKILL.md`)
+
+
+
+## Scoring Methodology
+
+
+Show dimension definitions, source signals, and thresholds
+
+| Dimension | Question | Scored signals |
+|---|---|---|
+| Security | Is it safe to use? | `security` (100%) |
+| Correctness | Is the answer correct? | `accuracy` (100%) |
+| Discoverability | Was the right skill loaded when needed? | `skill_execution` (100%) |
+| Effectiveness | Did the skill help complete the task? | `goal_accuracy` (50%) + `behavior_check` (50%) |
+| Efficiency | Did it avoid wasted tool calls and token usage? | `skill_efficiency` (50%) + `token_efficiency` (50%) |
+
+- Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%.
+- Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL.
+- Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate.
+- The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold.
+- Effectiveness is the equal-weight mean of goal completion (`goal_accuracy`) and expected workflow adherence (`behavior_check`).
+- Efficiency is 50% tool-call productivity (the backward-compatible `skill_efficiency` wire id) and 50% `token_efficiency`. Positive-case skill routing is scored under Discoverability, not Efficiency; a negative case without a routing target is N/A. N/A sources are omitted, remaining weights are renormalized, and the dimension is marked partial.
+
+Signals present in this run:
+
+- `security` (Security): unsafe operations, secret leakage, and unauthorized access.
+- `skill_execution` (Skill Execution): whether the expected skill was selected, decoys were avoided, and the workflow executed.
+- `skill_efficiency` (Tool Productivity): tool-call productivity (legacy wire id; routing is scored under Discoverability).
+- `accuracy` (Accuracy): final-answer correctness against the reference answer.
+- `goal_accuracy` (Goal Accuracy): whether the user's goal was achieved.
+- `behavior_check` (Behavior Check): whether the expected workflow behavior was followed.
+- `token_efficiency` (Token Efficiency): actual uncached prompt plus completion usage (50% of Efficiency).
+
+
+
+## Freshness
+
+Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes.
diff --git a/library-skills/nvmolkit-usage/SKILL.md b/library-skills/nvmolkit-usage/SKILL.md
index 4406a54a..e9d22be6 100644
--- a/library-skills/nvmolkit-usage/SKILL.md
+++ b/library-skills/nvmolkit-usage/SKILL.md
@@ -1,26 +1,24 @@
---
name: nvmolkit-usage
description: >-
- Write code that calls the installed nvMolKit Python API for GPU-accelerated,
- batched RDKit-style operations - Morgan fingerprints, Tanimoto/cosine
- similarity, ETKDG conformer embedding, MMFF/UFF optimization, TFD, conformer
- RMSD, Butina clustering, and substructure search. Use when the user is
- importing `nvmolkit.*`, debugging an `nvmolkit` call, choosing between
- nvMolKit and RDKit for a batched cheminformatics workflow, or wiring nvMolKit
- results into a torch/numpy pipeline. Out of scope: building nvMolKit from
- source.
+ Use when writing or debugging nvMolKit Python code for GPU-accelerated RDKit
+ fingerprints, similarity, conformers, clustering, and molecular searches.
license: Apache-2.0
metadata:
+ author: Kevin Boyd (@scal444)
owner: Kevin Boyd (@scal444)
- risk_tier: skill
+ risk-tier: skill
+ tags: [cheminformatics, rdkit, cuda]
---
# nvMolKit usage
-## What nvMolKit is
+## Purpose
GPU-accelerated, batched implementations of common RDKit operations. APIs mirror RDKit where possible but are batch-oriented: they take lists of `rdkit.Chem.Mol` (or lists of fingerprints) and process them in parallel on one or more GPUs. nvMolKit links against RDKit at build time; inputs and outputs are real RDKit `Mol` objects.
+This skill covers the installed Python API. Building nvMolKit from source is out of scope.
+
## Where nvMolKit does well
Reach for nvMolKit when:
@@ -29,25 +27,39 @@ Reach for nvMolKit when:
- The metric is **throughput / total wall time across the batch**, not per-molecule latency.
- The same operation is **repeated identically** across the batch (fingerprinting a library, embedding/minimizing many conformers, bulk pairwise similarity), so the GPU stays saturated.
-Plain RDKit is usually the better choice for single-molecule one-offs or workflows that can't be expressed as a batch. nvMolKit is not meant to replace RDKit for those cases.
-
-## Runtime requirements
+## Requirements
- An NVIDIA GPU with compute capability 7.0 (V100) or higher
- A CUDA driver compatible with CUDA 12.6+.
- A working `torch` install with CUDA support (nvMolKit returns GPU tensors via `torch`'s CUDA array interface).
-If CUDA is unavailable, nvMolKit calls raise. There is no CPU fallback - if the user needs one, use RDKit directly for that path.
-
When helping with installation, make the user choose a PyTorch CUDA backend that the host driver supports before installing nvMolKit. nvMolKit's PyPI wheels are built with CUDA Toolkit 12.9 and depend on CUDA 12 runtime packages, but pip/uv can still select a CUDA 13 PyTorch wheel unless the install command says otherwise.
- Conda: prefer conda-forge `pytorch-gpu`; pin `cuda-version=12.6` or another CUDA version supported by the driver.
-- pip: send the user to the PyTorch install selector (`https://pytorch.org/get-started/locally/`) or previous-versions page (`https://pytorch.org/get-started/previous-versions/`) to install `torch` for a CUDA 12.x backend before installing nvMolKit.
+- pip: send the user to the [PyTorch install selector](https://pytorch.org/get-started/locally/) or [previous-versions page](https://pytorch.org/get-started/previous-versions/) to install `torch` for a CUDA 12.x backend before installing nvMolKit.
- uv: install nvMolKit with an explicit backend, e.g. `uv pip install --torch-backend=cu128 nvmolkit`.
-## Verify the install before writing real code
+## Inputs
+
+- Required: choose an operation and supply molecules or fingerprints from the user's code or molecular dataset. Parse SMILES with RDKit and reject failed parses (`None`).
+- Molecular operations use RDKit `Mol` objects. Add hydrogens for ETKDG; minimization and conformer comparisons need existing conformers.
+- Fingerprint similarity takes packed `AsyncGpuResult`, torch tensors, or NumPy arrays: one molecule per row, with `int32` or `uint32` words.
+- Optional: take conformer counts, fingerprint settings, cutoffs, output modes, and hardware options from the user's requested workflow; otherwise use the documented API defaults.
+
+## Limitations
-Run this once to confirm nvMolKit is importable and a GPU op works end to end:
+- CUDA is required; there is no CPU fallback. Use RDKit directly when CPU execution is needed.
+- Plain RDKit is usually preferable for single-molecule work or operations that cannot be batched.
+- ETKDG does not support custom bounds matrices, custom CPCI, coordinate maps, or separate-fragment embedding.
+- Substructure search does not support chirality-aware matching, enhanced stereochemistry, or other advanced RDKit `SubstructMatchParameters` options.
+
+## Instructions
+
+1. Run the smoke test below before writing nvMolKit code.
+2. Choose an API from the entry-point table and apply its input requirements.
+3. Handle its result as described below; synchronize asynchronous GPU results before host reads.
+
+### Verify the install before writing real code
```python
import nvmolkit
@@ -68,7 +80,7 @@ print("fps shape:", tuple(fps.shape), "dtype:", fps.dtype)
# Expected: shape (3, 32), dtype torch.int32 (1024 bits packed into 32 int32s per row)
```
-If this fails, point the user at the install guide on the docs site rather than guessing - see "Going deeper" below.
+If this fails, point the user at the [installation guide](https://nvidia-bionemo.github.io/nvMolKit/#installation) rather than guessing.
## Entry points
@@ -77,15 +89,16 @@ If this fails, point the user at the install guide on the docs site rather than
| Morgan fingerprints | `nvmolkit.fingerprints` | `MorganFingerprintGenerator(radius, fpSize).GetFingerprints(mols)` |
| Bulk Tanimoto / cosine similarity | `nvmolkit.similarity` | `crossTanimotoSimilarity(...)`, `crossCosineSimilarity(...)`, plus `*MemoryConstrained` variants for results too large to fit in GPU memory |
| ETKDG conformer embedding | `nvmolkit.embedMolecules` | `EmbedMolecules(molecules, params, confsPerMolecule, ...)` |
-| MMFF94 optimization (one-shot) | `nvmolkit.mmffOptimization` | `MMFFOptimizeMoleculesConfs(molecules, ...)` |
-| UFF optimization (one-shot) | `nvmolkit.uffOptimization` | `UFFOptimizeMoleculesConfs(molecules, ...)` |
-| Forcefield with custom options + constraints | `nvmolkit.batchedForcefield` | `MMFFBatchedForcefield(mols, properties=..., nonBondedThreshold=..., ignoreInterfragInteractions=..., hardwareOptions=...)`, `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`. Per-molecule view `ff[i]` exposes `add_distance_constraint`, `add_position_constraint`, `add_angle_constraint`, `add_torsion_constraint`. Methods: `.compute_energy()`, `.compute_gradients()`, `.minimize(maxIters, forceTol)` |
+| MMFF94 optimization (one-shot) | `nvmolkit.mmffOptimization` | `MMFFOptimizeMoleculesConfs(molecules, ..., minimizerKind=..., fireOptions=...)` |
+| UFF optimization (one-shot) | `nvmolkit.uffOptimization` | `UFFOptimizeMoleculesConfs(molecules, ..., minimizerKind=..., fireOptions=...)` |
+| Forcefield with custom options + constraints | `nvmolkit.batchedForcefield` | `MMFFBatchedForcefield(mols, properties=..., nonBondedThreshold=..., ignoreInterfragInteractions=..., hardwareOptions=...)`, `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`. Per-molecule view `ff[i]` exposes `add_distance_constraint`, `add_position_constraint`, `add_angle_constraint`, `add_torsion_constraint`. Methods: `.compute_energy()`, `.compute_gradients()`, `.minimize(maxIters, forceTol, minimizerKind=..., fireOptions=...)` |
| Pairwise conformer RMSD | `nvmolkit.conformerRmsd` | `GetConformerRMSMatrix(mol)`, `GetConformerRMSMatrixBatch(mols)` |
| Torsion Fingerprint Deviation (TFD) | `nvmolkit.tfd` | `GetTFDMatrix(mol)`, `GetTFDMatrices(mols)` |
-| Butina clustering | `nvmolkit.clustering` | `butina(distance_matrix, cutoff)` (precomputed matrix), `fused_butina(fingerprints, cutoff)` (memory-efficient, on-the-fly) |
+| Butina clustering | `nvmolkit.clustering` | `butina(distance_matrix, cutoff)` (precomputed matrix), `fused_butina(fingerprints, cutoff)` (memory-efficient, on-the-fly); both support explicit RDKit and device output modes |
| Substructure search | `nvmolkit.substructure` | `hasSubstructMatch`, `countSubstructMatches`, `getSubstructMatches` |
+| Maximum common substructure | `nvmolkit.mcs` | `findMCS(mols, ...)` for all pairs, explicit pairs, or two paired molecule lists |
| Hardware tuning (batch size, GPU IDs) | `nvmolkit.types` | `HardwareOptions(...)` passed to ETKDG / MMFF / UFF |
-| Optional autotuning of `HardwareOptions` | `nvmolkit.autotune` | `tune_embed_molecules`, `tune_mmff_optimize`, `tune_uff_optimize`, `tune_batched_forcefield`. Requires the `optuna` package |
+| Optional autotuning | `nvmolkit.autotune` | `tune_embed_molecules`, `tune_mmff_optimize`, `tune_uff_optimize`, `tune_batched_forcefield`, `tune_substructure`, `tune_mcs`. Requires the `optuna` package |
## Result types and execution model
@@ -111,7 +124,7 @@ APIs that take a `stream` argument:
- `butina`, `fused_butina`
- `GetConformerRMSMatrix`, `GetConformerRMSMatrixBatch`
-Other APIs (ETKDG, MMFF/UFF optimization, TFD, substructure search) are synchronous to the caller — no stream plumbing needed.
+Other APIs (ETKDG, MMFF/UFF optimization, TFD, substructure search, MCS) are synchronous to the caller — no stream plumbing needed.
Typical pattern:
@@ -144,41 +157,26 @@ Used by ETKDG embedding and MMFF/UFF optimization (one-shot and `BatchedForcefie
The default mode (`CoordinateOutput.RDKIT_CONFORMERS`) still writes optimized coordinates back into each `Mol` and returns Python lists of energies/convergence flags. Reach for `CoordinateOutput.DEVICE` when chaining downstream GPU work (e.g. ETKDG → MMFF → similarity scoring) without host round-trips.
-## Configuration
-
-Two configuration objects expose the GPU/CPU knobs.
+### `MCSBatchResult`
-### `HardwareOptions` (ETKDG, MMFF, UFF)
+`findMCS` is synchronous and returns an `MCSBatchResult` backed by CPU NumPy
+arrays. Results are always flat: `result[k]` (or `result.get_result(k)`)
+materializes the result at pair position `k`, not generally the result for
+molecule `k`. Use `result.pairs[k]` to identify that pair. In `all_pairs` mode
+these are the generated pairs over `mols`; in `pairs` mode they exactly preserve
+the supplied pair sequence; in `paired_lists` mode item `k` compares `mols[k]`
+with `mols_b[k]`, while `result.pairs[k]` uses the combined-table indices
+`(k, len(mols) + k)`. Each `MCSResult` has `pair`, `num_atoms`, `num_bonds`,
+`canceled`, `atom_mapping`, and `bond_mapping`; the two columns of each mapping
+index the first and second molecule of that result pair, respectively.
-`from nvmolkit.types import HardwareOptions`. Passed via `hardwareOptions=` to `EmbedMolecules`, `MMFFOptimizeMoleculesConfs`, `UFFOptimizeMoleculesConfs`, and the `BatchedForcefield` constructors. Every field has an "auto" sentinel; the defaults are usually fine.
-
-| Field | Type | Default | Meaning |
-|---|---|---|---|
-| `preprocessingThreads` | int | `-1` (all visible CPUs) | CPU threads for preprocessing |
-| `batchSize` | int | `-1` (auto-tuned) | Number of conformers per GPU batch |
-| `batchesPerGpu` | int | `-1` (auto) | Concurrent batches per GPU; must be `>0` or `-1` |
-| `gpuIds` | `list[int]` | `[]` (all visible GPUs) | Specific device ordinals to target |
-
-Passing a `gpuIds` entry for a device that isn't visible raises `RuntimeError: invalid device ordinal`. For finding good values automatically across a representative sample, see `nvmolkit.autotune` (requires the `optuna` extra); each `tune_*` function returns a `TuneResult` whose `best_config` is a fully-populated `HardwareOptions` ready to pass back into the real call.
-
-`HardwareOptions` round-trips through `to_dict()` / `from_dict()` for persisting tuned configs to disk.
-
-### `SubstructSearchConfig` (substructure search)
-
-`from nvmolkit.substructure import SubstructSearchConfig`. Passed via `config=` to `hasSubstructMatch`, `countSubstructMatches`, and `getSubstructMatches`.
-
-| Field | Type | Default | Meaning |
-|---|---|---|---|
-| `batchSize` | int | `1024` | (target, query) pairs per GPU batch |
-| `workerThreads` | int | `-1` (auto) | GPU runner threads per GPU |
-| `preprocessingThreads` | int | `-1` (auto) | CPU threads for preprocessing |
-| `maxMatches` | int | `0` (unlimited) | Max matches returned per (target, query) pair |
-| `uniquify` | bool | `False` | Drop duplicate matches that differ only in atom enumeration order |
-| `gpuIds` | `list[int] \| None` | `None` (current device only) | Specific device ordinals to target |
+## Configuration
-Substructure search currently does not support chirality-aware matching, enhanced stereochemistry, or other advanced RDKit `SubstructMatchParameters` options.
+For ETKDG, forcefield, substructure, or MCS tuning, read the
+[advanced configuration reference](references/advanced-usage.md#configuration).
+It lists configuration fields, defaults, GPU selection, and autotuning APIs.
-## Recipes
+## Examples
### Morgan fingerprints + bulk Tanimoto similarity
@@ -210,7 +208,6 @@ from nvmolkit.embedMolecules import EmbedMolecules
mols = [AddHs(MolFromSmiles(smi)) for smi in ["C1CCCCC1", "C1CCCCC2CCCCC12", "COO"]]
params = ETKDGv3()
-params.useRandomCoords = True
EmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)
@@ -218,7 +215,7 @@ for mol in mols:
print(mol.GetNumConformers())
```
-Inputs are `list[Mol]`, sanitized and with hydrogens added (`AddHs`). Conformers are added in-place. `params.useRandomCoords` must be `True` - nvMolKit's ETKDG only supports random-coord initialization. A handful of niche `EmbedParameters` options are not supported (bounds matrices, custom CPCI, coord maps, separate-fragment embedding); the Features section of the docs site lists the full restrictions.
+Inputs are sanitized `list[Mol]` with hydrogens added (`AddHs`). Conformers are added in-place; see Limitations for unsupported embedding options.
### MMFF94 minimization of a batch of conformers
@@ -229,7 +226,7 @@ from nvmolkit.embedMolecules import EmbedMolecules
from nvmolkit.mmffOptimization import MMFFOptimizeMoleculesConfs
mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCN", "c1ccccc1"]]
-params = ETKDGv3(); params.useRandomCoords = True
+params = ETKDGv3()
EmbedMolecules(mols, params, confsPerMolecule=5)
energies = MMFFOptimizeMoleculesConfs(mols, maxIters=500)
@@ -239,6 +236,12 @@ for mol, mol_energies in zip(mols, energies):
Inputs are `list[Mol]` with conformers already populated (typically by ETKDG, RDKit's `EmbedMultipleConfs`, or a prior nvMolKit call). Coordinates are updated in place; the return is `list[list[float]]` of optimized energies aligned with the input molecule order and conformer index. UFF is identical in shape: swap in `from nvmolkit.uffOptimization import UFFOptimizeMoleculesConfs`.
+BFGS is the default minimizer. To use FIRE, pass `minimizerKind="FIRE"`;
+optionally customize it with a
+`nvmolkit.types.FireOptions` instance through `fireOptions=`. The one-shot MMFF
+and UFF functions and both batched-forcefield `.minimize()` methods accept the
+same selector.
+
If any input molecule is `None` or lacks MMFF/UFF atom types, the call raises `ValueError`. The exception's `args[1]` is a dict with keys `"none"` and `"no_params"` listing the offending indices - useful for filtering a noisy input set.
### Conformer RMSD and Butina clustering
@@ -247,7 +250,7 @@ If any input molecule is `None` or lacks MMFF/UFF atom types, the call raises `V
import torch
from rdkit import Chem
from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
-from nvmolkit.clustering import butina
+from nvmolkit.clustering import OutputMode, butina
from nvmolkit.conformerRmsd import GetConformerRMSMatrixBatch
mols = [Chem.AddHs(Chem.MolFromSmiles(smi)) for smi in ["CCCCCC", "c1ccccc1"]]
@@ -262,52 +265,91 @@ condensed = GetConformerRMSMatrixBatch(heavy_mols)
# Butina expects a square distance matrix, so request square GPU tensors.
square = GetConformerRMSMatrixBatch(heavy_mols, output_format="square")
-clusters = [butina(distance_matrix, cutoff=0.5).torch() for distance_matrix in square]
+results = [
+ butina(distance_matrix, cutoff=0.5, output=OutputMode.DEVICE)
+ for distance_matrix in square
+]
torch.cuda.synchronize()
-for mol_clusters in clusters:
- print(mol_clusters.cpu().tolist())
+for result in results:
+ print(result.cluster_ids.torch().cpu().tolist())
```
-`GetConformerRMSMatrix(mol)` and `GetConformerRMSMatrixBatch(mols)` default to `output_format="condensed"`, returning `AsyncGpuResult` objects that wrap RDKit-style flat vectors of length `N * (N - 1) // 2`. Use `output_format="square"` when chaining into `butina()` or any other API that expects an `N x N` distance matrix. Both forms live on the GPU; call `.numpy()` on condensed results or synchronize before moving square tensors to the CPU.
+Both Butina functions return GPU-resident results by default:
-### Custom forcefield options + constraints (`BatchedForcefield`)
+- The default, `output=OutputMode.DEVICE`, returns cluster IDs, centroids, and sizes.
+- `output=OutputMode.RDKIT` returns RDKit cluster tuples on the host. The first element of each cluster is its centroid.
+
+The device output fields are `AsyncGpuResult` objects. Use `.torch()` to access
+their CUDA tensors without a host copy or `.numpy()` to synchronize and copy a
+field to the host.
-Reach for `MMFFBatchedForcefield` / `UFFBatchedForcefield` instead of the one-shot `MMFFOptimizeMoleculesConfs` / `UFFOptimizeMoleculesConfs` when you need any of:
+`GetConformerRMSMatrix(mol)` and `GetConformerRMSMatrixBatch(mols)` default to `output_format="condensed"`, returning `AsyncGpuResult` objects that wrap RDKit-style flat vectors of length `N * (N - 1) // 2`. Use `output_format="square"` when chaining into `butina()` or any other API that expects an `N x N` distance matrix. Both forms live on the GPU; call `.numpy()` on condensed results or synchronize before moving square tensors to the CPU.
-- Custom `maxIters` / `forceTol` per call
-- Per-molecule `nonBondedThreshold` (MMFF) or `vdwThreshold` (UFF), or per-molecule `ignoreInterfragInteractions`
-- Per-molecule `MMFFMolProperties` objects (e.g. MMFF94s vs MMFF94)
-- Distance, position, angle, or torsion constraints
-- Standalone `compute_energy()` / `compute_gradients()` without minimization
+### Atom-Atom Path similarity and directed sphere exclusion clustering
+
+Atom-Atom Path (AAP) similarity with directed sphere exclusion (DISE)
+clustering provides device and RDKit-style output modes:
```python
-from rdkit.Chem import AddHs, MolFromSmiles
-from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
-from nvmolkit.batchedForcefield import MMFFBatchedForcefield
+from rdkit import Chem
+from nvmolkit.clustering import OutputMode, fused_dise
-mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCCCCC"]]
-for mol in mols:
- EmbedMultipleConfs(mol, numConfs=5)
+molecules = [Chem.MolFromSmiles(smiles) for smiles in ["CCCC", "CCCO", "CCOC"]]
+device_result = fused_dise(molecules, 1 - 0.217, metric="aap")
+rdkit_clusters = fused_dise(molecules, 1 - 0.217, metric="aap", output=OutputMode.RDKIT)
+```
+
+`device_result` has `cluster_ids`, `centroids`, and `cluster_sizes` fields;
+cluster IDs are zero-based and contiguous. `OutputMode.RDKIT` describes
+the centroid-first RDKit cluster representation, not an RDKit implementation
+of the AAP+DISE algorithm. The current DISE control loop synchronizes before
+returning either mode; `DEVICE` describes the stable schema and where the
+result resides, not asynchronous execution of the overall call.
-ff = MMFFBatchedForcefield(
- mols,
- nonBondedThreshold=[100.0, 20.0],
- ignoreInterfragInteractions=True,
-)
+### Maximum common substructure search
-ff[0].add_position_constraint(0, max_displ=0.1, force_constant=50.0)
-ff[1].add_distance_constraint(0, 4, relative=False, min_len=1.8, max_len=2.2, force_constant=25.0)
+```python
+from rdkit import Chem
+from nvmolkit.mcs import findMCS
+
+mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "CCN", "c1ccccc1O"]]
+result = findMCS(mols, mode="pairs", pairs=[(0, 1), (0, 2)])
-energies, converged = ff.minimize(maxIters=500, forceTol=1e-4)
-for mol, mol_energies, mol_converged in zip(mols, energies, converged):
- print(mol.GetNumConformers(), mol_energies, mol_converged)
+for pair_idx, pair in enumerate(result.pairs):
+ item = result[pair_idx]
+ print(pair, item.num_atoms, item.num_bonds, item.atom_mapping)
```
-All conformers of each input molecule are minimized in one batch. Constraints attached via `ff[i].add_*_constraint(...)` apply to every conformer of molecule `i`; constraint setters mark the wrapper dirty and the native forcefield rebuilds on the next call. Pass `output=CoordinateOutput.DEVICE` to `.minimize(...)` to keep optimized coordinates on the GPU (`Device3DResult`) instead of writing them back into RDKit conformers. UFF is the same shape: `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`.
+The default `mode="all_pairs"` generates the upper triangle including the
+diagonal. `mode="pairs"` preserves an explicit pair list exactly, including
+duplicates and reversed pairs. `mode="paired_lists"` zips `mols` with an
+equally sized `mols_b`. Timeouts are per pair; inspect `item.canceled` because a
+timed-out result can contain the best partial MCS found.
+
+Matching options include `atom_compare`, `bond_compare`, valence/formal-charge
+matching, and atom/bond ring-only matching. Unsupported RDKit fMCS options
+raise instead of silently changing semantics. For repeated representative
+explicit-pair workloads, `nvmolkit.autotune.tune_mcs` returns a `TuneResult`.
+Its `best_config` is the tuned `MCSConfig` to pass to
+`findMCS(..., config=result.best_config)`.
+
+### Custom forcefield options + constraints (`BatchedForcefield`)
+
+For per-molecule forcefield settings, geometric constraints, or separate
+energy and gradient calls, read the
+[advanced forcefield recipe](references/advanced-usage.md#custom-forcefield-options-and-constraints).
+
+## Troubleshooting
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `torch.cuda.is_available()` is false | GPU access, driver compatibility, or the torch CUDA build is missing | Check the GPU and driver, then follow the installation guidance above to select a compatible torch build. |
+| `RuntimeError: invalid device ordinal` | A requested `gpuIds` entry is not visible | Use device indices below `torch.cuda.device_count()` or the API's documented GPU defaults. |
+| An RDKit option is rejected | The option is unsupported by that nvMolKit API | Use supported options only if they preserve the requested behavior; otherwise use RDKit for that operation. |
## Going deeper
- Full feature list, API reference, and guides:
- What changed in each release:
-- Worked examples (Jupyter notebooks): the `examples/` directory in the GitHub repo
+- Worked examples (Jupyter notebooks): the [examples/ directory](https://github.com/NVIDIA-BioNeMo/nvMolKit/tree/main/examples) in the GitHub repo
diff --git a/library-skills/nvmolkit-usage/evals/evals.json b/library-skills/nvmolkit-usage/evals/evals.json
index ad04d2a9..ab199632 100644
--- a/library-skills/nvmolkit-usage/evals/evals.json
+++ b/library-skills/nvmolkit-usage/evals/evals.json
@@ -55,7 +55,7 @@
"expected_output": "The agent provides a complete nvMolKit port using batched embedding, batched MMFF optimization, and the batch conformer RMSD API, with nvMolKit-compatible ETKDG parameters and safe result handling.",
"assertions": [
"The agent creates explicit-hydrogen RDKit molecules with Chem.AddHs before embedding",
- "The agent creates ETKDGv3 parameters and sets useRandomCoords = True as required by nvMolKit",
+ "The agent creates ETKDGv3 parameters without setting useRandomCoords",
"The agent calls nvmolkit.embedMolecules.EmbedMolecules once on the molecule collection with confsPerMolecule=20",
"The agent calls MMFFOptimizeMoleculesConfs once on the molecule collection with maxIters=500 instead of retaining the RDKit per-molecule optimization loop",
"The agent calls GetConformerRMSMatrixBatch on the heavy-atom molecule collection",
@@ -102,7 +102,7 @@
"expected_output": "The agent writes a complete batch-oriented nvMolKit conformer workflow using compatible ETKDG parameters, batched MMFF and RMSD calls, invalid-molecule handling, and structured summaries.",
"assertions": [
"The code parses the SMILES and adds explicit hydrogens before ETKDG and MMFF",
- "The code uses ETKDGv3 with useRandomCoords = True",
+ "The code uses ETKDGv3; eigenvalue-based and random-coordinate initialization are both valid",
"The code calls EmbedMolecules once on the valid molecule collection with an explicit positive confsPerMolecule value",
"The code calls MMFFOptimizeMoleculesConfs once on the collection and handles molecules lacking MMFF parameters or reports the indexed ValueError cleanly",
"The code calls GetConformerRMSMatrixBatch on heavy-atom molecules rather than using the single-molecule API as its primary loop",
@@ -143,10 +143,10 @@
},
{
"id": "nvmolkit-usage-010",
- "prompt": "Here is an existing good nvMolKit ETKDG embedding script. Modify it to use nvMolKit autotuning for the HardwareOptions used by EmbedMolecules. Do not run or benchmark it; provide the updated script only.\n\n```python\nfrom pathlib import Path\nimport json\nimport time\n\nimport torch\nfrom rdkit import Chem\nfrom rdkit.Chem import AddHs\nfrom rdkit.Chem.rdDistGeom import ETKDGv3\n\nfrom nvmolkit.embedMolecules import EmbedMolecules\n\nsmiles_path = Path(\"molecules.smi\")\nsmiles = [\n line.split()[0]\n for line in smiles_path.read_text().splitlines()\n if line.strip() and not line.startswith(\"#\")\n]\nmols = [AddHs(Chem.MolFromSmiles(smi)) for smi in smiles]\n\nparams = ETKDGv3()\nparams.useRandomCoords = True\nparams.randomSeed = 0xC0FFEE\n\nstart = time.perf_counter()\nEmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)\ntorch.cuda.synchronize()\nelapsed = time.perf_counter() - start\n\nsummary = {\n \"molecules\": len(mols),\n \"conformers\": sum(mol.GetNumConformers() for mol in mols),\n \"elapsed_seconds\": elapsed,\n}\nPath(\"embedding_summary.json\").write_text(\n json.dumps(summary, indent=2, sort_keys=True)\n)\n```",
+ "prompt": "Here is an existing good nvMolKit ETKDG embedding script. Modify it to use nvMolKit autotuning for the HardwareOptions used by EmbedMolecules. Do not run or benchmark it; provide the updated script only.\n\n```python\nfrom pathlib import Path\nimport json\nimport time\n\nimport torch\nfrom rdkit import Chem\nfrom rdkit.Chem import AddHs\nfrom rdkit.Chem.rdDistGeom import ETKDGv3\n\nfrom nvmolkit.embedMolecules import EmbedMolecules\n\nsmiles_path = Path(\"molecules.smi\")\nsmiles = [\n line.split()[0]\n for line in smiles_path.read_text().splitlines()\n if line.strip() and not line.startswith(\"#\")\n]\nmols = [AddHs(Chem.MolFromSmiles(smi)) for smi in smiles]\n\nparams = ETKDGv3()\nparams.randomSeed = 0xC0FFEE\n\nstart = time.perf_counter()\nEmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)\ntorch.cuda.synchronize()\nelapsed = time.perf_counter() - start\n\nsummary = {\n \"molecules\": len(mols),\n \"conformers\": sum(mol.GetNumConformers() for mol in mols),\n \"elapsed_seconds\": elapsed,\n}\nPath(\"embedding_summary.json\").write_text(\n json.dumps(summary, indent=2, sort_keys=True)\n)\n```",
"expected_output": "The agent preserves the existing workflow, calls the supported tune_embed_molecules API on a representative workload, applies TuneResult.best_config through hardwareOptions= to the full EmbedMolecules call, and retains summary output.",
"assertions": [
- "The updated script preserves SMILES loading, AddHs, ETKDGv3 with useRandomCoords=True, full-workload embedding, and embedding_summary.json output",
+ "The updated script preserves SMILES loading, AddHs, ETKDGv3, full-workload embedding, and embedding_summary.json output",
"The script imports and calls nvmolkit.autotune.tune_embed_molecules or an equivalent supported import of that function",
"The script may tune on a representative subset while keeping the full collection for the production EmbedMolecules call",
"The script reads TuneResult.best_config and passes it to the full EmbedMolecules call via hardwareOptions=",
@@ -168,6 +168,21 @@
],
"expected_skill": "nvmolkit-usage",
"expected_script": null
+ },
+ {
+ "id": "nvmolkit-usage-012",
+ "prompt": "Write nvMolKit code that finds maximum common substructures for the explicit molecule pairs [(0, 1), (2, 3), (0, 2)]. Preserve that pair order, allow any atom and any bond to match, set a 5-second timeout for each pair, and report atom/bond counts plus whether each search timed out.",
+ "expected_output": "The agent constructs RDKit molecules, calls nvmolkit.mcs.findMCS once in explicit-pairs mode, and reads the ordered MCSBatchResult correctly, including each MCSResult's counts and canceled flag.",
+ "assertions": [
+ "The code imports findMCS from nvmolkit.mcs and calls it once for the batch",
+ "The code passes mode='pairs' and the explicit pairs [(0, 1), (2, 3), (0, 2)] without reordering or deduplicating them",
+ "The code uses atom_compare='any', bond_compare='any', and timeout_seconds=5",
+ "The code iterates in result.pairs order and materializes each item with result[pair_idx] or result.get_result(pair_idx)",
+ "The code reports num_atoms, num_bonds, and canceled for every requested pair",
+ "The agent explains that timeout_seconds is a per-pair budget and that a canceled result may contain the best partial MCS found"
+ ],
+ "expected_skill": "nvmolkit-usage",
+ "expected_script": null
}
]
}
diff --git a/library-skills/nvmolkit-usage/evals/trigger_evals.json b/library-skills/nvmolkit-usage/evals/trigger_evals.json
index 7d3760c3..07419470 100644
--- a/library-skills/nvmolkit-usage/evals/trigger_evals.json
+++ b/library-skills/nvmolkit-usage/evals/trigger_evals.json
@@ -18,11 +18,16 @@
},
{
"id": "nvmolkit-usage-trigger-004",
+ "prompt": "Use nvMolKit to find maximum common substructures for a batch of explicit molecule pairs.",
+ "expected": "trigger"
+ },
+ {
+ "id": "nvmolkit-usage-trigger-005",
"prompt": "Write a pandas data cleaning script for a CSV of customers.",
"expected": "no_trigger"
},
{
- "id": "nvmolkit-usage-trigger-005",
+ "id": "nvmolkit-usage-trigger-006",
"prompt": "Use RDKit to calculate one descriptor for a single molecule; I do not have a GPU.",
"expected": "no_trigger"
}
diff --git a/library-skills/nvmolkit-usage/references/advanced-usage.md b/library-skills/nvmolkit-usage/references/advanced-usage.md
new file mode 100644
index 00000000..caff65f2
--- /dev/null
+++ b/library-skills/nvmolkit-usage/references/advanced-usage.md
@@ -0,0 +1,79 @@
+# Advanced nvMolKit usage
+
+## Configuration
+
+Configuration objects expose operation-specific GPU and CPU execution controls.
+
+### `HardwareOptions` (ETKDG, MMFF, UFF)
+
+`from nvmolkit.types import HardwareOptions`. Passed via `hardwareOptions=` to `EmbedMolecules`, `MMFFOptimizeMoleculesConfs`, `UFFOptimizeMoleculesConfs`, and the `BatchedForcefield` constructors. Every field has an "auto" sentinel; the defaults are usually fine.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `preprocessingThreads` | int | `-1` (all visible CPUs) | CPU threads for preprocessing |
+| `batchSize` | int | `-1` (auto-tuned) | Number of conformers per GPU batch |
+| `batchesPerGpu` | int | `-1` (auto) | Concurrent batches per GPU; must be `>0` or `-1` |
+| `gpuIds` | `list[int]` | `[]` (all visible GPUs) | Specific device ordinals to target |
+
+Passing a `gpuIds` entry for a device that isn't visible raises `RuntimeError: invalid device ordinal`. For finding good values automatically across a representative sample, see `nvmolkit.autotune` (requires the `optuna` extra); each `tune_*` function returns a `TuneResult` whose `best_config` is a fully-populated `HardwareOptions` ready to pass back into the real call.
+
+`HardwareOptions` round-trips through `to_dict()` / `from_dict()` for persisting tuned configs to disk.
+
+### `SubstructSearchConfig` (substructure search)
+
+`from nvmolkit.substructure import SubstructSearchConfig`. Passed via `config=` to `hasSubstructMatch`, `countSubstructMatches`, and `getSubstructMatches`.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `batchSize` | int | `1024` | (target, query) pairs per GPU batch |
+| `workerThreads` | int | `-1` (auto) | GPU runner threads per GPU |
+| `preprocessingThreads` | int | `-1` (auto) | CPU threads for preprocessing |
+| `maxMatches` | int | `0` (unlimited) | Max matches returned per (target, query) pair |
+| `uniquify` | bool | `False` | Drop duplicate matches that differ only in atom enumeration order |
+| `gpuIds` | `list[int] \| None` | `None` (current device only) | Specific device ordinals to target |
+
+Substructure search currently does not support chirality-aware matching, enhanced stereochemistry, or other advanced RDKit `SubstructMatchParameters` options.
+
+### `MCSConfig` (maximum common substructure search)
+
+`from nvmolkit.mcs import MCSConfig`. Pass it via `config=` to `findMCS`.
+The fields `batchSize`, `workerThreads`, `preprocessingThreads`,
+`executorsPerRunner`, and `gpuIds` control chunking and dispatch. Defaults
+autoselect execution settings; an empty `gpuIds` list uses the current device.
+`MCSConfig` supports `to_dict()` / `from_dict()` and can also be persisted with
+`nvmolkit.autotune.save()` / `load()`.
+
+## Custom forcefield options and constraints
+
+Reach for `MMFFBatchedForcefield` / `UFFBatchedForcefield` instead of the one-shot `MMFFOptimizeMoleculesConfs` / `UFFOptimizeMoleculesConfs` when you need any of:
+
+- Custom `maxIters` / `forceTol` per call
+- Per-molecule `nonBondedThreshold` (MMFF) or `vdwThreshold` (UFF), or per-molecule `ignoreInterfragInteractions`
+- Per-molecule `MMFFMolProperties` objects (e.g. MMFF94s vs MMFF94)
+- Distance, position, angle, or torsion constraints
+- Standalone `compute_energy()` / `compute_gradients()` without minimization
+
+```python
+from rdkit.Chem import AddHs, MolFromSmiles
+from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
+from nvmolkit.batchedForcefield import MMFFBatchedForcefield
+
+mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCCCCC"]]
+for mol in mols:
+ EmbedMultipleConfs(mol, numConfs=5)
+
+ff = MMFFBatchedForcefield(
+ mols,
+ nonBondedThreshold=[100.0, 20.0],
+ ignoreInterfragInteractions=True,
+)
+
+ff[0].add_position_constraint(0, max_displ=0.1, force_constant=50.0)
+ff[1].add_distance_constraint(0, 4, relative=False, min_len=1.8, max_len=2.2, force_constant=25.0)
+
+energies, converged = ff.minimize(maxIters=500, forceTol=1e-4)
+for mol, mol_energies, mol_converged in zip(mols, energies, converged):
+ print(mol.GetNumConformers(), mol_energies, mol_converged)
+```
+
+All conformers of each input molecule are minimized in one batch. Constraints attached via `ff[i].add_*_constraint(...)` apply to every conformer of molecule `i`; constraint setters mark the wrapper dirty and the native forcefield rebuilds on the next call. Pass `output=CoordinateOutput.DEVICE` to `.minimize(...)` to keep optimized coordinates on the GPU (`Device3DResult`) instead of writing them back into RDKit conformers. UFF is the same shape: `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`.
diff --git a/library-skills/nvmolkit-usage/skill-card.md b/library-skills/nvmolkit-usage/skill-card.md
new file mode 100644
index 00000000..cf39425a
--- /dev/null
+++ b/library-skills/nvmolkit-usage/skill-card.md
@@ -0,0 +1,85 @@
+## Description:
+Use when writing or debugging nvMolKit Python code for GPU-accelerated RDKit fingerprints, similarity, conformers, clustering, and molecular searches.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+Apache-2.0
+## Use Case:
+Developers and computational chemists use this skill to write and debug GPU-accelerated molecular processing code with nvMolKit, including fingerprinting, similarity searches, conformer generation, forcefield optimization, clustering, and substructure/MCS searches.
+
+### Deployment Geography for Use:
+Global
+
+## Requirements / Dependencies:
+**Requires API Key or External Credential:** [Not Specified]
+**Credential Type(s):** [None identified]
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+## Known Risks and Mitigations:
+Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills.
+Mitigation: Review and scan skill before deployment.
+
+## Reference(s):
+- [Advanced Usage Reference](references/advanced-usage.md)
+- [NVIDIA nvMolKit Documentation](https://nvidia-bionemo.github.io/nvMolKit/)
+- [nvMolKit Changelog](https://nvidia-bionemo.github.io/nvMolKit/changelog.html)
+- [nvMolKit Examples (Jupyter notebooks)](https://github.com/NVIDIA-BioNeMo/nvMolKit/tree/main/examples)
+
+
+## Skill Output:
+**Output Type(s):** [Code, Configuration instructions, Analysis]
+**Output Format:** [Markdown with inline Python code blocks]
+**Output Parameters:** [1D]
+**Other Properties Related to Output:** [None]
+
+## Evaluation Agents Used:
+- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`)
+- Codex (`openai/openai/gpt-5.5`)
+
+
+
+## Evaluation Tasks:
+12 evaluation tasks (12 positive), each with 3 attempts per task in isolated sandbox pods.
+
+## Evaluation Metrics Used:
+Reported benchmark dimensions:
+- Security: Is it safe to use? Checks for unsafe operations, secret leakage, and unauthorized access.
+- Correctness: Is the answer correct? Verifies final-answer correctness against the reference answer.
+- Discoverability: Was the right skill loaded when needed? Checks whether the expected skill was selected and the workflow executed.
+- Effectiveness: Did the skill help complete the task? Equal-weight mean of goal completion and expected workflow adherence.
+- Efficiency: Did it avoid wasted tool calls and token usage? 50% tool-call productivity and 50% token efficiency.
+
+Underlying evaluation signals used in this run:
+- `security`: Unsafe operations, secret leakage, and unauthorized access.
+- `accuracy`: Final-answer correctness against the reference answer.
+- `skill_execution`: Whether the expected skill was selected, decoys were avoided, and the workflow executed.
+- `goal_accuracy`: Whether the user's goal was achieved.
+- `behavior_check`: Whether the expected workflow behavior was followed.
+- `skill_efficiency`: Tool-call productivity (routing scored under Discoverability).
+- `token_efficiency`: Actual uncached prompt plus completion usage.
+
+
+
+## Evaluation Results:
+| Measure | Claude Code (Baseline → Skill Uplift) | Codex (Baseline → Skill Uplift) |
+|---|---:|---:|
+| Overall | 91.1% | 92.3% |
+| Security | 66.7% → 91.7% (+25.0 pts) | 100.0% → 100.0% (±0.0 pts) |
+| Correctness | 95.0% → 100.0% (+5.0 pts) | 96.7% → 96.7% (±0.0 pts) |
+| Discoverability | 91.7% | 95.0% |
+| Effectiveness | 91.4% → 92.6% (+1.2 pts) | 82.9% → 85.4% (+2.5 pts) |
+| Efficiency | 79.5% | 84.6% |
+
+## Skill Version(s):
+0.6.0 (source: pyproject.toml, CHANGELOG, released 2026-08-13)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail).
diff --git a/library-skills/nvmolkit-usage/skill.oms.sig b/library-skills/nvmolkit-usage/skill.oms.sig
new file mode 100644
index 00000000..71168c6d
--- /dev/null
+++ b/library-skills/nvmolkit-usage/skill.oms.sig
@@ -0,0 +1 @@
+{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{"x509CertificateChain":{"certificates":[{"rawBytes":"MIICgzCCAgmgAwIBAgIUKIyS7SxNteQIiWzK1dWj85E6520wCgYIKoZIzj0EAwMwVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwHhcNMjYwNDAxMDAwMDAwWhcNMjgwNDIyMTUzMzA5WjBUMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTlZJRElBIENvcnBvcmF0aW9uMSgwJgYDVQQDDB9OVklESUEgQWdlbnQgU2tpbGxzIFNpZ25pbmcgMDAxMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEYoRM9bQl/dGlwSRNi6bTpIJUXH8Nv9GciP6LSflJYYMLCc296kpyuTSsk5ddbAWiDcFX3C/ydX3jwc+qCLYP6uHy9XphyLjOQ27Yb2J6rBLVtRBS1mgGco/Gr7fL6ODco4GaMIGXMB0GA1UdDgQWBBRQ/5ZW3nJ6lmo9SVk7I15o7UGmpTAfBgNVHSMEGDAWgBRPGpILxMBBleJSsBGjrMKsby1CgjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUHMAGGG2h0dHA6Ly9vY3NwLm5kaXMubnZpZGlhLmNvbTAKBggqhkjOPQQDAwNoADBlAjAUygu/GiOCIXrgGr4SmLgeEVDcEitfFUv7ALbvLVGVyMysB3mxmO/uInZfXzWcJZsCMQDxuoxj4ZmO30jhkPIcCxGFCOvnUsnfU3TfGcouYm4M6iRpbKvtVnHPiy4bi6pcKf0="},{"rawBytes":"MIICiDCCAg6gAwIBAgIUZsIuSv9NkpJCNqtYEfCouVv5BzowCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAASI72cR3ctKGg4VWnB3bNja6g1Z2PnOmFEopkPof+QeIcPk9rT+g9MjJnq51EQXL93a7C2GJ9J985G4o2V85VD7wJ1RaXhluHW2rf3y8bQGeAYaKMr5s/hUgn+M3/9WlWejgaAwgZ0wHQYDVR0OBBYEFE8akgvEwEGV4lKwEaOswqxvLUKCMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AubmRpcy5udmlkaWEuY29tMAoGCCqGSM49BAMDA2gAMGUCMQCeIMMfAbyzPDacw2MxG+Yt1cikrJX/DVxiGfXuHmkkXn6VgSzE79+lkqDErpVO2gYCMCNEColOyvUvkzZGUEI1hQ3PfMgi3FIo9tHoBKMw4/wGBLFpu/0ubtmbBXM6/UMOEw=="},{"rawBytes":"MIICRTCCAcygAwIBAgIUeJdY3rV86EdvFmG7L8LJBsyQFYkwCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABAYpiXCDjJ9NT2eSDhyHJVSw1Tbze18cGG2F/578oWvHxg23eQAhNRYdq88i1iOshZSO6C29doKui5Xpmo/7Ctw9Sx4PP2RzOmIuOLCuTdNtKcTRwi4GEsd5BAFvWj42M6NjMGEwHQYDVR0OBBYEFItnoAjjfuCEUvzyvWyI2vOGvwPjMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2cAMGQCMCwtAjWLaNwgGWNCgdyNoTyvNhqWRECRJV2r3+7w8g0PL6NHLOsbkgE09BH95h8XlgIwTaQmbbUh2ChAJ5TA1wRiVDnCcvbzHlZl2jM2FcwQQZlk19LOAbyGMRixbu2Ww/rj"}]},"tlogEntries":[]},"dsseEnvelope":{"payload":"ewogICJfdHlwZSI6ICJodHRwczovL2luLXRvdG8uaW8vU3RhdGVtZW50L3YxIiwKICAic3ViamVjdCI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAibnZtb2xraXQtdXNhZ2UiLAogICAgICAiZGlnZXN0IjogewogICAgICAgICJzaGEyNTYiOiAiNzI0OWNmYWVlZTY4NmRiMTMwYzYxMzM5ZTkyMDJlNTZhYTEwY2Q2MGRkMDBhMDVhZDA5MDhhZTFiNzJmMDM1MiIKICAgICAgfQogICAgfQogIF0sCiAgInByZWRpY2F0ZVR5cGUiOiAiaHR0cHM6Ly9tb2RlbF9zaWduaW5nL3NpZ25hdHVyZS92MS4wIiwKICAicHJlZGljYXRlIjogewogICAgInJlc291cmNlcyI6IFsKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImRmZGE0MjVkOTVkOTAzMThjYjRkNDE2OTFkOWMzNzdjOTdlM2IyYmYxNWVkYmZmMWEzMTNmZmQ0OGVmNDM5YTIiLAogICAgICAgICJuYW1lIjogIkJFTkNITUFSSy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI3ZTAxNWMzODE2OGUwNDlhZmRhOWNhNjk1MzdmMzAyNzBkNGUxZmU0ZmVhMzEwNzdiMmQ3NGM1YjU0Njk4YjYiLAogICAgICAgICJuYW1lIjogIlNLSUxMLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZTkyOGJhYzkyYmYyYTI4NzFlZWM2MTViNGRhM2EwMGJkYzMyYzAxOGNkZmIyNjY3MmY4MmUwNDY3ZGNiMGVmYSIsCiAgICAgICAgIm5hbWUiOiAiZXZhbHMvZXZhbHMuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjZhOTc3N2JmMDdiNGU4OTY3ZWRkOTA1Y2U2OTdlYWU5Mzk2OTRjOWM2NGQxMzU4MDdkOTA4ZTk4MGFjNmRmYjIiLAogICAgICAgICJuYW1lIjogImV2YWxzL3RyaWdnZXJfZXZhbHMuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjFmNGQ2NDY1NTk2OGEzODk2ODVkODc0ZDIzMzJkZmVhYzQ1NmE4MDUwMjM0ZDc1YjdhNjdmYTYzN2UyYmE4ODMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvYWR2YW5jZWQtdXNhZ2UubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI0N2JhZDAxZjJjZmJhMzcyNWRkOWM1MTkwNjA0MjQwZDc0Y2JmM2E2MzYyYTQxMTEyOTI2ZTY0MTIyNmNlNDhkIiwKICAgICAgICAibmFtZSI6ICJza2lsbC1jYXJkLm1kIgogICAgICB9CiAgICBdLAogICAgInNlcmlhbGl6YXRpb24iOiB7CiAgICAgICJhbGxvd19zeW1saW5rcyI6IGZhbHNlLAogICAgICAiaWdub3JlX3BhdGhzIjogWwogICAgICAgICIuZ2l0YXR0cmlidXRlcyIsCiAgICAgICAgIi5naXRodWIiLAogICAgICAgICIuZ2l0IiwKICAgICAgICAiLmdpdGlnbm9yZSIKICAgICAgXSwKICAgICAgIm1ldGhvZCI6ICJmaWxlcyIsCiAgICAgICJoYXNoX3R5cGUiOiAic2hhMjU2IgogICAgfQogIH0KfQ==","payloadType":"application/vnd.in-toto+json","signatures":[{"sig":"MGUCMQDfpMi+T0t6KQkNTs7Crz+IJ299imJWiG0a2ZnEr7HnOWliiHEVH2cL7wArl8utCvYCMHFk1IE0KG4jYUyKFa4IQADs1ta/tx+OVS5NSuGN6Ssev06qjHBD5faeFXW2IBNZDA==","keyid":""}]}}
\ No newline at end of file
diff --git a/open-models-skills/kermt/kermt-add-cmim-pretrain/skill-card.md b/open-models-skills/kermt/kermt-add-cmim-pretrain/skill-card.md
new file mode 100644
index 00000000..c25a6984
--- /dev/null
+++ b/open-models-skills/kermt/kermt-add-cmim-pretrain/skill-card.md
@@ -0,0 +1,77 @@
+## Description:
+Converts a grover_base checkpoint into a hybrid checkpoint by adding a randomly-initialized cMIM decoder and latent distribution, then continues pretraining on the user's corpus in hybrid (vocab + contrast) mode.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML research engineers who want the cMIM contrastive objective on top of an existing grover_base KERMT checkpoint without retraining from scratch. Functionally `kermt-continue-pretrain` with a one-time checkpoint-conversion step prepended.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU (multi-GPU supported via DDP)
+* A grover_base checkpoint (encoder-only, or encoder + vocab heads)
+* A pretraining corpus CSV
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: The newly added cMIM decoder and latent distribution are randomly initialized, so the converted checkpoint performs worse than its source until sufficient hybrid pretraining has run — a checkpoint taken too early is silently degraded.
+Mitigation: The conversion step is explicitly separated from the training step, and `kermt-monitor` exposes validation loss so users can confirm convergence before adopting the result.
+
+Risk: Continued pretraining is a long-running, multi-GPU workload that a single agent instruction can start, potentially consuming days of GPU time.
+Mitigation: Runs launch detached with a run manifest; `kermt-monitor` provides progress visibility and the container identifiers needed to terminate early.
+
+Risk: Supplying a checkpoint that is not grover_base (e.g. already cmim or hybrid) would produce an invalid conversion.
+Mitigation: The skill validates the source checkpoint type before conversion.
+
+Risk: Conversion and data preparation write new checkpoint and shard/vocab/feature artifacts that can overwrite prior output.
+Mitigation: Artifacts are written under an explicit run/output path; the source checkpoint is not modified in place.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/run_pretrain_local.py` — extended usage examples
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-continue-pretrain`, `kermt-pretrain-scratch`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Converted hybrid checkpoint; subsequent training checkpoints; shard/vocab/feature artifacts; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, converted checkpoint path, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering source-checkpoint validation, cMIM conversion, corpus preparation, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models produced by this skill inherit the composition and biases of the user's pretraining corpus. Downstream predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-continue-pretrain/skill-card.md b/open-models-skills/kermt/kermt-continue-pretrain/skill-card.md
new file mode 100644
index 00000000..50489db5
--- /dev/null
+++ b/open-models-skills/kermt/kermt-continue-pretrain/skill-card.md
@@ -0,0 +1,77 @@
+## Description:
+Continues pretraining from an existing KERMT checkpoint — validating the checkpoint and corpus, preparing shard/vocab/feature artifacts, and launching `pretrain_ddp.py` inside the KERMT container with `--pretrain_mode` auto-dispatched from the checkpoint type.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML engineers adapting a KERMT foundation model to a domain-specific molecular corpus — for example an in-house compound collection — before task finetuning, without discarding the representations already learned.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU (multi-GPU supported via DDP)
+* An existing KERMT checkpoint (grover_base vocab-only, cmim, or hybrid)
+* A pretraining corpus CSV
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Continued pretraining is a long-running, multi-GPU workload that a single agent instruction can start, potentially consuming days of GPU time and substantial cloud spend.
+Mitigation: Runs launch detached with a run manifest; `kermt-monitor` provides progress visibility and the container identifiers needed to terminate early.
+
+Risk: Selecting the wrong `--pretrain_mode` for a checkpoint would train against the wrong objective and silently waste the entire run.
+Mitigation: The skill auto-dispatches `--pretrain_mode` from the detected checkpoint type rather than relying on the user to specify it.
+
+Risk: Data preparation writes shard, vocabulary, and feature artifacts that can be large and can overwrite prior preparation output.
+Mitigation: Preparation writes under an explicit run/output path supplied by the user.
+
+Risk: Continued pretraining on a narrow corpus can degrade general-purpose representations (catastrophic forgetting) in ways not visible until downstream finetuning.
+Mitigation: The original checkpoint is not modified in place; users should retain it and compare downstream task performance before adopting the continued-pretrain checkpoint.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/run_pretrain_local.py` — extended usage examples
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-pretrain-scratch`, `kermt-add-cmim-pretrain`, `kermt-finetune`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Model checkpoint files; shard/vocab/feature artifacts; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, resolved pretrain mode, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+5 evaluation tasks defined in `evals/evals.json`, covering checkpoint validation, corpus validation, data preparation, pretrain-mode dispatch, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models produced by this skill inherit the composition and biases of the user's pretraining corpus. Downstream predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-embed/skill-card.md b/open-models-skills/kermt/kermt-embed/skill-card.md
new file mode 100644
index 00000000..38be64d7
--- /dev/null
+++ b/open-models-skills/kermt/kermt-embed/skill-card.md
@@ -0,0 +1,69 @@
+## Description:
+Extracts per-molecule embeddings from any encoder-bearing KERMT checkpoint (grover_base / cmim / hybrid / finetuned), writing one `.npy` per readout type plus `canonical_smiles.npy` and `validity.npy`.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML engineers and cheminformaticians who need fixed-length molecular representations from a KERMT encoder to feed a downstream model, clustering step, or similarity search, without training a task head.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU
+* Any encoder-bearing KERMT checkpoint
+* A SMILES input CSV (featurization happens on the fly — no precomputed features required)
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Embeddings from different checkpoints or readout types are not comparable, and mixing them in a downstream model produces silently meaningless results.
+Mitigation: The skill writes each readout type to a separately named `.npy` and emits `canonical_smiles.npy` alongside, so provenance and row alignment are explicit.
+
+Risk: Invalid SMILES rows would misalign embeddings against the caller's original input ordering.
+Mitigation: The skill emits `validity.npy`, letting the caller filter or realign rows deterministically.
+
+Risk: Large input libraries can produce embedding arrays of substantial size and consume significant disk.
+Mitigation: Outputs are written to a user-specified directory; users should size storage for the molecule count and embedding dimensionality before running.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `task/extract_embeddings.py` — the underlying extraction entry point
+- Related skills: `kermt-setup`, `kermt-finetune`, `kermt-infer`
+
+## Skill Output:
+**Output Type(s):** [Files]
+**Output Format:** [NumPy `.npy` arrays — one per readout type (atom_from_atom, bond_from_atom, atom_from_bond, bond_from_bond), plus `canonical_smiles.npy` and `validity.npy`]
+**Output Parameters:** [2D — one row per input molecule, one column per embedding dimension]
+**Other Properties Related to Output:** [Row order corresponds to the input CSV; `validity.npy` identifies rows whose SMILES failed to parse]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+5 evaluation tasks defined in `evals/evals.json`, covering checkpoint compatibility, readout selection, and output artifact production.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-finetune/skill-card.md b/open-models-skills/kermt/kermt-finetune/skill-card.md
new file mode 100644
index 00000000..a9db2f87
--- /dev/null
+++ b/open-models-skills/kermt/kermt-finetune/skill-card.md
@@ -0,0 +1,78 @@
+## Description:
+Finetunes a pretrained KERMT encoder on a labeled CSV — validating the input checkpoint and dataset, preparing features and optional splits, then launching `main.py finetune` inside the KERMT container as a detached, hours-scale run.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+Computational chemists and ML engineers adapting a pretrained KERMT encoder (grover_base / cmim / hybrid) to their own labeled molecular property dataset — for example an in-house ADMET assay panel — before running predictions with `kermt-infer`.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU
+* A pretrain checkpoint (grover_base, cmim, or hybrid)
+* A labeled CSV with SMILES and one or more target columns
+* Hyperparameters default from `agent/config/defaults_finetune.json`, overridable per flag
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Finetuning is an hours-scale GPU workload that a single agent instruction can start, consuming substantial GPU-hours or cloud spend.
+Mitigation: Runs launch detached with a run manifest, and `kermt-monitor` gives the user continuous visibility and the container identifiers needed to terminate early.
+
+Risk: Supplying a finetuned checkpoint instead of a pretrain checkpoint would produce an invalid training configuration.
+Mitigation: The skill validates the checkpoint type before launching and rejects non-pretrain checkpoints.
+
+Risk: A poorly split dataset (e.g. random splits on congeneric series) yields optimistic validation metrics that do not generalize.
+Mitigation: The skill exposes explicit split handling rather than defaulting silently; users remain responsible for choosing a split strategy appropriate to their chemistry.
+
+Risk: Training writes checkpoints and logs into a user-specified directory and can overwrite artifacts from a previous run.
+Mitigation: Outputs are written under an explicit run directory; users should use distinct output paths per experiment.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`; users should confirm their data-handling policy before enabling it.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/config/defaults_finetune.json` — default hyperparameters
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-infer`, `kermt-embed`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Model checkpoint files; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, configured hyperparameters, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes. Use `kermt-monitor` for progress.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+5 evaluation tasks defined in `evals/evals.json`, covering checkpoint validation, dataset validation, data preparation, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models finetuned with this skill inherit the biases and coverage limits of the user's training data. Resulting predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-infer/skill-card.md b/open-models-skills/kermt/kermt-infer/skill-card.md
new file mode 100644
index 00000000..443f191e
--- /dev/null
+++ b/open-models-skills/kermt/kermt-infer/skill-card.md
@@ -0,0 +1,74 @@
+## Description:
+Runs molecular property predictions with a finetuned KERMT checkpoint on a SMILES-only CSV, validating that the checkpoint carries task FFN heads, preparing rdkit_2d features, and launching `main.py predict` inside the KERMT container.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+Computational chemists and drug-discovery teams scoring a library of candidate molecules for ADMET or other molecular properties using a KERMT model they have already finetuned. Not for use with pretrain checkpoints — the skill refuses those and redirects to `kermt-finetune`.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU
+* A finetuned KERMT checkpoint containing task FFN heads
+* A SMILES-only input CSV
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Predictions are computational estimates and may be applied outside the chemical space the model was finetuned on, producing confidently wrong property values for novel scaffolds.
+Mitigation: Users must treat outputs as hypotheses requiring experimental validation, and should check that input chemistry resembles the finetuning set before acting on predictions.
+
+Risk: Supplying a pretrain checkpoint instead of a finetuned one would yield meaningless outputs.
+Mitigation: The skill validates the checkpoint for task FFN heads before running and refuses pretrain checkpoints with an explicit redirect to `kermt-finetune`.
+
+Risk: Malformed or non-parseable SMILES silently reduce the effective prediction set.
+Mitigation: The skill runs a data-preparation and cleaning step that reports invalid rows before inference.
+
+Risk: The skill writes prediction outputs into a user-specified directory and can overwrite prior results.
+Mitigation: Outputs are written under an explicit output path supplied by the user; no files outside that path are modified.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- [RDKit documentation](https://www.rdkit.org/docs/) — `rdkit_2d` descriptor featurization
+- Related skills: `kermt-finetune` (produces the required checkpoint), `kermt-embed`
+
+## Skill Output:
+**Output Type(s):** [Analysis, Files]
+**Output Format:** [CSV of per-molecule predictions; Markdown summary]
+**Output Parameters:** [2D — one row per input molecule, one column per predicted task]
+**Other Properties Related to Output:** [Predictions are model estimates, not measurements, and are not calibrated probabilities of experimental outcome. Runs blocking, on a minutes-scale timeframe.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering checkpoint validation, CSV validation, feature preparation, and the predict invocation.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Molecular property predictions produced by this skill are computational hypotheses for research and development workflows. They must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-monitor/skill-card.md b/open-models-skills/kermt/kermt-monitor/skill-card.md
new file mode 100644
index 00000000..84e12f12
--- /dev/null
+++ b/open-models-skills/kermt/kermt-monitor/skill-card.md
@@ -0,0 +1,70 @@
+## Description:
+Reports progress for a detached KERMT run by reading `run.json`, querying Docker for container state, tailing the pretrain/finetune log, and parsing progress lines (epoch, step, validation loss).
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML engineers running long KERMT pretraining or finetuning jobs who need to check status, spot divergence early, and decide whether to let a run continue or terminate it. This is the companion skill to every detached `kermt-*` training invocation.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* Docker
+* `jq`
+* A prior detached KERMT run that produced a `run.json`
+
+Note: unlike the training skills, this skill does not require a GPU.
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: A stale or missing `run.json` can cause the skill to report on the wrong run, or to report nothing while a job is in fact still consuming GPU-hours.
+Mitigation: The skill cross-checks `run.json` against live Docker container state rather than trusting the manifest alone.
+
+Risk: Log tailing surfaces run output into the agent transcript, which may include file paths or environment details.
+Mitigation: The skill reads only the pretrain/finetune log; users should treat agent transcripts as sensitive and avoid pasting credentials into run configuration.
+
+Risk: This skill is read-only and cannot stop a runaway job, so a user may assume monitoring implies control.
+Mitigation: The skill reports container identifiers so the user can terminate the run directly via Docker if needed.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/kermt_container.sh` — defines `kermt_run_detached`, the wrapper whose runs this skill observes
+- Related skills: `kermt-pretrain-scratch`, `kermt-continue-pretrain`, `kermt-finetune`
+
+## Skill Output:
+**Output Type(s):** [Analysis]
+**Output Format:** [Markdown status report]
+**Output Parameters:** [1D — container state, current epoch, current step, latest validation loss]
+**Other Properties Related to Output:** [Read-only; the skill makes no changes to the run or the host]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering run discovery, container-state reporting, and log progress parsing.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-pretrain-scratch/skill-card.md b/open-models-skills/kermt/kermt-pretrain-scratch/skill-card.md
new file mode 100644
index 00000000..46705812
--- /dev/null
+++ b/open-models-skills/kermt/kermt-pretrain-scratch/skill-card.md
@@ -0,0 +1,77 @@
+## Description:
+Pretrains a fresh KERMT model from scratch on a user-provided corpus — building a new vocabulary, instantiating the model architecture from defaults, and launching `pretrain_ddp.py` inside the KERMT container with no starting checkpoint loaded.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML research engineers training a KERMT model from random initialization on a corpus sufficiently large and distinct that continued pretraining from an existing checkpoint is not appropriate. For most users, `kermt-continue-pretrain` is the better starting point.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU (multi-GPU strongly recommended; DDP supported)
+* A large pretraining corpus CSV
+* Substantial disk for shard, vocabulary, and feature artifacts
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: This is the most expensive skill in the KERMT family — training from random initialization can consume days to weeks of multi-GPU time, and a single agent instruction can start it.
+Mitigation: Runs launch detached with a run manifest; `kermt-monitor` provides progress visibility and the container identifiers needed to terminate early. Users should confirm corpus scale justifies from-scratch training before invoking.
+
+Risk: Training from scratch on an insufficiently large corpus produces a model materially worse than the available pretrained checkpoints, with the cost discovered only after the run.
+Mitigation: The skill is documented as the exception path, with `kermt-continue-pretrain` as the recommended default; users should benchmark against an existing checkpoint before committing.
+
+Risk: A vocabulary built from the user's corpus is not interchangeable with vocabularies from other checkpoints, so resulting models are incompatible with checkpoints trained elsewhere.
+Mitigation: The new vocabulary is written alongside the checkpoint in the run directory, making the pairing explicit and auditable.
+
+Risk: Data preparation writes large shard/vocab/feature artifacts and can overwrite prior preparation output.
+Mitigation: Preparation writes under an explicit run/output path supplied by the user.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/run_pretrain_local.py` — extended usage examples
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-continue-pretrain`, `kermt-finetune`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Model checkpoint files; new vocabulary; shard/feature artifacts; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, vocabulary path, model configuration, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering corpus validation, vocabulary construction, architecture instantiation, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models produced by this skill inherit the composition and biases of the user's pretraining corpus entirely, with no counterbalancing from prior pretraining. Downstream predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/kermt/kermt-setup/skill-card.md b/open-models-skills/kermt/kermt-setup/skill-card.md
new file mode 100644
index 00000000..076d3238
--- /dev/null
+++ b/open-models-skills/kermt/kermt-setup/skill-card.md
@@ -0,0 +1,69 @@
+## Description:
+Bootstraps the KERMT agent environment — verifies host Docker and the NVIDIA Container Toolkit, builds the `kermt:latest` image from the repository Dockerfile if absent, and runs a GPU smoke test inside the container.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+Computational chemists and ML engineers preparing a workstation or GPU node to run any `kermt-*` skill. Every other KERMT skill depends on this one; it is the first skill to invoke on a fresh clone.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* Docker
+* NVIDIA Container Toolkit
+* CUDA-capable NVIDIA GPU
+* A local clone of the KERMT repository (supplies the Dockerfile)
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: The skill builds a container image and runs GPU workloads, which consumes significant local disk and can take tens of minutes on a cold cache.
+Mitigation: The skill checks for an existing `kermt:latest` image and skips the build when one is present; the smoke test is short and read-only.
+
+Risk: Docker commands require elevated host privileges, and an agent running them has broad access to the host container runtime.
+Mitigation: The skill issues only build, run, and inspect commands against the KERMT image; users should keep their agent's command-approval gate enabled and review commands before execution.
+
+Risk: A partially configured host (driver/toolkit mismatch) can produce a container that starts but cannot see the GPU, causing confusing downstream failures in training skills.
+Mitigation: The GPU smoke test runs inside the container and fails loudly at setup time rather than deferring the error to a long-running job.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- [NVIDIA Container Toolkit documentation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/)
+- `agent/scripts/kermt_container.sh` — container entry points used by this skill
+
+## Skill Output:
+**Output Type(s):** [Analysis, Configuration instructions]
+**Output Format:** [Markdown status report with inline bash commands]
+**Output Parameters:** [1D — pass/fail status per environment check]
+**Other Properties Related to Output:** [Side effect: builds the `kermt:latest` Docker image on the host if it does not already exist]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering environment verification, image build, and GPU smoke test paths.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/proteina-complexa/complexa-design/SKILL.md b/open-models-skills/proteina-complexa/complexa-design/SKILL.md
index ca3b89f9..bbfd0299 100644
--- a/open-models-skills/proteina-complexa/complexa-design/SKILL.md
+++ b/open-models-skills/proteina-complexa/complexa-design/SKILL.md
@@ -1,17 +1,19 @@
---
name: complexa-design
description: >
- End-to-end Proteina-Complexa design pipeline driver. Use when the user wants to
- "design a binder", "design binders for X", "run complexa design", "de novo
- binder", "PDL1 binder", "TrkA binder", "design proteins for target", "protein
- binder design", "ligand binder", "design a small-molecule binder", "ATP-binding
- protein", "AME motif scaffolding", "scaffold a motif near a ligand", "motif +
- ligand design", "enzyme scaffolding", "flow matching protein design",
- "beam-search binder", "FK steering", "MCTS protein design", or "refold with AF2
- / RF3 / ESMFold", or wants success rates, interface pAE, scRMSD, or FoldSeek
- diversity from one command. Drives the complexa design pipeline from target
- picking to manifest emission and reports how many designs passed.
-compatibility: "complexa CLI installed (pip install -e .); environment file populated; 1x CUDA GPU >=40GB VRAM (A100/H100/L40S); 24 CPUs; ~50GB disk"
+ End-to-end Proteina-Complexa design pipeline driver. Reach for this skill whenever
+ the user wants to "design a binder", "design binders for X", "run complexa
+ design", "de novo binder", "PDL1 binder", "TrkA binder", "design proteins for
+ target", "protein binder design", "ligand binder", "design a small-molecule
+ binder", "ATP-binding protein", "AME motif scaffolding", "scaffold a motif
+ near a ligand", "motif + ligand design", "enzyme scaffolding", "flow matching
+ protein design", "beam-search binder", "FK steering", "MCTS protein design",
+ "refold with AF2", "refold with RF3", or wants success rates, interface pAE,
+ scRMSD, or
+ FoldSeek diversity from a single command. This is the scientific anchor of
+ the skill set: it drives `complexa design ` from target picking to
+ manifest emission and tells the user how many designs passed.
+compatibility: "complexa CLI installed (pip install -e .); .env populated; 1x CUDA GPU >=40GB VRAM (A100/H100/L40S); 24 CPUs; ~50GB disk"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
diff --git a/open-models-skills/proteina-complexa/complexa-design/evals/trigger_evals.json b/open-models-skills/proteina-complexa/complexa-design/evals/trigger_evals.json
deleted file mode 100644
index 0577c82c..00000000
--- a/open-models-skills/proteina-complexa/complexa-design/evals/trigger_evals.json
+++ /dev/null
@@ -1,27 +0,0 @@
-[
- {"query": "Design a binder for my target", "should_trigger": true},
- {"query": "design binders for PDL1", "should_trigger": true},
- {"query": "run complexa design on this target", "should_trigger": true},
- {"query": "de novo binder design", "should_trigger": true},
- {"query": "Design a PDL1 binder", "should_trigger": true},
- {"query": "Design a TrkA binder", "should_trigger": true},
- {"query": "design proteins for target", "should_trigger": true},
- {"query": "protein binder design end to end", "should_trigger": true},
- {"query": "Design a ligand binder for this small molecule", "should_trigger": true},
- {"query": "design a small-molecule binder", "should_trigger": true},
- {"query": "Design an ATP-binding protein", "should_trigger": true},
- {"query": "AME motif scaffolding around a ligand", "should_trigger": true},
- {"query": "scaffold a motif near a ligand", "should_trigger": true},
- {"query": "motif + ligand design", "should_trigger": true},
- {"query": "enzyme scaffolding with complexa", "should_trigger": true},
- {"query": "flow matching protein design", "should_trigger": true},
- {"query": "beam-search binder generation", "should_trigger": true},
- {"query": "use FK steering for the design search", "should_trigger": true},
- {"query": "MCTS protein design", "should_trigger": true},
- {"query": "refold designs with AF2 / RF3 / ESMFold and report success rates", "should_trigger": true},
- {"query": "What's the interface pAE, scRMSD, and FoldSeek diversity of the run?", "should_trigger": true},
- {"query": "Evaluate an existing folder of PDBs I already generated", "should_trigger": false},
- {"query": "Launch the design run on the SLURM cluster", "should_trigger": false},
- {"query": "Register a new target in the targets dict", "should_trigger": false},
- {"query": "How do I compute molecular weight of aspirin?", "should_trigger": false}
-]
diff --git a/open-models-skills/proteina-complexa/complexa-design/skill-card.md b/open-models-skills/proteina-complexa/complexa-design/skill-card.md
new file mode 100644
index 00000000..2242a470
--- /dev/null
+++ b/open-models-skills/proteina-complexa/complexa-design/skill-card.md
@@ -0,0 +1,80 @@
+## Description:
+Drives the end-to-end Proteina-Complexa design pipeline — `complexa design ` from target selection through manifest emission — for protein binder, ligand binder, and AME / motif-scaffolding tasks, and reports how many designs passed.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers and computational biologists running de novo binder design against a registered target — generating candidate binders with reward-guided flow matching, refolding them with an independent structure predictor (AF2 or RF3), and ranking by interface metrics (success rate, interface pAE, scRMSD, FoldSeek diversity). This is the scientific anchor of the `complexa-*` skill set.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* `.env` populated (`complexa-setup`) and a target registered (`complexa-target`)
+* 1× CUDA GPU with ≥40 GB VRAM (A100 / H100 / L40S)
+* 24 CPUs, ~50 GB disk
+* Folding backend weights: AF2 (ColabDesign) or RF3
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Designed binders are computational predictions. Reported success rates, interface pAE, and scRMSD are in-silico metrics that correlate imperfectly with experimental binding; treating them as validated hits wastes wet-lab resources.
+Mitigation: The pipeline refolds designs with a structure predictor independent of the generator and reports pass rates against explicit thresholds rather than a single score. All outputs require experimental validation.
+
+Risk: A full design campaign is a long, GPU-intensive workload that a single agent instruction can start, consuming substantial GPU-hours or cloud spend.
+Mitigation: The skill runs a pre-flight validation step before launching and emits a replayable manifest, so configuration errors surface before the expensive stage.
+
+Risk: Incorrect target or hotspot configuration directs the entire campaign at the wrong surface, with the error invisible until results are inspected.
+Mitigation: The skill validates the target as an explicit pipeline step and refuses to proceed on an invalid target.
+
+Risk: Generation is stochastic — repeated runs with identical inputs produce different binders unless a seed is fixed, which can confound comparisons between configurations.
+Mitigation: The emitted manifest records the run configuration for replay; use `complexa-sweep` for controlled comparisons across configurations.
+
+Risk: The skill writes design outputs and can overwrite results from a previous campaign in the same directory.
+Mitigation: Outputs are written under explicit per-run output paths.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- La-Proteina — the flow-based generative model this work builds on
+- [ColabDesign / AlphaFold2](https://github.com/sokrypton/ColabDesign) and RF3 — independent refolding backends
+- [Foldseek](https://github.com/steineggerlab/foldseek) — structural diversity metric
+- Related skills: `complexa-setup`, `complexa-target`, `complexa-evaluate-pdbs`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [PDB structures of designed binders; result CSV of per-design metrics; replayable JSON manifest; Markdown summary]
+**Output Parameters:** [3D for atomic coordinates; 2D for the per-design metric table; 1D for campaign-level pass rates]
+**Other Properties Related to Output:** [Outputs are computational predictions, not measurements. Confidence and interface metrics are model-reported and are not calibrated probabilities of experimental binding. Generation is stochastic unless seeded.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering pipeline selection, pre-flight validation, design execution, and result collection with manifest emission — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+This skill generates novel protein sequences and structures. Users are responsible for screening designed sequences before synthesis, and for using the skill consistent with applicable biosecurity norms, biosafety review processes, and export-control obligations. Designed binders are research hypotheses and must not be used for clinical decision-making, diagnosis, or treatment selection.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/SKILL.md b/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/SKILL.md
index 1155b10b..57fe7cfa 100644
--- a/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/SKILL.md
+++ b/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/SKILL.md
@@ -1,16 +1,19 @@
---
name: complexa-evaluate-pdbs
description: >
- Standalone evaluation of an existing PDB directory with Proteina-Complexa. Use
- when the user wants to "evaluate PDB files", "re-fold these designs", "compute
- interface pAE", "compute i_pLDDT for a folder", "run AF2 / RF3 / ESMFold on my
- designs", "score binder candidates", "designability of this folder", "scRMSD for
- designs", "motif RMSD for these PDBs", "complexa analysis", "complexa evaluate
- from a PDB directory", "evaluate from pdb dir", or to score third-party outputs
- (BindCraft, AlphaProteo, RFdiffusion, hand-curated decoys). Picks the correct
- evaluate_*.yaml config, wires ++dataset.pdb_dir and the folding backend, runs the
- evaluate → analyze chain, parses the result CSV, and reports pass-rates against
- the right result_type thresholds.
+ Standalone evaluation of an existing PDB directory with Proteina-Complexa.
+ Use this skill whenever the user wants to "evaluate PDB files", "re-fold these
+ designs", "compute interface pAE", "compute i_pLDDT for a folder",
+ "run AF2 / RF3 / ESMFold on my designs", "score binder candidates",
+ "designability of this folder", "scRMSD for designs", "motif RMSD for these
+ PDBs", "complexa analysis", "complexa evaluate from a PDB directory",
+ "evaluate from pdb dir", or score third-party outputs (BindCraft, AlphaProteo,
+ RFdiffusion, hand-curated decoys). It picks the correct `evaluate_*.yaml`
+ config, wires `++dataset.pdb_dir` and the folding backend, runs
+ `complexa analysis` (the evaluate → analyze chain), parses the result CSV,
+ reports pass-rates against the right `result_type` thresholds, and emits a
+ replayable `eval_manifest.json`. Reach for this skill before hand-rolling
+ refolding scripts.
compatibility: "complexa CLI installed (pip install -e .); CUDA GPU; AF2_DIR (colabdesign) or RF3_CKPT_PATH+RF3_EXEC_PATH (rf3_latest); ESMFold weights for monomer paths"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
diff --git a/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/evals/trigger_evals.json b/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/evals/trigger_evals.json
deleted file mode 100644
index 4fbfce6d..00000000
--- a/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/evals/trigger_evals.json
+++ /dev/null
@@ -1,20 +0,0 @@
-[
- {"query": "Evaluate these PDB files with Proteina-Complexa", "should_trigger": true},
- {"query": "Re-fold these designs and score them", "should_trigger": true},
- {"query": "Compute interface pAE for my binder designs", "should_trigger": true},
- {"query": "compute i_pLDDT for a folder of PDBs", "should_trigger": true},
- {"query": "Run AF2 / RF3 / ESMFold on my designs and report metrics", "should_trigger": true},
- {"query": "Score these binder candidates", "should_trigger": true},
- {"query": "What's the designability of this folder of designs?", "should_trigger": true},
- {"query": "Get scRMSD for these designs", "should_trigger": true},
- {"query": "motif RMSD for these PDBs", "should_trigger": true},
- {"query": "run complexa analysis on this evaluate config", "should_trigger": true},
- {"query": "complexa evaluate from a PDB directory", "should_trigger": true},
- {"query": "evaluate from pdb dir", "should_trigger": true},
- {"query": "Score these BindCraft outputs against complexa metrics", "should_trigger": true},
- {"query": "Evaluate my AlphaProteo and RFdiffusion decoys", "should_trigger": true},
- {"query": "Design a new binder for TrkA", "should_trigger": false},
- {"query": "Generate binders with complexa design", "should_trigger": false},
- {"query": "Submit a binder search to the SLURM cluster", "should_trigger": false},
- {"query": "How do I open a PDB file in PyMOL?", "should_trigger": false}
-]
diff --git a/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/skill-card.md b/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/skill-card.md
new file mode 100644
index 00000000..647ece55
--- /dev/null
+++ b/open-models-skills/proteina-complexa/complexa-evaluate-pdbs/skill-card.md
@@ -0,0 +1,75 @@
+## Description:
+Evaluates an existing directory of PDB files with Proteina-Complexa — selecting the correct `evaluate_*.yaml` config and folding backend, running the `complexa analysis` evaluate-then-analyze chain, parsing the result CSV, reporting pass rates against `result_type` thresholds, and emitting a replayable `eval_manifest.json`.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers scoring binder candidates that already exist as structures — refolding designs, computing interface pAE, i_pLDDT, scRMSD, and motif RMSD, and assessing designability. Works on Proteina-Complexa output and equally on third-party outputs (BindCraft, AlphaProteo, RFdiffusion, hand-curated decoys), so it serves as a common yardstick across design methods.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* CUDA GPU
+* A folding backend: `AF2_DIR` (ColabDesign) or `RF3_CKPT_PATH` + `RF3_EXEC_PATH` (rf3_latest)
+* ESMFold weights for monomer evaluation paths
+* A directory of input PDB files
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Pass rates are only meaningful relative to the thresholds of the selected `result_type`; comparing numbers produced under different configs or folding backends is misleading.
+Mitigation: The skill emits a replayable `eval_manifest.json` recording the config, backend, and thresholds used, so comparisons can be checked for like-for-like.
+
+Risk: Evaluating designs with the same model family that generated them inflates apparent quality.
+Mitigation: The skill supports independent folding backends (AF2/ColabDesign, RF3, ESMFold) and is documented for use as an independent check; users should choose a backend distinct from the generator.
+
+Risk: Refolding a large PDB directory is GPU-intensive and can run far longer than a user expects from a single instruction.
+Mitigation: The skill selects the appropriate config up front and reports the input set size before running.
+
+Risk: Malformed or non-standard PDB inputs — particularly third-party outputs with unusual chain or numbering conventions — can be silently skipped or misparsed.
+Mitigation: The skill parses the result CSV and reports counts, so a shortfall between inputs and scored designs is visible.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- [ColabDesign / AlphaFold2](https://github.com/sokrypton/ColabDesign), RF3, and [ESMFold](https://github.com/facebookresearch/esm) — supported folding backends
+- Related skills: `complexa-setup`, `complexa-design`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Analysis, Files]
+**Output Format:** [Result CSV of per-design metrics; `eval_manifest.json`; Markdown pass-rate report]
+**Output Parameters:** [2D — one row per evaluated design, columns for interface pAE, i_pLDDT, scRMSD, motif RMSD; 1D for aggregate pass rates]
+**Other Properties Related to Output:** [Metrics are model-reported in-silico estimates, not measurements, and are not calibrated probabilities of experimental binding.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering config selection, backend wiring, evaluation execution, and pass-rate reporting with manifest emission — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Evaluation results are computational hypotheses. A high in-silico pass rate is not evidence of experimental binding, and must not be used for clinical decision-making, diagnosis, or treatment selection.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/proteina-complexa/complexa-setup/SKILL.md b/open-models-skills/proteina-complexa/complexa-setup/SKILL.md
index 335df7fd..3a7ffe1a 100644
--- a/open-models-skills/proteina-complexa/complexa-setup/SKILL.md
+++ b/open-models-skills/proteina-complexa/complexa-setup/SKILL.md
@@ -3,8 +3,8 @@ name: complexa-setup
description: >
First-time setup, environment configuration, and model-weight installation for
Proteina-Complexa. Reach for this skill whenever the user says "set up complexa",
- "install complexa", "configure my environment file", "first-time setup", "what models do I
- have installed", "what's in my environment file", "download model weights", "download
+ "install complexa", "configure my .env", "first-time setup", "what models do I
+ have installed", "what's in my .env", "download model weights", "download
Complexa / AF2 / RF3 / ProteinMPNN / LigandMPNN / ESM2 / ESMFold checkpoints",
"preflight my GPU", "verify environment", "complexa init", "complexa download",
"complexa download --status", "complexa validate env", or any time a fresh
@@ -28,7 +28,7 @@ user (or a future agent) can re-read instead of re-deriving state.
| Step | Preferred path | Why |
|---|---|---|
-| `.env` creation (Step 2) | **File edit** (copying the env template + 3 line swaps) or `complexa init` | `complexa init` is a thin wrapper around `cp + 3 regex swaps` (`_swap_runtime_in_env` in `cli_runner.py`). Either path works; pick CLI for new humans, direct edit for agents. |
+| `.env` creation (Step 2) | **File edit** (`cp .env_example .env` + 3 line swaps) or `complexa init` | `complexa init` is a thin wrapper around `cp + 3 regex swaps` (`_swap_runtime_in_env` in `cli_runner.py`). Either path works; pick CLI for new humans, direct edit for agents. |
| `.env` value edits (Step 3) | **File edit** (StrReplace `LOCAL_CODE_PATH=…` etc.) | No CLI for this — the values are user-specific paths. |
| Download model weights (Step 4) | **CLI** (`complexa download --…`) | Dispatches to `env/download_startup.sh` (~1000 lines of bash with NGC URLs, retries, checksum-style skip-if-present). Don't try to replicate. |
| Validate env (Step 5) | **CLI** (`complexa validate env`) or `test -f .env && test -d $DATA_PATH` | CLI prints a nicer report; the manual check is one-liner-safe. |
diff --git a/open-models-skills/proteina-complexa/complexa-setup/config/skillspector-baseline.yml b/open-models-skills/proteina-complexa/complexa-setup/config/skillspector-baseline.yml
deleted file mode 100644
index b22487f4..00000000
--- a/open-models-skills/proteina-complexa/complexa-setup/config/skillspector-baseline.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-# SkillSpector suppression baseline — complexa-setup
-#
-# Audited, false-positive suppression consumed by the NVSkills Tier 1 runner
-# (.ci/run_validation_tier.sh passes this via `skillevaluator --skillspector-baseline`).
-# Suppressed findings are NOT deleted: they remain in the report JSON marked
-# `suppressed: true` with the reason below, so the decision stays auditable in
-# the MR diff. A finding is suppressed only when every field set here
-# glob-matches it (fnmatch, case-insensitive).
-version: 1
-
-rules:
- - id: "PE3"
- path: "*SKILL.md"
- reason: >-
- Reviewed false positive (BioNeMo, omosafi@nvidia.com, 2026-07-31).
- complexa-setup is a first-party setup skill whose documented purpose is
- generating and editing the project's own dotenv configuration file (the
- COMPLEXA_RUNTIME plus LOCAL_*_PATH placeholders) through the `complexa
- init` helper. The PE3 "Credential Access" matches are literal references
- to that project config file in the setup steps and the troubleshooting
- table of SKILL.md — user-facing configuration guidance, not credential
- theft. No SSH private keys, cloud credential stores, or secret token files
- are involved.
diff --git a/open-models-skills/proteina-complexa/complexa-setup/reference/downloads.md b/open-models-skills/proteina-complexa/complexa-setup/reference/downloads.md
index b760fdfe..12d3a44c 100644
--- a/open-models-skills/proteina-complexa/complexa-setup/reference/downloads.md
+++ b/open-models-skills/proteina-complexa/complexa-setup/reference/downloads.md
@@ -3,12 +3,10 @@
Full flag matrix, destination layout, and NGC source for every checkpoint
Complexa can pull.
-`complexa download` is a thin Python wrapper around `env/download_startup.sh`.
-The CLI (`src/proteinfoundation/cli/cli_runner.py:download_main`) accepts the
-documented flags below and forwards them to the bash script. It is a first-party,
-developer-run CLI invoked with a fixed, documented set of flags — it takes no
-untrusted or network-supplied input, so the forwarded arguments are not an
-injection surface.
+`complexa download` is a thin Python wrapper around `env/download_startup.sh`
+— the CLI argparse (in `src/proteinfoundation/cli/cli_runner.py:download_main`)
+forwards `sys.argv[2:]` straight to the bash script, so any flag the bash
+script accepts is reachable.
---
@@ -29,7 +27,8 @@ The Python argparse explicitly defines these flags:
The underlying bash script also accepts per-model flags (`--pmpnn`,
`--ligmpnn`, `--af2`, `--esm2`, `--esmfold`, `--rf3`, `--boltz2`) that pass
through unchanged. They are listed in `env/download_startup.sh:show_help` but
-not in the Python argparse — the bash script accepts them directly.
+not in the Python argparse — they still work because of the `sys.argv[2:]`
+passthrough.
| Passthrough flag | Destination | Approx size |
|------------------|-------------|-------------|
diff --git a/open-models-skills/proteina-complexa/complexa-setup/skill-card.md b/open-models-skills/proteina-complexa/complexa-setup/skill-card.md
new file mode 100644
index 00000000..41ca079e
--- /dev/null
+++ b/open-models-skills/proteina-complexa/complexa-setup/skill-card.md
@@ -0,0 +1,68 @@
+## Description:
+Performs first-time setup for Proteina-Complexa — driving `complexa init`, `complexa download`, and `complexa validate env` end to end, editing required `.env` keys, selecting the UV or Docker runtime, and emitting a replayable setup artifact.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers and computational biologists making a fresh Proteina-Complexa checkout runnable — verifying GPU preflight, configuring `.env`, and installing model weights (Complexa, AF2, RF3, ProteinMPNN, LigandMPNN, ESM2, ESMFold). This is the first skill to run on a new clone; every other `complexa-*` skill depends on it.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): Credentials for model-weight sources, as required by the individual checkpoints being downloaded
+
+* `complexa` CLI installed (`pip install -e .`)
+* bash 4+
+* `nvidia-smi` optional at setup time; a CUDA GPU is required for the design and evaluation skills
+* Substantial disk for model checkpoints
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: The skill edits the user's `.env` file, which holds paths and may hold credentials; a mis-edit could break the environment or expose values in an agent transcript.
+Mitigation: The skill edits only the required keys and reports what changed; `.env` is git-ignored in this repository and must never be committed. Users should treat agent transcripts as sensitive.
+
+Risk: Model-weight downloads are large and fetch third-party checkpoints (AF2/ColabDesign, RF3, ESMFold, ProteinMPNN, LigandMPNN) whose licenses differ from this repository's.
+Mitigation: `complexa download --status` reports what is present before fetching; users are responsible for reviewing and complying with each checkpoint's upstream license terms.
+
+Risk: A partially completed setup produces confusing failures much later, inside long-running design jobs.
+Mitigation: `complexa validate env` runs as an explicit final step so environment problems surface at setup time.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- Related skills: `complexa-target`, `complexa-design`, `complexa-evaluate-pdbs`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Analysis, Files, Configuration instructions]
+**Output Format:** [Markdown setup report; edited `.env`; downloaded checkpoint files; replayable setup artifact]
+**Output Parameters:** [1D — per-check pass/fail status, resolved runtime, installed model inventory]
+**Other Properties Related to Output:** [Side effects: writes `.env`, downloads model weights to disk]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering init, weight download and status reporting, `.env` configuration, and environment validation — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/proteina-complexa/complexa-sweep/SKILL.md b/open-models-skills/proteina-complexa/complexa-sweep/SKILL.md
index a692d614..f053d10b 100644
--- a/open-models-skills/proteina-complexa/complexa-sweep/SKILL.md
+++ b/open-models-skills/proteina-complexa/complexa-sweep/SKILL.md
@@ -198,7 +198,7 @@ Alongside the manifest, save the ranked `sweep_summary.csv` from Step 6 to `./sw
Total GPU-time for a sweep = `N_configs × per_run_GPU_time`. A single `search_binder_local_pipeline` run on one A100 is roughly 30–90 min (binder length + nsteps dependent). A 4-axis × 4-value sweep = 256 configs × ~60 min = ~256 GPU-hours — at that scale, plan on a multi-GPU host with the Step-4 sharding pattern.
-Refer to the shared hardware reference for the per-run baseline + VRAM minima.
+Refer to [`.claude/skills/_shared/reference/hardware.md`](../_shared/reference/hardware.md) for the per-run baseline + VRAM minima.
## Troubleshooting
diff --git a/open-models-skills/proteina-complexa/complexa-sweep/reference/SWEEP.md b/open-models-skills/proteina-complexa/complexa-sweep/reference/SWEEP.md
index c459c8f9..6dbf2e8b 100644
--- a/open-models-skills/proteina-complexa/complexa-sweep/reference/SWEEP.md
+++ b/open-models-skills/proteina-complexa/complexa-sweep/reference/SWEEP.md
@@ -3,10 +3,10 @@
How to run parameter sweeps and override experiment settings without modifying source code.
> **Documentation Map**
-> - Running a design? See the Inference Guide.
-> - Tuning YAML configs? See the Configuration Guide.
-> - Understanding metrics? See the Evaluation Guide.
-> - Search metadata? See the Search Metadata notes.
+> - Running a design? See [Inference Guide](INFERENCE.md)
+> - Tuning YAML configs? See [Configuration Guide](CONFIGURATION_GUIDE.md)
+> - Understanding metrics? See [Evaluation Guide](EVALUATION_METRICS.md)
+> - Search metadata? See [Search Metadata](SEARCH_METADATA.md)
## Overview
@@ -276,7 +276,7 @@ orchestration. It does not change how individual modules consume configs.
| `--infer_config_name search_binder` | `--config_name search_binder_pipeline` |
| `generate_binder_inference_configs.py` | `generate_inference_configs.py` |
| Hardcoded `ALPHA_PROTEO_TARGETS` list | Removed (use sweep or override) |
-| Manual removal of `configs/inference_configs` | Automatic: temp dir + staging (concurrent-safe) |
+| `rm -rf configs/inference_configs` | Automatic: temp dir + staging (concurrent-safe) |
## Tests
diff --git a/open-models-skills/proteina-complexa/complexa-sweep/reference/sweep_axes.md b/open-models-skills/proteina-complexa/complexa-sweep/reference/sweep_axes.md
index 0d962231..693d8387 100644
--- a/open-models-skills/proteina-complexa/complexa-sweep/reference/sweep_axes.md
+++ b/open-models-skills/proteina-complexa/complexa-sweep/reference/sweep_axes.md
@@ -1,6 +1,6 @@
# Sweep Axes Reference
-Catalogue of swept keys for Proteina-Complexa design pipelines, grouped by pipeline stage. Every key is a config dot-path you can put in a `configs/sweeps/*.yaml` file as a sweep axis (list value) or as an `--override KEY=VAL` pin.
+Catalogue of swept keys for Proteina-Complexa design pipelines, grouped by pipeline stage. Every key is a Hydra dot-path you can put in a `configs/sweeps/*.yaml` file as a sweep axis (list value) or as an `--override KEY=VAL` pin.
Defaults are read from `configs/pipeline/binder/binder_generate.yaml`, `configs/pipeline/binder/binder_evaluate.yaml`, and `configs/pipeline/model_sampling.yaml`. Verify against your actual base pipeline config before launching — different pipelines (e.g. `search_ligand_binder_local_pipeline`, `search_ame_local_pipeline`) inherit different defaults.
@@ -82,7 +82,7 @@ Annotated example based on `configs/sweeps/example.yaml`:
```yaml
# --- Sweep axes (lists, cartesian-producted) ---
-# Each key is a config dot-path. Each list value becomes one dimension.
+# Each key is a Hydra dot-path. Each list value becomes one dimension.
# Total configs = product of list lengths. Here 2 × 2 = 4.
generation.search.beam_search.beam_width:
- 2
@@ -140,7 +140,7 @@ For an irregular set of `(key1, key2)` pairs (not a full cartesian product), the
| Column | Source | Notes |
|---|---|---|
| `config_id` | The index in `inf_{idx}_{run_name}.yaml` | 0-based, sequential, set by `apply_sweeper_and_save_configs`. |
-| `` (one per axis) | Read from the per-config `inf_*.yaml` at the swept config path | Strip the dot-path to a short column header (e.g. `beam_width`). |
+| `` (one per axis) | Read from the per-config `inf_*.yaml` at the swept Hydra path | Strip the dot-path to a short column header (e.g. `beam_width`). |
| `n_samples` | `len(results_csv)` | Rows in the analyze CSV for this config. |
| `success_rate` | `mean(passes_filter)` if column present, else thresholded `mean((i_pae < 10) & (i_plddt > 0.7) & (sc_rmsd < 2.0))` | Confirm thresholds with the user. |
| `mean_i_pae` | `i_pae.mean()` | Lower = better. AF2 interface PAE. |
diff --git a/open-models-skills/proteina-complexa/complexa-sweep/skill-card.md b/open-models-skills/proteina-complexa/complexa-sweep/skill-card.md
new file mode 100644
index 00000000..9cd61b24
--- /dev/null
+++ b/open-models-skills/proteina-complexa/complexa-sweep/skill-card.md
@@ -0,0 +1,75 @@
+## Description:
+Runs parameter sweeps over a Proteina-Complexa design pipeline — authoring sweeper YAML, expanding cartesian-product configurations, and ranking per-configuration results for hyperparameter scans and Pareto search over generation, reward, and evaluation knobs.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers and method developers tuning a design pipeline — scanning beam width, step count, temperature, or reward weights; ablating reward components; or trading binder quality against wall-clock. This is the only skill that owns sweeper YAML authoring and per-configuration result ranking.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* `complexa-setup` completed and a target registered (`complexa-target`)
+* CUDA GPU meeting the `complexa-design` requirements, for each configuration in the sweep
+* Disk and GPU-hours proportional to the size of the cartesian product
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: This is the highest-cost skill in the family. A cartesian product expands multiplicatively, so a sweep specified in one short instruction can launch dozens of full design campaigns and consume very large amounts of GPU time or cloud spend.
+Mitigation: The skill expands and reports the configuration list before execution, so the user sees the run count before committing. Users should start with a small grid and confirm cost before widening.
+
+Risk: Ranking configurations on a stochastic pipeline can select a configuration that merely got a lucky seed rather than one that is genuinely better.
+Mitigation: Results are reported per configuration rather than as a single winner, so users can judge whether differences exceed run-to-run variance. Seeds should be fixed for like-for-like comparison.
+
+Risk: Sweeping on a small or unrepresentative target set overfits hyperparameters to that target, and the choice may not transfer.
+Mitigation: Per-configuration results are retained so users can re-examine the ranking against a held-out target.
+
+Risk: A large sweep writes many output directories and can exhaust disk mid-run, losing partially completed configurations.
+Mitigation: Outputs are written under explicit per-configuration paths; users should size storage against the expanded run count.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- `reference/sweep_axes.md` in this skill directory — the sweepable parameter axes
+- `configs/sweeps/` — example sweep definitions
+- Related skills: `complexa-design`, `complexa-target`, `complexa-evaluate-pdbs`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Sweeper YAML; per-configuration design outputs and result CSVs; Markdown ranking table]
+**Output Parameters:** [2D — one row per configuration, columns for the swept parameters and resulting metrics]
+**Other Properties Related to Output:** [Rankings reflect in-silico metrics on a stochastic pipeline; differences within run-to-run variance should not be treated as meaningful.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering sweeper YAML authoring, cartesian-product expansion, sweep execution, and per-configuration ranking — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Sweeps generate novel protein sequences and structures at scale. Users are responsible for screening designed sequences before synthesis, and for using the skill consistent with applicable biosecurity norms, biosafety review processes, and export-control obligations.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/open-models-skills/proteina-complexa/complexa-target/skill-card.md b/open-models-skills/proteina-complexa/complexa-target/skill-card.md
new file mode 100644
index 00000000..e00351b6
--- /dev/null
+++ b/open-models-skills/proteina-complexa/complexa-target/skill-card.md
@@ -0,0 +1,70 @@
+## Description:
+Adds, registers, edits, lists, shows, and validates Proteina-Complexa design targets — protein binder, ligand binder, and AME / enzyme-scaffolding — and is the only skill that writes the three target dictionary files.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers defining what to design against — registering a target structure, chain specification, hotspot residues, and binder length range before running `complexa-design`. Also covers `complexa validate target` and questions about chain-spec syntax and where hotspots live.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* `complexa-setup` completed
+* A target structure (PDB/mmCIF) or SMILES for ligand-binder targets
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: This skill has exclusive write access to `configs/targets/{,ligand_}targets_dict.yaml` and `configs/design_tasks/ame_dict_v2.yaml`; a malformed edit could corrupt target definitions shared across a team's design runs.
+Mitigation: `complexa validate target` runs as an explicit validation path, and the skill is the single documented owner of those files so edits are not made ad hoc from multiple places.
+
+Risk: Incorrect hotspot residue numbering — a common failure when structure numbering differs from sequence numbering — silently redirects design to the wrong surface, wasting an entire downstream design campaign.
+Mitigation: The skill validates targets before use and supports structure-confirmed hotspot specification rather than accepting bare residue indices without checking.
+
+Risk: Target definitions may be derived from third-party structures (e.g. RCSB PDB entries) whose terms of use apply to downstream work.
+Mitigation: Users are responsible for confirming the provenance and licensing of any structure they register.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- [RCSB Protein Data Bank](https://www.rcsb.org/) — common source of target structures
+- Related skills: `complexa-setup`, `complexa-design`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [YAML target dictionary entries; Markdown summary of registered targets]
+**Output Parameters:** [1D — target identifier, chain spec, hotspot residues, binder length range]
+**Other Properties Related to Output:** [Side effect: writes to the repository's target dictionary configuration files]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering target registration, listing/showing, chain and hotspot specification, and validation — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Target selection determines what a downstream design campaign is aimed at. Users are responsible for ensuring their design targets are consistent with applicable biosecurity norms and export-control obligations.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-design/SKILL.md b/skills/bionemo-agent-toolkit/skills/complexa-design/SKILL.md
index ca3b89f9..bbfd0299 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-design/SKILL.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-design/SKILL.md
@@ -1,17 +1,19 @@
---
name: complexa-design
description: >
- End-to-end Proteina-Complexa design pipeline driver. Use when the user wants to
- "design a binder", "design binders for X", "run complexa design", "de novo
- binder", "PDL1 binder", "TrkA binder", "design proteins for target", "protein
- binder design", "ligand binder", "design a small-molecule binder", "ATP-binding
- protein", "AME motif scaffolding", "scaffold a motif near a ligand", "motif +
- ligand design", "enzyme scaffolding", "flow matching protein design",
- "beam-search binder", "FK steering", "MCTS protein design", or "refold with AF2
- / RF3 / ESMFold", or wants success rates, interface pAE, scRMSD, or FoldSeek
- diversity from one command. Drives the complexa design pipeline from target
- picking to manifest emission and reports how many designs passed.
-compatibility: "complexa CLI installed (pip install -e .); environment file populated; 1x CUDA GPU >=40GB VRAM (A100/H100/L40S); 24 CPUs; ~50GB disk"
+ End-to-end Proteina-Complexa design pipeline driver. Reach for this skill whenever
+ the user wants to "design a binder", "design binders for X", "run complexa
+ design", "de novo binder", "PDL1 binder", "TrkA binder", "design proteins for
+ target", "protein binder design", "ligand binder", "design a small-molecule
+ binder", "ATP-binding protein", "AME motif scaffolding", "scaffold a motif
+ near a ligand", "motif + ligand design", "enzyme scaffolding", "flow matching
+ protein design", "beam-search binder", "FK steering", "MCTS protein design",
+ "refold with AF2", "refold with RF3", or wants success rates, interface pAE,
+ scRMSD, or
+ FoldSeek diversity from a single command. This is the scientific anchor of
+ the skill set: it drives `complexa design ` from target picking to
+ manifest emission and tells the user how many designs passed.
+compatibility: "complexa CLI installed (pip install -e .); .env populated; 1x CUDA GPU >=40GB VRAM (A100/H100/L40S); 24 CPUs; ~50GB disk"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-design/evals/trigger_evals.json b/skills/bionemo-agent-toolkit/skills/complexa-design/evals/trigger_evals.json
deleted file mode 100644
index 0577c82c..00000000
--- a/skills/bionemo-agent-toolkit/skills/complexa-design/evals/trigger_evals.json
+++ /dev/null
@@ -1,27 +0,0 @@
-[
- {"query": "Design a binder for my target", "should_trigger": true},
- {"query": "design binders for PDL1", "should_trigger": true},
- {"query": "run complexa design on this target", "should_trigger": true},
- {"query": "de novo binder design", "should_trigger": true},
- {"query": "Design a PDL1 binder", "should_trigger": true},
- {"query": "Design a TrkA binder", "should_trigger": true},
- {"query": "design proteins for target", "should_trigger": true},
- {"query": "protein binder design end to end", "should_trigger": true},
- {"query": "Design a ligand binder for this small molecule", "should_trigger": true},
- {"query": "design a small-molecule binder", "should_trigger": true},
- {"query": "Design an ATP-binding protein", "should_trigger": true},
- {"query": "AME motif scaffolding around a ligand", "should_trigger": true},
- {"query": "scaffold a motif near a ligand", "should_trigger": true},
- {"query": "motif + ligand design", "should_trigger": true},
- {"query": "enzyme scaffolding with complexa", "should_trigger": true},
- {"query": "flow matching protein design", "should_trigger": true},
- {"query": "beam-search binder generation", "should_trigger": true},
- {"query": "use FK steering for the design search", "should_trigger": true},
- {"query": "MCTS protein design", "should_trigger": true},
- {"query": "refold designs with AF2 / RF3 / ESMFold and report success rates", "should_trigger": true},
- {"query": "What's the interface pAE, scRMSD, and FoldSeek diversity of the run?", "should_trigger": true},
- {"query": "Evaluate an existing folder of PDBs I already generated", "should_trigger": false},
- {"query": "Launch the design run on the SLURM cluster", "should_trigger": false},
- {"query": "Register a new target in the targets dict", "should_trigger": false},
- {"query": "How do I compute molecular weight of aspirin?", "should_trigger": false}
-]
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-design/skill-card.md b/skills/bionemo-agent-toolkit/skills/complexa-design/skill-card.md
new file mode 100644
index 00000000..2242a470
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/complexa-design/skill-card.md
@@ -0,0 +1,80 @@
+## Description:
+Drives the end-to-end Proteina-Complexa design pipeline — `complexa design ` from target selection through manifest emission — for protein binder, ligand binder, and AME / motif-scaffolding tasks, and reports how many designs passed.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers and computational biologists running de novo binder design against a registered target — generating candidate binders with reward-guided flow matching, refolding them with an independent structure predictor (AF2 or RF3), and ranking by interface metrics (success rate, interface pAE, scRMSD, FoldSeek diversity). This is the scientific anchor of the `complexa-*` skill set.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* `.env` populated (`complexa-setup`) and a target registered (`complexa-target`)
+* 1× CUDA GPU with ≥40 GB VRAM (A100 / H100 / L40S)
+* 24 CPUs, ~50 GB disk
+* Folding backend weights: AF2 (ColabDesign) or RF3
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Designed binders are computational predictions. Reported success rates, interface pAE, and scRMSD are in-silico metrics that correlate imperfectly with experimental binding; treating them as validated hits wastes wet-lab resources.
+Mitigation: The pipeline refolds designs with a structure predictor independent of the generator and reports pass rates against explicit thresholds rather than a single score. All outputs require experimental validation.
+
+Risk: A full design campaign is a long, GPU-intensive workload that a single agent instruction can start, consuming substantial GPU-hours or cloud spend.
+Mitigation: The skill runs a pre-flight validation step before launching and emits a replayable manifest, so configuration errors surface before the expensive stage.
+
+Risk: Incorrect target or hotspot configuration directs the entire campaign at the wrong surface, with the error invisible until results are inspected.
+Mitigation: The skill validates the target as an explicit pipeline step and refuses to proceed on an invalid target.
+
+Risk: Generation is stochastic — repeated runs with identical inputs produce different binders unless a seed is fixed, which can confound comparisons between configurations.
+Mitigation: The emitted manifest records the run configuration for replay; use `complexa-sweep` for controlled comparisons across configurations.
+
+Risk: The skill writes design outputs and can overwrite results from a previous campaign in the same directory.
+Mitigation: Outputs are written under explicit per-run output paths.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- La-Proteina — the flow-based generative model this work builds on
+- [ColabDesign / AlphaFold2](https://github.com/sokrypton/ColabDesign) and RF3 — independent refolding backends
+- [Foldseek](https://github.com/steineggerlab/foldseek) — structural diversity metric
+- Related skills: `complexa-setup`, `complexa-target`, `complexa-evaluate-pdbs`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [PDB structures of designed binders; result CSV of per-design metrics; replayable JSON manifest; Markdown summary]
+**Output Parameters:** [3D for atomic coordinates; 2D for the per-design metric table; 1D for campaign-level pass rates]
+**Other Properties Related to Output:** [Outputs are computational predictions, not measurements. Confidence and interface metrics are model-reported and are not calibrated probabilities of experimental binding. Generation is stochastic unless seeded.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering pipeline selection, pre-flight validation, design execution, and result collection with manifest emission — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+This skill generates novel protein sequences and structures. Users are responsible for screening designed sequences before synthesis, and for using the skill consistent with applicable biosecurity norms, biosafety review processes, and export-control obligations. Designed binders are research hypotheses and must not be used for clinical decision-making, diagnosis, or treatment selection.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/SKILL.md b/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/SKILL.md
index 1155b10b..57fe7cfa 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/SKILL.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/SKILL.md
@@ -1,16 +1,19 @@
---
name: complexa-evaluate-pdbs
description: >
- Standalone evaluation of an existing PDB directory with Proteina-Complexa. Use
- when the user wants to "evaluate PDB files", "re-fold these designs", "compute
- interface pAE", "compute i_pLDDT for a folder", "run AF2 / RF3 / ESMFold on my
- designs", "score binder candidates", "designability of this folder", "scRMSD for
- designs", "motif RMSD for these PDBs", "complexa analysis", "complexa evaluate
- from a PDB directory", "evaluate from pdb dir", or to score third-party outputs
- (BindCraft, AlphaProteo, RFdiffusion, hand-curated decoys). Picks the correct
- evaluate_*.yaml config, wires ++dataset.pdb_dir and the folding backend, runs the
- evaluate → analyze chain, parses the result CSV, and reports pass-rates against
- the right result_type thresholds.
+ Standalone evaluation of an existing PDB directory with Proteina-Complexa.
+ Use this skill whenever the user wants to "evaluate PDB files", "re-fold these
+ designs", "compute interface pAE", "compute i_pLDDT for a folder",
+ "run AF2 / RF3 / ESMFold on my designs", "score binder candidates",
+ "designability of this folder", "scRMSD for designs", "motif RMSD for these
+ PDBs", "complexa analysis", "complexa evaluate from a PDB directory",
+ "evaluate from pdb dir", or score third-party outputs (BindCraft, AlphaProteo,
+ RFdiffusion, hand-curated decoys). It picks the correct `evaluate_*.yaml`
+ config, wires `++dataset.pdb_dir` and the folding backend, runs
+ `complexa analysis` (the evaluate → analyze chain), parses the result CSV,
+ reports pass-rates against the right `result_type` thresholds, and emits a
+ replayable `eval_manifest.json`. Reach for this skill before hand-rolling
+ refolding scripts.
compatibility: "complexa CLI installed (pip install -e .); CUDA GPU; AF2_DIR (colabdesign) or RF3_CKPT_PATH+RF3_EXEC_PATH (rf3_latest); ESMFold weights for monomer paths"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/evals/trigger_evals.json b/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/evals/trigger_evals.json
deleted file mode 100644
index 4fbfce6d..00000000
--- a/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/evals/trigger_evals.json
+++ /dev/null
@@ -1,20 +0,0 @@
-[
- {"query": "Evaluate these PDB files with Proteina-Complexa", "should_trigger": true},
- {"query": "Re-fold these designs and score them", "should_trigger": true},
- {"query": "Compute interface pAE for my binder designs", "should_trigger": true},
- {"query": "compute i_pLDDT for a folder of PDBs", "should_trigger": true},
- {"query": "Run AF2 / RF3 / ESMFold on my designs and report metrics", "should_trigger": true},
- {"query": "Score these binder candidates", "should_trigger": true},
- {"query": "What's the designability of this folder of designs?", "should_trigger": true},
- {"query": "Get scRMSD for these designs", "should_trigger": true},
- {"query": "motif RMSD for these PDBs", "should_trigger": true},
- {"query": "run complexa analysis on this evaluate config", "should_trigger": true},
- {"query": "complexa evaluate from a PDB directory", "should_trigger": true},
- {"query": "evaluate from pdb dir", "should_trigger": true},
- {"query": "Score these BindCraft outputs against complexa metrics", "should_trigger": true},
- {"query": "Evaluate my AlphaProteo and RFdiffusion decoys", "should_trigger": true},
- {"query": "Design a new binder for TrkA", "should_trigger": false},
- {"query": "Generate binders with complexa design", "should_trigger": false},
- {"query": "Submit a binder search to the SLURM cluster", "should_trigger": false},
- {"query": "How do I open a PDB file in PyMOL?", "should_trigger": false}
-]
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/skill-card.md b/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/skill-card.md
new file mode 100644
index 00000000..647ece55
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/complexa-evaluate-pdbs/skill-card.md
@@ -0,0 +1,75 @@
+## Description:
+Evaluates an existing directory of PDB files with Proteina-Complexa — selecting the correct `evaluate_*.yaml` config and folding backend, running the `complexa analysis` evaluate-then-analyze chain, parsing the result CSV, reporting pass rates against `result_type` thresholds, and emitting a replayable `eval_manifest.json`.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers scoring binder candidates that already exist as structures — refolding designs, computing interface pAE, i_pLDDT, scRMSD, and motif RMSD, and assessing designability. Works on Proteina-Complexa output and equally on third-party outputs (BindCraft, AlphaProteo, RFdiffusion, hand-curated decoys), so it serves as a common yardstick across design methods.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* CUDA GPU
+* A folding backend: `AF2_DIR` (ColabDesign) or `RF3_CKPT_PATH` + `RF3_EXEC_PATH` (rf3_latest)
+* ESMFold weights for monomer evaluation paths
+* A directory of input PDB files
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Pass rates are only meaningful relative to the thresholds of the selected `result_type`; comparing numbers produced under different configs or folding backends is misleading.
+Mitigation: The skill emits a replayable `eval_manifest.json` recording the config, backend, and thresholds used, so comparisons can be checked for like-for-like.
+
+Risk: Evaluating designs with the same model family that generated them inflates apparent quality.
+Mitigation: The skill supports independent folding backends (AF2/ColabDesign, RF3, ESMFold) and is documented for use as an independent check; users should choose a backend distinct from the generator.
+
+Risk: Refolding a large PDB directory is GPU-intensive and can run far longer than a user expects from a single instruction.
+Mitigation: The skill selects the appropriate config up front and reports the input set size before running.
+
+Risk: Malformed or non-standard PDB inputs — particularly third-party outputs with unusual chain or numbering conventions — can be silently skipped or misparsed.
+Mitigation: The skill parses the result CSV and reports counts, so a shortfall between inputs and scored designs is visible.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- [ColabDesign / AlphaFold2](https://github.com/sokrypton/ColabDesign), RF3, and [ESMFold](https://github.com/facebookresearch/esm) — supported folding backends
+- Related skills: `complexa-setup`, `complexa-design`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Analysis, Files]
+**Output Format:** [Result CSV of per-design metrics; `eval_manifest.json`; Markdown pass-rate report]
+**Output Parameters:** [2D — one row per evaluated design, columns for interface pAE, i_pLDDT, scRMSD, motif RMSD; 1D for aggregate pass rates]
+**Other Properties Related to Output:** [Metrics are model-reported in-silico estimates, not measurements, and are not calibrated probabilities of experimental binding.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering config selection, backend wiring, evaluation execution, and pass-rate reporting with manifest emission — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Evaluation results are computational hypotheses. A high in-silico pass rate is not evidence of experimental binding, and must not be used for clinical decision-making, diagnosis, or treatment selection.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-setup/SKILL.md b/skills/bionemo-agent-toolkit/skills/complexa-setup/SKILL.md
index 335df7fd..3a7ffe1a 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-setup/SKILL.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-setup/SKILL.md
@@ -3,8 +3,8 @@ name: complexa-setup
description: >
First-time setup, environment configuration, and model-weight installation for
Proteina-Complexa. Reach for this skill whenever the user says "set up complexa",
- "install complexa", "configure my environment file", "first-time setup", "what models do I
- have installed", "what's in my environment file", "download model weights", "download
+ "install complexa", "configure my .env", "first-time setup", "what models do I
+ have installed", "what's in my .env", "download model weights", "download
Complexa / AF2 / RF3 / ProteinMPNN / LigandMPNN / ESM2 / ESMFold checkpoints",
"preflight my GPU", "verify environment", "complexa init", "complexa download",
"complexa download --status", "complexa validate env", or any time a fresh
@@ -28,7 +28,7 @@ user (or a future agent) can re-read instead of re-deriving state.
| Step | Preferred path | Why |
|---|---|---|
-| `.env` creation (Step 2) | **File edit** (copying the env template + 3 line swaps) or `complexa init` | `complexa init` is a thin wrapper around `cp + 3 regex swaps` (`_swap_runtime_in_env` in `cli_runner.py`). Either path works; pick CLI for new humans, direct edit for agents. |
+| `.env` creation (Step 2) | **File edit** (`cp .env_example .env` + 3 line swaps) or `complexa init` | `complexa init` is a thin wrapper around `cp + 3 regex swaps` (`_swap_runtime_in_env` in `cli_runner.py`). Either path works; pick CLI for new humans, direct edit for agents. |
| `.env` value edits (Step 3) | **File edit** (StrReplace `LOCAL_CODE_PATH=…` etc.) | No CLI for this — the values are user-specific paths. |
| Download model weights (Step 4) | **CLI** (`complexa download --…`) | Dispatches to `env/download_startup.sh` (~1000 lines of bash with NGC URLs, retries, checksum-style skip-if-present). Don't try to replicate. |
| Validate env (Step 5) | **CLI** (`complexa validate env`) or `test -f .env && test -d $DATA_PATH` | CLI prints a nicer report; the manual check is one-liner-safe. |
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-setup/config/skillspector-baseline.yml b/skills/bionemo-agent-toolkit/skills/complexa-setup/config/skillspector-baseline.yml
deleted file mode 100644
index b22487f4..00000000
--- a/skills/bionemo-agent-toolkit/skills/complexa-setup/config/skillspector-baseline.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-# SkillSpector suppression baseline — complexa-setup
-#
-# Audited, false-positive suppression consumed by the NVSkills Tier 1 runner
-# (.ci/run_validation_tier.sh passes this via `skillevaluator --skillspector-baseline`).
-# Suppressed findings are NOT deleted: they remain in the report JSON marked
-# `suppressed: true` with the reason below, so the decision stays auditable in
-# the MR diff. A finding is suppressed only when every field set here
-# glob-matches it (fnmatch, case-insensitive).
-version: 1
-
-rules:
- - id: "PE3"
- path: "*SKILL.md"
- reason: >-
- Reviewed false positive (BioNeMo, omosafi@nvidia.com, 2026-07-31).
- complexa-setup is a first-party setup skill whose documented purpose is
- generating and editing the project's own dotenv configuration file (the
- COMPLEXA_RUNTIME plus LOCAL_*_PATH placeholders) through the `complexa
- init` helper. The PE3 "Credential Access" matches are literal references
- to that project config file in the setup steps and the troubleshooting
- table of SKILL.md — user-facing configuration guidance, not credential
- theft. No SSH private keys, cloud credential stores, or secret token files
- are involved.
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-setup/reference/downloads.md b/skills/bionemo-agent-toolkit/skills/complexa-setup/reference/downloads.md
index b760fdfe..12d3a44c 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-setup/reference/downloads.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-setup/reference/downloads.md
@@ -3,12 +3,10 @@
Full flag matrix, destination layout, and NGC source for every checkpoint
Complexa can pull.
-`complexa download` is a thin Python wrapper around `env/download_startup.sh`.
-The CLI (`src/proteinfoundation/cli/cli_runner.py:download_main`) accepts the
-documented flags below and forwards them to the bash script. It is a first-party,
-developer-run CLI invoked with a fixed, documented set of flags — it takes no
-untrusted or network-supplied input, so the forwarded arguments are not an
-injection surface.
+`complexa download` is a thin Python wrapper around `env/download_startup.sh`
+— the CLI argparse (in `src/proteinfoundation/cli/cli_runner.py:download_main`)
+forwards `sys.argv[2:]` straight to the bash script, so any flag the bash
+script accepts is reachable.
---
@@ -29,7 +27,8 @@ The Python argparse explicitly defines these flags:
The underlying bash script also accepts per-model flags (`--pmpnn`,
`--ligmpnn`, `--af2`, `--esm2`, `--esmfold`, `--rf3`, `--boltz2`) that pass
through unchanged. They are listed in `env/download_startup.sh:show_help` but
-not in the Python argparse — the bash script accepts them directly.
+not in the Python argparse — they still work because of the `sys.argv[2:]`
+passthrough.
| Passthrough flag | Destination | Approx size |
|------------------|-------------|-------------|
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-setup/skill-card.md b/skills/bionemo-agent-toolkit/skills/complexa-setup/skill-card.md
new file mode 100644
index 00000000..41ca079e
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/complexa-setup/skill-card.md
@@ -0,0 +1,68 @@
+## Description:
+Performs first-time setup for Proteina-Complexa — driving `complexa init`, `complexa download`, and `complexa validate env` end to end, editing required `.env` keys, selecting the UV or Docker runtime, and emitting a replayable setup artifact.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers and computational biologists making a fresh Proteina-Complexa checkout runnable — verifying GPU preflight, configuring `.env`, and installing model weights (Complexa, AF2, RF3, ProteinMPNN, LigandMPNN, ESM2, ESMFold). This is the first skill to run on a new clone; every other `complexa-*` skill depends on it.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): Credentials for model-weight sources, as required by the individual checkpoints being downloaded
+
+* `complexa` CLI installed (`pip install -e .`)
+* bash 4+
+* `nvidia-smi` optional at setup time; a CUDA GPU is required for the design and evaluation skills
+* Substantial disk for model checkpoints
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: The skill edits the user's `.env` file, which holds paths and may hold credentials; a mis-edit could break the environment or expose values in an agent transcript.
+Mitigation: The skill edits only the required keys and reports what changed; `.env` is git-ignored in this repository and must never be committed. Users should treat agent transcripts as sensitive.
+
+Risk: Model-weight downloads are large and fetch third-party checkpoints (AF2/ColabDesign, RF3, ESMFold, ProteinMPNN, LigandMPNN) whose licenses differ from this repository's.
+Mitigation: `complexa download --status` reports what is present before fetching; users are responsible for reviewing and complying with each checkpoint's upstream license terms.
+
+Risk: A partially completed setup produces confusing failures much later, inside long-running design jobs.
+Mitigation: `complexa validate env` runs as an explicit final step so environment problems surface at setup time.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- Related skills: `complexa-target`, `complexa-design`, `complexa-evaluate-pdbs`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Analysis, Files, Configuration instructions]
+**Output Format:** [Markdown setup report; edited `.env`; downloaded checkpoint files; replayable setup artifact]
+**Output Parameters:** [1D — per-check pass/fail status, resolved runtime, installed model inventory]
+**Other Properties Related to Output:** [Side effects: writes `.env`, downloads model weights to disk]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering init, weight download and status reporting, `.env` configuration, and environment validation — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-sweep/SKILL.md b/skills/bionemo-agent-toolkit/skills/complexa-sweep/SKILL.md
index a692d614..f053d10b 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-sweep/SKILL.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-sweep/SKILL.md
@@ -198,7 +198,7 @@ Alongside the manifest, save the ranked `sweep_summary.csv` from Step 6 to `./sw
Total GPU-time for a sweep = `N_configs × per_run_GPU_time`. A single `search_binder_local_pipeline` run on one A100 is roughly 30–90 min (binder length + nsteps dependent). A 4-axis × 4-value sweep = 256 configs × ~60 min = ~256 GPU-hours — at that scale, plan on a multi-GPU host with the Step-4 sharding pattern.
-Refer to the shared hardware reference for the per-run baseline + VRAM minima.
+Refer to [`.claude/skills/_shared/reference/hardware.md`](../_shared/reference/hardware.md) for the per-run baseline + VRAM minima.
## Troubleshooting
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/SWEEP.md b/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/SWEEP.md
index c459c8f9..6dbf2e8b 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/SWEEP.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/SWEEP.md
@@ -3,10 +3,10 @@
How to run parameter sweeps and override experiment settings without modifying source code.
> **Documentation Map**
-> - Running a design? See the Inference Guide.
-> - Tuning YAML configs? See the Configuration Guide.
-> - Understanding metrics? See the Evaluation Guide.
-> - Search metadata? See the Search Metadata notes.
+> - Running a design? See [Inference Guide](INFERENCE.md)
+> - Tuning YAML configs? See [Configuration Guide](CONFIGURATION_GUIDE.md)
+> - Understanding metrics? See [Evaluation Guide](EVALUATION_METRICS.md)
+> - Search metadata? See [Search Metadata](SEARCH_METADATA.md)
## Overview
@@ -276,7 +276,7 @@ orchestration. It does not change how individual modules consume configs.
| `--infer_config_name search_binder` | `--config_name search_binder_pipeline` |
| `generate_binder_inference_configs.py` | `generate_inference_configs.py` |
| Hardcoded `ALPHA_PROTEO_TARGETS` list | Removed (use sweep or override) |
-| Manual removal of `configs/inference_configs` | Automatic: temp dir + staging (concurrent-safe) |
+| `rm -rf configs/inference_configs` | Automatic: temp dir + staging (concurrent-safe) |
## Tests
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/sweep_axes.md b/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/sweep_axes.md
index 0d962231..693d8387 100644
--- a/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/sweep_axes.md
+++ b/skills/bionemo-agent-toolkit/skills/complexa-sweep/reference/sweep_axes.md
@@ -1,6 +1,6 @@
# Sweep Axes Reference
-Catalogue of swept keys for Proteina-Complexa design pipelines, grouped by pipeline stage. Every key is a config dot-path you can put in a `configs/sweeps/*.yaml` file as a sweep axis (list value) or as an `--override KEY=VAL` pin.
+Catalogue of swept keys for Proteina-Complexa design pipelines, grouped by pipeline stage. Every key is a Hydra dot-path you can put in a `configs/sweeps/*.yaml` file as a sweep axis (list value) or as an `--override KEY=VAL` pin.
Defaults are read from `configs/pipeline/binder/binder_generate.yaml`, `configs/pipeline/binder/binder_evaluate.yaml`, and `configs/pipeline/model_sampling.yaml`. Verify against your actual base pipeline config before launching — different pipelines (e.g. `search_ligand_binder_local_pipeline`, `search_ame_local_pipeline`) inherit different defaults.
@@ -82,7 +82,7 @@ Annotated example based on `configs/sweeps/example.yaml`:
```yaml
# --- Sweep axes (lists, cartesian-producted) ---
-# Each key is a config dot-path. Each list value becomes one dimension.
+# Each key is a Hydra dot-path. Each list value becomes one dimension.
# Total configs = product of list lengths. Here 2 × 2 = 4.
generation.search.beam_search.beam_width:
- 2
@@ -140,7 +140,7 @@ For an irregular set of `(key1, key2)` pairs (not a full cartesian product), the
| Column | Source | Notes |
|---|---|---|
| `config_id` | The index in `inf_{idx}_{run_name}.yaml` | 0-based, sequential, set by `apply_sweeper_and_save_configs`. |
-| `` (one per axis) | Read from the per-config `inf_*.yaml` at the swept config path | Strip the dot-path to a short column header (e.g. `beam_width`). |
+| `` (one per axis) | Read from the per-config `inf_*.yaml` at the swept Hydra path | Strip the dot-path to a short column header (e.g. `beam_width`). |
| `n_samples` | `len(results_csv)` | Rows in the analyze CSV for this config. |
| `success_rate` | `mean(passes_filter)` if column present, else thresholded `mean((i_pae < 10) & (i_plddt > 0.7) & (sc_rmsd < 2.0))` | Confirm thresholds with the user. |
| `mean_i_pae` | `i_pae.mean()` | Lower = better. AF2 interface PAE. |
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-sweep/skill-card.md b/skills/bionemo-agent-toolkit/skills/complexa-sweep/skill-card.md
new file mode 100644
index 00000000..9cd61b24
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/complexa-sweep/skill-card.md
@@ -0,0 +1,75 @@
+## Description:
+Runs parameter sweeps over a Proteina-Complexa design pipeline — authoring sweeper YAML, expanding cartesian-product configurations, and ranking per-configuration results for hyperparameter scans and Pareto search over generation, reward, and evaluation knobs.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers and method developers tuning a design pipeline — scanning beam width, step count, temperature, or reward weights; ablating reward components; or trading binder quality against wall-clock. This is the only skill that owns sweeper YAML authoring and per-configuration result ranking.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* `complexa-setup` completed and a target registered (`complexa-target`)
+* CUDA GPU meeting the `complexa-design` requirements, for each configuration in the sweep
+* Disk and GPU-hours proportional to the size of the cartesian product
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: This is the highest-cost skill in the family. A cartesian product expands multiplicatively, so a sweep specified in one short instruction can launch dozens of full design campaigns and consume very large amounts of GPU time or cloud spend.
+Mitigation: The skill expands and reports the configuration list before execution, so the user sees the run count before committing. Users should start with a small grid and confirm cost before widening.
+
+Risk: Ranking configurations on a stochastic pipeline can select a configuration that merely got a lucky seed rather than one that is genuinely better.
+Mitigation: Results are reported per configuration rather than as a single winner, so users can judge whether differences exceed run-to-run variance. Seeds should be fixed for like-for-like comparison.
+
+Risk: Sweeping on a small or unrepresentative target set overfits hyperparameters to that target, and the choice may not transfer.
+Mitigation: Per-configuration results are retained so users can re-examine the ranking against a held-out target.
+
+Risk: A large sweep writes many output directories and can exhaust disk mid-run, losing partially completed configurations.
+Mitigation: Outputs are written under explicit per-configuration paths; users should size storage against the expanded run count.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- `reference/sweep_axes.md` in this skill directory — the sweepable parameter axes
+- `configs/sweeps/` — example sweep definitions
+- Related skills: `complexa-design`, `complexa-target`, `complexa-evaluate-pdbs`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Sweeper YAML; per-configuration design outputs and result CSVs; Markdown ranking table]
+**Output Parameters:** [2D — one row per configuration, columns for the swept parameters and resulting metrics]
+**Other Properties Related to Output:** [Rankings reflect in-silico metrics on a stochastic pipeline; differences within run-to-run variance should not be treated as meaningful.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering sweeper YAML authoring, cartesian-product expansion, sweep execution, and per-configuration ranking — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Sweeps generate novel protein sequences and structures at scale. Users are responsible for screening designed sequences before synthesis, and for using the skill consistent with applicable biosecurity norms, biosafety review processes, and export-control obligations.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/complexa-target/skill-card.md b/skills/bionemo-agent-toolkit/skills/complexa-target/skill-card.md
new file mode 100644
index 00000000..e00351b6
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/complexa-target/skill-card.md
@@ -0,0 +1,70 @@
+## Description:
+Adds, registers, edits, lists, shows, and validates Proteina-Complexa design targets — protein binder, ligand binder, and AME / enzyme-scaffolding — and is the only skill that writes the three target dictionary files.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA
+
+### License/Terms of Use:
+This repository contains multiple components under different licenses; see the [`LICENSE`](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/blob/HEAD/LICENSE) in the source repository.
+
+## Use Case:
+Protein designers defining what to design against — registering a target structure, chain specification, hotspot residues, and binder length range before running `complexa-design`. Also covers `complexa validate target` and questions about chain-spec syntax and where hotspots live.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `complexa` CLI installed (`pip install -e .`)
+* `complexa-setup` completed
+* A target structure (PDB/mmCIF) or SMILES for ligand-binder targets
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: This skill has exclusive write access to `configs/targets/{,ligand_}targets_dict.yaml` and `configs/design_tasks/ame_dict_v2.yaml`; a malformed edit could corrupt target definitions shared across a team's design runs.
+Mitigation: `complexa validate target` runs as an explicit validation path, and the skill is the single documented owner of those files so edits are not made ad hoc from multiple places.
+
+Risk: Incorrect hotspot residue numbering — a common failure when structure numbering differs from sequence numbering — silently redirects design to the wrong surface, wasting an entire downstream design campaign.
+Mitigation: The skill validates targets before use and supports structure-confirmed hotspot specification rather than accepting bare residue indices without checking.
+
+Risk: Target definitions may be derived from third-party structures (e.g. RCSB PDB entries) whose terms of use apply to downstream work.
+Mitigation: Users are responsible for confirming the provenance and licensing of any structure they register.
+
+## Reference(s):
+- [Proteina-Complexa repository](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa)
+- [RCSB Protein Data Bank](https://www.rcsb.org/) — common source of target structures
+- Related skills: `complexa-setup`, `complexa-design`, `complexa-sweep`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [YAML target dictionary entries; Markdown summary of registered targets]
+**Output Parameters:** [1D — target identifier, chain spec, hotspot residues, binder length range]
+**Other Properties Related to Output:** [Side effect: writes to the repository's target dictionary configuration files]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+Not yet present on this branch. A co-located `evals/evals.json` with 4 tasks — covering target registration, listing/showing, chain and hotspot specification, and validation — is introduced by [PR #57](https://github.com/NVIDIA-BioNeMo/Proteina-Complexa/pull/57) (branch `aggregator-compat`) and lands on `dev` when that merges.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+5391310 (source: git SHA, committed 2026-07-16)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Target selection determines what a downstream design campaign is aimed at. Users are responsible for ensuring their design targets are consistent with applicable biosecurity norms and export-control obligations.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-add-cmim-pretrain/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-add-cmim-pretrain/skill-card.md
new file mode 100644
index 00000000..c25a6984
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-add-cmim-pretrain/skill-card.md
@@ -0,0 +1,77 @@
+## Description:
+Converts a grover_base checkpoint into a hybrid checkpoint by adding a randomly-initialized cMIM decoder and latent distribution, then continues pretraining on the user's corpus in hybrid (vocab + contrast) mode.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML research engineers who want the cMIM contrastive objective on top of an existing grover_base KERMT checkpoint without retraining from scratch. Functionally `kermt-continue-pretrain` with a one-time checkpoint-conversion step prepended.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU (multi-GPU supported via DDP)
+* A grover_base checkpoint (encoder-only, or encoder + vocab heads)
+* A pretraining corpus CSV
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: The newly added cMIM decoder and latent distribution are randomly initialized, so the converted checkpoint performs worse than its source until sufficient hybrid pretraining has run — a checkpoint taken too early is silently degraded.
+Mitigation: The conversion step is explicitly separated from the training step, and `kermt-monitor` exposes validation loss so users can confirm convergence before adopting the result.
+
+Risk: Continued pretraining is a long-running, multi-GPU workload that a single agent instruction can start, potentially consuming days of GPU time.
+Mitigation: Runs launch detached with a run manifest; `kermt-monitor` provides progress visibility and the container identifiers needed to terminate early.
+
+Risk: Supplying a checkpoint that is not grover_base (e.g. already cmim or hybrid) would produce an invalid conversion.
+Mitigation: The skill validates the source checkpoint type before conversion.
+
+Risk: Conversion and data preparation write new checkpoint and shard/vocab/feature artifacts that can overwrite prior output.
+Mitigation: Artifacts are written under an explicit run/output path; the source checkpoint is not modified in place.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/run_pretrain_local.py` — extended usage examples
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-continue-pretrain`, `kermt-pretrain-scratch`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Converted hybrid checkpoint; subsequent training checkpoints; shard/vocab/feature artifacts; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, converted checkpoint path, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering source-checkpoint validation, cMIM conversion, corpus preparation, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models produced by this skill inherit the composition and biases of the user's pretraining corpus. Downstream predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-continue-pretrain/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-continue-pretrain/skill-card.md
new file mode 100644
index 00000000..50489db5
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-continue-pretrain/skill-card.md
@@ -0,0 +1,77 @@
+## Description:
+Continues pretraining from an existing KERMT checkpoint — validating the checkpoint and corpus, preparing shard/vocab/feature artifacts, and launching `pretrain_ddp.py` inside the KERMT container with `--pretrain_mode` auto-dispatched from the checkpoint type.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML engineers adapting a KERMT foundation model to a domain-specific molecular corpus — for example an in-house compound collection — before task finetuning, without discarding the representations already learned.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU (multi-GPU supported via DDP)
+* An existing KERMT checkpoint (grover_base vocab-only, cmim, or hybrid)
+* A pretraining corpus CSV
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Continued pretraining is a long-running, multi-GPU workload that a single agent instruction can start, potentially consuming days of GPU time and substantial cloud spend.
+Mitigation: Runs launch detached with a run manifest; `kermt-monitor` provides progress visibility and the container identifiers needed to terminate early.
+
+Risk: Selecting the wrong `--pretrain_mode` for a checkpoint would train against the wrong objective and silently waste the entire run.
+Mitigation: The skill auto-dispatches `--pretrain_mode` from the detected checkpoint type rather than relying on the user to specify it.
+
+Risk: Data preparation writes shard, vocabulary, and feature artifacts that can be large and can overwrite prior preparation output.
+Mitigation: Preparation writes under an explicit run/output path supplied by the user.
+
+Risk: Continued pretraining on a narrow corpus can degrade general-purpose representations (catastrophic forgetting) in ways not visible until downstream finetuning.
+Mitigation: The original checkpoint is not modified in place; users should retain it and compare downstream task performance before adopting the continued-pretrain checkpoint.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/run_pretrain_local.py` — extended usage examples
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-pretrain-scratch`, `kermt-add-cmim-pretrain`, `kermt-finetune`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Model checkpoint files; shard/vocab/feature artifacts; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, resolved pretrain mode, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+5 evaluation tasks defined in `evals/evals.json`, covering checkpoint validation, corpus validation, data preparation, pretrain-mode dispatch, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models produced by this skill inherit the composition and biases of the user's pretraining corpus. Downstream predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-embed/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-embed/skill-card.md
new file mode 100644
index 00000000..38be64d7
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-embed/skill-card.md
@@ -0,0 +1,69 @@
+## Description:
+Extracts per-molecule embeddings from any encoder-bearing KERMT checkpoint (grover_base / cmim / hybrid / finetuned), writing one `.npy` per readout type plus `canonical_smiles.npy` and `validity.npy`.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML engineers and cheminformaticians who need fixed-length molecular representations from a KERMT encoder to feed a downstream model, clustering step, or similarity search, without training a task head.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU
+* Any encoder-bearing KERMT checkpoint
+* A SMILES input CSV (featurization happens on the fly — no precomputed features required)
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Embeddings from different checkpoints or readout types are not comparable, and mixing them in a downstream model produces silently meaningless results.
+Mitigation: The skill writes each readout type to a separately named `.npy` and emits `canonical_smiles.npy` alongside, so provenance and row alignment are explicit.
+
+Risk: Invalid SMILES rows would misalign embeddings against the caller's original input ordering.
+Mitigation: The skill emits `validity.npy`, letting the caller filter or realign rows deterministically.
+
+Risk: Large input libraries can produce embedding arrays of substantial size and consume significant disk.
+Mitigation: Outputs are written to a user-specified directory; users should size storage for the molecule count and embedding dimensionality before running.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `task/extract_embeddings.py` — the underlying extraction entry point
+- Related skills: `kermt-setup`, `kermt-finetune`, `kermt-infer`
+
+## Skill Output:
+**Output Type(s):** [Files]
+**Output Format:** [NumPy `.npy` arrays — one per readout type (atom_from_atom, bond_from_atom, atom_from_bond, bond_from_bond), plus `canonical_smiles.npy` and `validity.npy`]
+**Output Parameters:** [2D — one row per input molecule, one column per embedding dimension]
+**Other Properties Related to Output:** [Row order corresponds to the input CSV; `validity.npy` identifies rows whose SMILES failed to parse]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+5 evaluation tasks defined in `evals/evals.json`, covering checkpoint compatibility, readout selection, and output artifact production.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-finetune/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-finetune/skill-card.md
new file mode 100644
index 00000000..a9db2f87
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-finetune/skill-card.md
@@ -0,0 +1,78 @@
+## Description:
+Finetunes a pretrained KERMT encoder on a labeled CSV — validating the input checkpoint and dataset, preparing features and optional splits, then launching `main.py finetune` inside the KERMT container as a detached, hours-scale run.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+Computational chemists and ML engineers adapting a pretrained KERMT encoder (grover_base / cmim / hybrid) to their own labeled molecular property dataset — for example an in-house ADMET assay panel — before running predictions with `kermt-infer`.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU
+* A pretrain checkpoint (grover_base, cmim, or hybrid)
+* A labeled CSV with SMILES and one or more target columns
+* Hyperparameters default from `agent/config/defaults_finetune.json`, overridable per flag
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Finetuning is an hours-scale GPU workload that a single agent instruction can start, consuming substantial GPU-hours or cloud spend.
+Mitigation: Runs launch detached with a run manifest, and `kermt-monitor` gives the user continuous visibility and the container identifiers needed to terminate early.
+
+Risk: Supplying a finetuned checkpoint instead of a pretrain checkpoint would produce an invalid training configuration.
+Mitigation: The skill validates the checkpoint type before launching and rejects non-pretrain checkpoints.
+
+Risk: A poorly split dataset (e.g. random splits on congeneric series) yields optimistic validation metrics that do not generalize.
+Mitigation: The skill exposes explicit split handling rather than defaulting silently; users remain responsible for choosing a split strategy appropriate to their chemistry.
+
+Risk: Training writes checkpoints and logs into a user-specified directory and can overwrite artifacts from a previous run.
+Mitigation: Outputs are written under an explicit run directory; users should use distinct output paths per experiment.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`; users should confirm their data-handling policy before enabling it.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/config/defaults_finetune.json` — default hyperparameters
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-infer`, `kermt-embed`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Model checkpoint files; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, configured hyperparameters, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes. Use `kermt-monitor` for progress.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+5 evaluation tasks defined in `evals/evals.json`, covering checkpoint validation, dataset validation, data preparation, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models finetuned with this skill inherit the biases and coverage limits of the user's training data. Resulting predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-infer/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-infer/skill-card.md
new file mode 100644
index 00000000..443f191e
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-infer/skill-card.md
@@ -0,0 +1,74 @@
+## Description:
+Runs molecular property predictions with a finetuned KERMT checkpoint on a SMILES-only CSV, validating that the checkpoint carries task FFN heads, preparing rdkit_2d features, and launching `main.py predict` inside the KERMT container.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+Computational chemists and drug-discovery teams scoring a library of candidate molecules for ADMET or other molecular properties using a KERMT model they have already finetuned. Not for use with pretrain checkpoints — the skill refuses those and redirects to `kermt-finetune`.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU
+* A finetuned KERMT checkpoint containing task FFN heads
+* A SMILES-only input CSV
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: Predictions are computational estimates and may be applied outside the chemical space the model was finetuned on, producing confidently wrong property values for novel scaffolds.
+Mitigation: Users must treat outputs as hypotheses requiring experimental validation, and should check that input chemistry resembles the finetuning set before acting on predictions.
+
+Risk: Supplying a pretrain checkpoint instead of a finetuned one would yield meaningless outputs.
+Mitigation: The skill validates the checkpoint for task FFN heads before running and refuses pretrain checkpoints with an explicit redirect to `kermt-finetune`.
+
+Risk: Malformed or non-parseable SMILES silently reduce the effective prediction set.
+Mitigation: The skill runs a data-preparation and cleaning step that reports invalid rows before inference.
+
+Risk: The skill writes prediction outputs into a user-specified directory and can overwrite prior results.
+Mitigation: Outputs are written under an explicit output path supplied by the user; no files outside that path are modified.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- [RDKit documentation](https://www.rdkit.org/docs/) — `rdkit_2d` descriptor featurization
+- Related skills: `kermt-finetune` (produces the required checkpoint), `kermt-embed`
+
+## Skill Output:
+**Output Type(s):** [Analysis, Files]
+**Output Format:** [CSV of per-molecule predictions; Markdown summary]
+**Output Parameters:** [2D — one row per input molecule, one column per predicted task]
+**Other Properties Related to Output:** [Predictions are model estimates, not measurements, and are not calibrated probabilities of experimental outcome. Runs blocking, on a minutes-scale timeframe.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering checkpoint validation, CSV validation, feature preparation, and the predict invocation.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Molecular property predictions produced by this skill are computational hypotheses for research and development workflows. They must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-monitor/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-monitor/skill-card.md
new file mode 100644
index 00000000..84e12f12
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-monitor/skill-card.md
@@ -0,0 +1,70 @@
+## Description:
+Reports progress for a detached KERMT run by reading `run.json`, querying Docker for container state, tailing the pretrain/finetune log, and parsing progress lines (epoch, step, validation loss).
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML engineers running long KERMT pretraining or finetuning jobs who need to check status, spot divergence early, and decide whether to let a run continue or terminate it. This is the companion skill to every detached `kermt-*` training invocation.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* Docker
+* `jq`
+* A prior detached KERMT run that produced a `run.json`
+
+Note: unlike the training skills, this skill does not require a GPU.
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: A stale or missing `run.json` can cause the skill to report on the wrong run, or to report nothing while a job is in fact still consuming GPU-hours.
+Mitigation: The skill cross-checks `run.json` against live Docker container state rather than trusting the manifest alone.
+
+Risk: Log tailing surfaces run output into the agent transcript, which may include file paths or environment details.
+Mitigation: The skill reads only the pretrain/finetune log; users should treat agent transcripts as sensitive and avoid pasting credentials into run configuration.
+
+Risk: This skill is read-only and cannot stop a runaway job, so a user may assume monitoring implies control.
+Mitigation: The skill reports container identifiers so the user can terminate the run directly via Docker if needed.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/kermt_container.sh` — defines `kermt_run_detached`, the wrapper whose runs this skill observes
+- Related skills: `kermt-pretrain-scratch`, `kermt-continue-pretrain`, `kermt-finetune`
+
+## Skill Output:
+**Output Type(s):** [Analysis]
+**Output Format:** [Markdown status report]
+**Output Parameters:** [1D — container state, current epoch, current step, latest validation loss]
+**Other Properties Related to Output:** [Read-only; the skill makes no changes to the run or the host]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering run discovery, container-state reporting, and log progress parsing.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-pretrain-scratch/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-pretrain-scratch/skill-card.md
new file mode 100644
index 00000000..46705812
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-pretrain-scratch/skill-card.md
@@ -0,0 +1,77 @@
+## Description:
+Pretrains a fresh KERMT model from scratch on a user-provided corpus — building a new vocabulary, instantiating the model architecture from defaults, and launching `pretrain_ddp.py` inside the KERMT container with no starting checkpoint loaded.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+ML research engineers training a KERMT model from random initialization on a corpus sufficiently large and distinct that continued pretraining from an existing checkpoint is not appropriate. For most users, `kermt-continue-pretrain` is the better starting point.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: Optional
+Credential Type(s): API key — `WANDB_API_KEY` for optional Weights & Biases run tracking
+
+* `kermt-setup` completed (supplies the `kermt:latest` image)
+* Docker, NVIDIA Container Toolkit, CUDA-capable NVIDIA GPU (multi-GPU strongly recommended; DDP supported)
+* A large pretraining corpus CSV
+* Substantial disk for shard, vocabulary, and feature artifacts
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: This is the most expensive skill in the KERMT family — training from random initialization can consume days to weeks of multi-GPU time, and a single agent instruction can start it.
+Mitigation: Runs launch detached with a run manifest; `kermt-monitor` provides progress visibility and the container identifiers needed to terminate early. Users should confirm corpus scale justifies from-scratch training before invoking.
+
+Risk: Training from scratch on an insufficiently large corpus produces a model materially worse than the available pretrained checkpoints, with the cost discovered only after the run.
+Mitigation: The skill is documented as the exception path, with `kermt-continue-pretrain` as the recommended default; users should benchmark against an existing checkpoint before committing.
+
+Risk: A vocabulary built from the user's corpus is not interchangeable with vocabularies from other checkpoints, so resulting models are incompatible with checkpoints trained elsewhere.
+Mitigation: The new vocabulary is written alongside the checkpoint in the run directory, making the pairing explicit and auditable.
+
+Risk: Data preparation writes large shard/vocab/feature artifacts and can overwrite prior preparation output.
+Mitigation: Preparation writes under an explicit run/output path supplied by the user.
+
+Risk: When Weights & Biases tracking is enabled, run metadata is transmitted to a third-party service.
+Mitigation: W&B tracking is optional and off unless the user supplies `WANDB_API_KEY`.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- `agent/scripts/run_pretrain_local.py` — extended usage examples
+- Related skills: `kermt-setup`, `kermt-monitor`, `kermt-continue-pretrain`, `kermt-finetune`
+
+## Skill Output:
+**Output Type(s):** [Files, Analysis]
+**Output Format:** [Model checkpoint files; new vocabulary; shard/feature artifacts; training logs; `run.json` manifest; Markdown launch summary]
+**Output Parameters:** [1D — run identifier, container id, vocabulary path, model configuration, output paths]
+**Other Properties Related to Output:** [Detached execution: the skill returns after launch, not after training completes.]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering corpus validation, vocabulary construction, architecture instantiation, and detached launch.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+Models produced by this skill inherit the composition and biases of the user's pretraining corpus entirely, with no counterbalancing from prior pretraining. Downstream predictions are research hypotheses and must not be used as the sole basis for clinical, safety, or regulatory decisions.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/kermt-setup/skill-card.md b/skills/bionemo-agent-toolkit/skills/kermt-setup/skill-card.md
new file mode 100644
index 00000000..076d3238
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/kermt-setup/skill-card.md
@@ -0,0 +1,69 @@
+## Description:
+Bootstraps the KERMT agent environment — verifies host Docker and the NVIDIA Container Toolkit, builds the `kermt:latest` image from the repository Dockerfile if absent, and runs a GPU smoke test inside the container.
+
+This skill is ready for commercial/non-commercial use.
+
+## Owner
+NVIDIA BioNeMo
+
+### License/Terms of Use:
+Apache-2.0
+
+## Use Case:
+Computational chemists and ML engineers preparing a workstation or GPU node to run any `kermt-*` skill. Every other KERMT skill depends on this one; it is the first skill to invoke on a fresh clone.
+
+### Requirements/Dependencies:
+Requires API Key or External Credential: No
+Credential Type(s): None
+
+* Docker
+* NVIDIA Container Toolkit
+* CUDA-capable NVIDIA GPU
+* A local clone of the KERMT repository (supplies the Dockerfile)
+
+Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+
+### Deployment Geography for Use:
+Global
+
+## Known Risks and Mitigations:
+Risk: The skill builds a container image and runs GPU workloads, which consumes significant local disk and can take tens of minutes on a cold cache.
+Mitigation: The skill checks for an existing `kermt:latest` image and skips the build when one is present; the smoke test is short and read-only.
+
+Risk: Docker commands require elevated host privileges, and an agent running them has broad access to the host container runtime.
+Mitigation: The skill issues only build, run, and inspect commands against the KERMT image; users should keep their agent's command-approval gate enabled and review commands before execution.
+
+Risk: A partially configured host (driver/toolkit mismatch) can produce a container that starts but cannot see the GPU, causing confusing downstream failures in training skills.
+Mitigation: The GPU smoke test runs inside the container and fails loudly at setup time rather than deferring the error to a long-running job.
+
+## Reference(s):
+- [KERMT repository](https://github.com/NVIDIA-BioNeMo/KERMT)
+- [NVIDIA Container Toolkit documentation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/)
+- `agent/scripts/kermt_container.sh` — container entry points used by this skill
+
+## Skill Output:
+**Output Type(s):** [Analysis, Configuration instructions]
+**Output Format:** [Markdown status report with inline bash commands]
+**Output Parameters:** [1D — pass/fail status per environment check]
+**Other Properties Related to Output:** [Side effect: builds the `kermt:latest` Docker image on the host if it does not already exist]
+
+## Evaluation Agents Used:
+Target agents: `claude-code`, `codex`. NVSkills-Eval has not yet been run against this skill — see Evaluation Results.
+
+## Evaluation Tasks:
+4 evaluation tasks defined in `evals/evals.json`, covering environment verification, image build, and GPU smoke test paths.
+
+## Evaluation Metrics Used:
+Planned NVSkills-Eval dimensions: Security, Correctness, Discoverability, Effectiveness, Efficiency.
+
+## Evaluation Results:
+Pending. NVSkills-Eval has not been run for this skill; results and a `BENCHMARK.md` will be published when the evaluation pipeline runs.
+
+## Skill Version(s):
+b1c082c (source: git SHA, committed 2026-07-17)
+
+## Ethical Considerations:
+NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
+
+(For Release on NVIDIA Platforms Only)
+Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://www.nvidia.com/en-us/support/submit-security-vulnerability/).
diff --git a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/SKILL.md b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/SKILL.md
index 4406a54a..e9d22be6 100644
--- a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/SKILL.md
+++ b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/SKILL.md
@@ -1,26 +1,24 @@
---
name: nvmolkit-usage
description: >-
- Write code that calls the installed nvMolKit Python API for GPU-accelerated,
- batched RDKit-style operations - Morgan fingerprints, Tanimoto/cosine
- similarity, ETKDG conformer embedding, MMFF/UFF optimization, TFD, conformer
- RMSD, Butina clustering, and substructure search. Use when the user is
- importing `nvmolkit.*`, debugging an `nvmolkit` call, choosing between
- nvMolKit and RDKit for a batched cheminformatics workflow, or wiring nvMolKit
- results into a torch/numpy pipeline. Out of scope: building nvMolKit from
- source.
+ Use when writing or debugging nvMolKit Python code for GPU-accelerated RDKit
+ fingerprints, similarity, conformers, clustering, and molecular searches.
license: Apache-2.0
metadata:
+ author: Kevin Boyd (@scal444)
owner: Kevin Boyd (@scal444)
- risk_tier: skill
+ risk-tier: skill
+ tags: [cheminformatics, rdkit, cuda]
---
# nvMolKit usage
-## What nvMolKit is
+## Purpose
GPU-accelerated, batched implementations of common RDKit operations. APIs mirror RDKit where possible but are batch-oriented: they take lists of `rdkit.Chem.Mol` (or lists of fingerprints) and process them in parallel on one or more GPUs. nvMolKit links against RDKit at build time; inputs and outputs are real RDKit `Mol` objects.
+This skill covers the installed Python API. Building nvMolKit from source is out of scope.
+
## Where nvMolKit does well
Reach for nvMolKit when:
@@ -29,25 +27,39 @@ Reach for nvMolKit when:
- The metric is **throughput / total wall time across the batch**, not per-molecule latency.
- The same operation is **repeated identically** across the batch (fingerprinting a library, embedding/minimizing many conformers, bulk pairwise similarity), so the GPU stays saturated.
-Plain RDKit is usually the better choice for single-molecule one-offs or workflows that can't be expressed as a batch. nvMolKit is not meant to replace RDKit for those cases.
-
-## Runtime requirements
+## Requirements
- An NVIDIA GPU with compute capability 7.0 (V100) or higher
- A CUDA driver compatible with CUDA 12.6+.
- A working `torch` install with CUDA support (nvMolKit returns GPU tensors via `torch`'s CUDA array interface).
-If CUDA is unavailable, nvMolKit calls raise. There is no CPU fallback - if the user needs one, use RDKit directly for that path.
-
When helping with installation, make the user choose a PyTorch CUDA backend that the host driver supports before installing nvMolKit. nvMolKit's PyPI wheels are built with CUDA Toolkit 12.9 and depend on CUDA 12 runtime packages, but pip/uv can still select a CUDA 13 PyTorch wheel unless the install command says otherwise.
- Conda: prefer conda-forge `pytorch-gpu`; pin `cuda-version=12.6` or another CUDA version supported by the driver.
-- pip: send the user to the PyTorch install selector (`https://pytorch.org/get-started/locally/`) or previous-versions page (`https://pytorch.org/get-started/previous-versions/`) to install `torch` for a CUDA 12.x backend before installing nvMolKit.
+- pip: send the user to the [PyTorch install selector](https://pytorch.org/get-started/locally/) or [previous-versions page](https://pytorch.org/get-started/previous-versions/) to install `torch` for a CUDA 12.x backend before installing nvMolKit.
- uv: install nvMolKit with an explicit backend, e.g. `uv pip install --torch-backend=cu128 nvmolkit`.
-## Verify the install before writing real code
+## Inputs
+
+- Required: choose an operation and supply molecules or fingerprints from the user's code or molecular dataset. Parse SMILES with RDKit and reject failed parses (`None`).
+- Molecular operations use RDKit `Mol` objects. Add hydrogens for ETKDG; minimization and conformer comparisons need existing conformers.
+- Fingerprint similarity takes packed `AsyncGpuResult`, torch tensors, or NumPy arrays: one molecule per row, with `int32` or `uint32` words.
+- Optional: take conformer counts, fingerprint settings, cutoffs, output modes, and hardware options from the user's requested workflow; otherwise use the documented API defaults.
+
+## Limitations
-Run this once to confirm nvMolKit is importable and a GPU op works end to end:
+- CUDA is required; there is no CPU fallback. Use RDKit directly when CPU execution is needed.
+- Plain RDKit is usually preferable for single-molecule work or operations that cannot be batched.
+- ETKDG does not support custom bounds matrices, custom CPCI, coordinate maps, or separate-fragment embedding.
+- Substructure search does not support chirality-aware matching, enhanced stereochemistry, or other advanced RDKit `SubstructMatchParameters` options.
+
+## Instructions
+
+1. Run the smoke test below before writing nvMolKit code.
+2. Choose an API from the entry-point table and apply its input requirements.
+3. Handle its result as described below; synchronize asynchronous GPU results before host reads.
+
+### Verify the install before writing real code
```python
import nvmolkit
@@ -68,7 +80,7 @@ print("fps shape:", tuple(fps.shape), "dtype:", fps.dtype)
# Expected: shape (3, 32), dtype torch.int32 (1024 bits packed into 32 int32s per row)
```
-If this fails, point the user at the install guide on the docs site rather than guessing - see "Going deeper" below.
+If this fails, point the user at the [installation guide](https://nvidia-bionemo.github.io/nvMolKit/#installation) rather than guessing.
## Entry points
@@ -77,15 +89,16 @@ If this fails, point the user at the install guide on the docs site rather than
| Morgan fingerprints | `nvmolkit.fingerprints` | `MorganFingerprintGenerator(radius, fpSize).GetFingerprints(mols)` |
| Bulk Tanimoto / cosine similarity | `nvmolkit.similarity` | `crossTanimotoSimilarity(...)`, `crossCosineSimilarity(...)`, plus `*MemoryConstrained` variants for results too large to fit in GPU memory |
| ETKDG conformer embedding | `nvmolkit.embedMolecules` | `EmbedMolecules(molecules, params, confsPerMolecule, ...)` |
-| MMFF94 optimization (one-shot) | `nvmolkit.mmffOptimization` | `MMFFOptimizeMoleculesConfs(molecules, ...)` |
-| UFF optimization (one-shot) | `nvmolkit.uffOptimization` | `UFFOptimizeMoleculesConfs(molecules, ...)` |
-| Forcefield with custom options + constraints | `nvmolkit.batchedForcefield` | `MMFFBatchedForcefield(mols, properties=..., nonBondedThreshold=..., ignoreInterfragInteractions=..., hardwareOptions=...)`, `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`. Per-molecule view `ff[i]` exposes `add_distance_constraint`, `add_position_constraint`, `add_angle_constraint`, `add_torsion_constraint`. Methods: `.compute_energy()`, `.compute_gradients()`, `.minimize(maxIters, forceTol)` |
+| MMFF94 optimization (one-shot) | `nvmolkit.mmffOptimization` | `MMFFOptimizeMoleculesConfs(molecules, ..., minimizerKind=..., fireOptions=...)` |
+| UFF optimization (one-shot) | `nvmolkit.uffOptimization` | `UFFOptimizeMoleculesConfs(molecules, ..., minimizerKind=..., fireOptions=...)` |
+| Forcefield with custom options + constraints | `nvmolkit.batchedForcefield` | `MMFFBatchedForcefield(mols, properties=..., nonBondedThreshold=..., ignoreInterfragInteractions=..., hardwareOptions=...)`, `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`. Per-molecule view `ff[i]` exposes `add_distance_constraint`, `add_position_constraint`, `add_angle_constraint`, `add_torsion_constraint`. Methods: `.compute_energy()`, `.compute_gradients()`, `.minimize(maxIters, forceTol, minimizerKind=..., fireOptions=...)` |
| Pairwise conformer RMSD | `nvmolkit.conformerRmsd` | `GetConformerRMSMatrix(mol)`, `GetConformerRMSMatrixBatch(mols)` |
| Torsion Fingerprint Deviation (TFD) | `nvmolkit.tfd` | `GetTFDMatrix(mol)`, `GetTFDMatrices(mols)` |
-| Butina clustering | `nvmolkit.clustering` | `butina(distance_matrix, cutoff)` (precomputed matrix), `fused_butina(fingerprints, cutoff)` (memory-efficient, on-the-fly) |
+| Butina clustering | `nvmolkit.clustering` | `butina(distance_matrix, cutoff)` (precomputed matrix), `fused_butina(fingerprints, cutoff)` (memory-efficient, on-the-fly); both support explicit RDKit and device output modes |
| Substructure search | `nvmolkit.substructure` | `hasSubstructMatch`, `countSubstructMatches`, `getSubstructMatches` |
+| Maximum common substructure | `nvmolkit.mcs` | `findMCS(mols, ...)` for all pairs, explicit pairs, or two paired molecule lists |
| Hardware tuning (batch size, GPU IDs) | `nvmolkit.types` | `HardwareOptions(...)` passed to ETKDG / MMFF / UFF |
-| Optional autotuning of `HardwareOptions` | `nvmolkit.autotune` | `tune_embed_molecules`, `tune_mmff_optimize`, `tune_uff_optimize`, `tune_batched_forcefield`. Requires the `optuna` package |
+| Optional autotuning | `nvmolkit.autotune` | `tune_embed_molecules`, `tune_mmff_optimize`, `tune_uff_optimize`, `tune_batched_forcefield`, `tune_substructure`, `tune_mcs`. Requires the `optuna` package |
## Result types and execution model
@@ -111,7 +124,7 @@ APIs that take a `stream` argument:
- `butina`, `fused_butina`
- `GetConformerRMSMatrix`, `GetConformerRMSMatrixBatch`
-Other APIs (ETKDG, MMFF/UFF optimization, TFD, substructure search) are synchronous to the caller — no stream plumbing needed.
+Other APIs (ETKDG, MMFF/UFF optimization, TFD, substructure search, MCS) are synchronous to the caller — no stream plumbing needed.
Typical pattern:
@@ -144,41 +157,26 @@ Used by ETKDG embedding and MMFF/UFF optimization (one-shot and `BatchedForcefie
The default mode (`CoordinateOutput.RDKIT_CONFORMERS`) still writes optimized coordinates back into each `Mol` and returns Python lists of energies/convergence flags. Reach for `CoordinateOutput.DEVICE` when chaining downstream GPU work (e.g. ETKDG → MMFF → similarity scoring) without host round-trips.
-## Configuration
-
-Two configuration objects expose the GPU/CPU knobs.
+### `MCSBatchResult`
-### `HardwareOptions` (ETKDG, MMFF, UFF)
+`findMCS` is synchronous and returns an `MCSBatchResult` backed by CPU NumPy
+arrays. Results are always flat: `result[k]` (or `result.get_result(k)`)
+materializes the result at pair position `k`, not generally the result for
+molecule `k`. Use `result.pairs[k]` to identify that pair. In `all_pairs` mode
+these are the generated pairs over `mols`; in `pairs` mode they exactly preserve
+the supplied pair sequence; in `paired_lists` mode item `k` compares `mols[k]`
+with `mols_b[k]`, while `result.pairs[k]` uses the combined-table indices
+`(k, len(mols) + k)`. Each `MCSResult` has `pair`, `num_atoms`, `num_bonds`,
+`canceled`, `atom_mapping`, and `bond_mapping`; the two columns of each mapping
+index the first and second molecule of that result pair, respectively.
-`from nvmolkit.types import HardwareOptions`. Passed via `hardwareOptions=` to `EmbedMolecules`, `MMFFOptimizeMoleculesConfs`, `UFFOptimizeMoleculesConfs`, and the `BatchedForcefield` constructors. Every field has an "auto" sentinel; the defaults are usually fine.
-
-| Field | Type | Default | Meaning |
-|---|---|---|---|
-| `preprocessingThreads` | int | `-1` (all visible CPUs) | CPU threads for preprocessing |
-| `batchSize` | int | `-1` (auto-tuned) | Number of conformers per GPU batch |
-| `batchesPerGpu` | int | `-1` (auto) | Concurrent batches per GPU; must be `>0` or `-1` |
-| `gpuIds` | `list[int]` | `[]` (all visible GPUs) | Specific device ordinals to target |
-
-Passing a `gpuIds` entry for a device that isn't visible raises `RuntimeError: invalid device ordinal`. For finding good values automatically across a representative sample, see `nvmolkit.autotune` (requires the `optuna` extra); each `tune_*` function returns a `TuneResult` whose `best_config` is a fully-populated `HardwareOptions` ready to pass back into the real call.
-
-`HardwareOptions` round-trips through `to_dict()` / `from_dict()` for persisting tuned configs to disk.
-
-### `SubstructSearchConfig` (substructure search)
-
-`from nvmolkit.substructure import SubstructSearchConfig`. Passed via `config=` to `hasSubstructMatch`, `countSubstructMatches`, and `getSubstructMatches`.
-
-| Field | Type | Default | Meaning |
-|---|---|---|---|
-| `batchSize` | int | `1024` | (target, query) pairs per GPU batch |
-| `workerThreads` | int | `-1` (auto) | GPU runner threads per GPU |
-| `preprocessingThreads` | int | `-1` (auto) | CPU threads for preprocessing |
-| `maxMatches` | int | `0` (unlimited) | Max matches returned per (target, query) pair |
-| `uniquify` | bool | `False` | Drop duplicate matches that differ only in atom enumeration order |
-| `gpuIds` | `list[int] \| None` | `None` (current device only) | Specific device ordinals to target |
+## Configuration
-Substructure search currently does not support chirality-aware matching, enhanced stereochemistry, or other advanced RDKit `SubstructMatchParameters` options.
+For ETKDG, forcefield, substructure, or MCS tuning, read the
+[advanced configuration reference](references/advanced-usage.md#configuration).
+It lists configuration fields, defaults, GPU selection, and autotuning APIs.
-## Recipes
+## Examples
### Morgan fingerprints + bulk Tanimoto similarity
@@ -210,7 +208,6 @@ from nvmolkit.embedMolecules import EmbedMolecules
mols = [AddHs(MolFromSmiles(smi)) for smi in ["C1CCCCC1", "C1CCCCC2CCCCC12", "COO"]]
params = ETKDGv3()
-params.useRandomCoords = True
EmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)
@@ -218,7 +215,7 @@ for mol in mols:
print(mol.GetNumConformers())
```
-Inputs are `list[Mol]`, sanitized and with hydrogens added (`AddHs`). Conformers are added in-place. `params.useRandomCoords` must be `True` - nvMolKit's ETKDG only supports random-coord initialization. A handful of niche `EmbedParameters` options are not supported (bounds matrices, custom CPCI, coord maps, separate-fragment embedding); the Features section of the docs site lists the full restrictions.
+Inputs are sanitized `list[Mol]` with hydrogens added (`AddHs`). Conformers are added in-place; see Limitations for unsupported embedding options.
### MMFF94 minimization of a batch of conformers
@@ -229,7 +226,7 @@ from nvmolkit.embedMolecules import EmbedMolecules
from nvmolkit.mmffOptimization import MMFFOptimizeMoleculesConfs
mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCN", "c1ccccc1"]]
-params = ETKDGv3(); params.useRandomCoords = True
+params = ETKDGv3()
EmbedMolecules(mols, params, confsPerMolecule=5)
energies = MMFFOptimizeMoleculesConfs(mols, maxIters=500)
@@ -239,6 +236,12 @@ for mol, mol_energies in zip(mols, energies):
Inputs are `list[Mol]` with conformers already populated (typically by ETKDG, RDKit's `EmbedMultipleConfs`, or a prior nvMolKit call). Coordinates are updated in place; the return is `list[list[float]]` of optimized energies aligned with the input molecule order and conformer index. UFF is identical in shape: swap in `from nvmolkit.uffOptimization import UFFOptimizeMoleculesConfs`.
+BFGS is the default minimizer. To use FIRE, pass `minimizerKind="FIRE"`;
+optionally customize it with a
+`nvmolkit.types.FireOptions` instance through `fireOptions=`. The one-shot MMFF
+and UFF functions and both batched-forcefield `.minimize()` methods accept the
+same selector.
+
If any input molecule is `None` or lacks MMFF/UFF atom types, the call raises `ValueError`. The exception's `args[1]` is a dict with keys `"none"` and `"no_params"` listing the offending indices - useful for filtering a noisy input set.
### Conformer RMSD and Butina clustering
@@ -247,7 +250,7 @@ If any input molecule is `None` or lacks MMFF/UFF atom types, the call raises `V
import torch
from rdkit import Chem
from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
-from nvmolkit.clustering import butina
+from nvmolkit.clustering import OutputMode, butina
from nvmolkit.conformerRmsd import GetConformerRMSMatrixBatch
mols = [Chem.AddHs(Chem.MolFromSmiles(smi)) for smi in ["CCCCCC", "c1ccccc1"]]
@@ -262,52 +265,91 @@ condensed = GetConformerRMSMatrixBatch(heavy_mols)
# Butina expects a square distance matrix, so request square GPU tensors.
square = GetConformerRMSMatrixBatch(heavy_mols, output_format="square")
-clusters = [butina(distance_matrix, cutoff=0.5).torch() for distance_matrix in square]
+results = [
+ butina(distance_matrix, cutoff=0.5, output=OutputMode.DEVICE)
+ for distance_matrix in square
+]
torch.cuda.synchronize()
-for mol_clusters in clusters:
- print(mol_clusters.cpu().tolist())
+for result in results:
+ print(result.cluster_ids.torch().cpu().tolist())
```
-`GetConformerRMSMatrix(mol)` and `GetConformerRMSMatrixBatch(mols)` default to `output_format="condensed"`, returning `AsyncGpuResult` objects that wrap RDKit-style flat vectors of length `N * (N - 1) // 2`. Use `output_format="square"` when chaining into `butina()` or any other API that expects an `N x N` distance matrix. Both forms live on the GPU; call `.numpy()` on condensed results or synchronize before moving square tensors to the CPU.
+Both Butina functions return GPU-resident results by default:
-### Custom forcefield options + constraints (`BatchedForcefield`)
+- The default, `output=OutputMode.DEVICE`, returns cluster IDs, centroids, and sizes.
+- `output=OutputMode.RDKIT` returns RDKit cluster tuples on the host. The first element of each cluster is its centroid.
+
+The device output fields are `AsyncGpuResult` objects. Use `.torch()` to access
+their CUDA tensors without a host copy or `.numpy()` to synchronize and copy a
+field to the host.
-Reach for `MMFFBatchedForcefield` / `UFFBatchedForcefield` instead of the one-shot `MMFFOptimizeMoleculesConfs` / `UFFOptimizeMoleculesConfs` when you need any of:
+`GetConformerRMSMatrix(mol)` and `GetConformerRMSMatrixBatch(mols)` default to `output_format="condensed"`, returning `AsyncGpuResult` objects that wrap RDKit-style flat vectors of length `N * (N - 1) // 2`. Use `output_format="square"` when chaining into `butina()` or any other API that expects an `N x N` distance matrix. Both forms live on the GPU; call `.numpy()` on condensed results or synchronize before moving square tensors to the CPU.
-- Custom `maxIters` / `forceTol` per call
-- Per-molecule `nonBondedThreshold` (MMFF) or `vdwThreshold` (UFF), or per-molecule `ignoreInterfragInteractions`
-- Per-molecule `MMFFMolProperties` objects (e.g. MMFF94s vs MMFF94)
-- Distance, position, angle, or torsion constraints
-- Standalone `compute_energy()` / `compute_gradients()` without minimization
+### Atom-Atom Path similarity and directed sphere exclusion clustering
+
+Atom-Atom Path (AAP) similarity with directed sphere exclusion (DISE)
+clustering provides device and RDKit-style output modes:
```python
-from rdkit.Chem import AddHs, MolFromSmiles
-from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
-from nvmolkit.batchedForcefield import MMFFBatchedForcefield
+from rdkit import Chem
+from nvmolkit.clustering import OutputMode, fused_dise
-mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCCCCC"]]
-for mol in mols:
- EmbedMultipleConfs(mol, numConfs=5)
+molecules = [Chem.MolFromSmiles(smiles) for smiles in ["CCCC", "CCCO", "CCOC"]]
+device_result = fused_dise(molecules, 1 - 0.217, metric="aap")
+rdkit_clusters = fused_dise(molecules, 1 - 0.217, metric="aap", output=OutputMode.RDKIT)
+```
+
+`device_result` has `cluster_ids`, `centroids`, and `cluster_sizes` fields;
+cluster IDs are zero-based and contiguous. `OutputMode.RDKIT` describes
+the centroid-first RDKit cluster representation, not an RDKit implementation
+of the AAP+DISE algorithm. The current DISE control loop synchronizes before
+returning either mode; `DEVICE` describes the stable schema and where the
+result resides, not asynchronous execution of the overall call.
-ff = MMFFBatchedForcefield(
- mols,
- nonBondedThreshold=[100.0, 20.0],
- ignoreInterfragInteractions=True,
-)
+### Maximum common substructure search
-ff[0].add_position_constraint(0, max_displ=0.1, force_constant=50.0)
-ff[1].add_distance_constraint(0, 4, relative=False, min_len=1.8, max_len=2.2, force_constant=25.0)
+```python
+from rdkit import Chem
+from nvmolkit.mcs import findMCS
+
+mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "CCN", "c1ccccc1O"]]
+result = findMCS(mols, mode="pairs", pairs=[(0, 1), (0, 2)])
-energies, converged = ff.minimize(maxIters=500, forceTol=1e-4)
-for mol, mol_energies, mol_converged in zip(mols, energies, converged):
- print(mol.GetNumConformers(), mol_energies, mol_converged)
+for pair_idx, pair in enumerate(result.pairs):
+ item = result[pair_idx]
+ print(pair, item.num_atoms, item.num_bonds, item.atom_mapping)
```
-All conformers of each input molecule are minimized in one batch. Constraints attached via `ff[i].add_*_constraint(...)` apply to every conformer of molecule `i`; constraint setters mark the wrapper dirty and the native forcefield rebuilds on the next call. Pass `output=CoordinateOutput.DEVICE` to `.minimize(...)` to keep optimized coordinates on the GPU (`Device3DResult`) instead of writing them back into RDKit conformers. UFF is the same shape: `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`.
+The default `mode="all_pairs"` generates the upper triangle including the
+diagonal. `mode="pairs"` preserves an explicit pair list exactly, including
+duplicates and reversed pairs. `mode="paired_lists"` zips `mols` with an
+equally sized `mols_b`. Timeouts are per pair; inspect `item.canceled` because a
+timed-out result can contain the best partial MCS found.
+
+Matching options include `atom_compare`, `bond_compare`, valence/formal-charge
+matching, and atom/bond ring-only matching. Unsupported RDKit fMCS options
+raise instead of silently changing semantics. For repeated representative
+explicit-pair workloads, `nvmolkit.autotune.tune_mcs` returns a `TuneResult`.
+Its `best_config` is the tuned `MCSConfig` to pass to
+`findMCS(..., config=result.best_config)`.
+
+### Custom forcefield options + constraints (`BatchedForcefield`)
+
+For per-molecule forcefield settings, geometric constraints, or separate
+energy and gradient calls, read the
+[advanced forcefield recipe](references/advanced-usage.md#custom-forcefield-options-and-constraints).
+
+## Troubleshooting
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `torch.cuda.is_available()` is false | GPU access, driver compatibility, or the torch CUDA build is missing | Check the GPU and driver, then follow the installation guidance above to select a compatible torch build. |
+| `RuntimeError: invalid device ordinal` | A requested `gpuIds` entry is not visible | Use device indices below `torch.cuda.device_count()` or the API's documented GPU defaults. |
+| An RDKit option is rejected | The option is unsupported by that nvMolKit API | Use supported options only if they preserve the requested behavior; otherwise use RDKit for that operation. |
## Going deeper
- Full feature list, API reference, and guides:
- What changed in each release:
-- Worked examples (Jupyter notebooks): the `examples/` directory in the GitHub repo
+- Worked examples (Jupyter notebooks): the [examples/ directory](https://github.com/NVIDIA-BioNeMo/nvMolKit/tree/main/examples) in the GitHub repo
diff --git a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/evals.json b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/evals.json
index ad04d2a9..ab199632 100644
--- a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/evals.json
+++ b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/evals.json
@@ -55,7 +55,7 @@
"expected_output": "The agent provides a complete nvMolKit port using batched embedding, batched MMFF optimization, and the batch conformer RMSD API, with nvMolKit-compatible ETKDG parameters and safe result handling.",
"assertions": [
"The agent creates explicit-hydrogen RDKit molecules with Chem.AddHs before embedding",
- "The agent creates ETKDGv3 parameters and sets useRandomCoords = True as required by nvMolKit",
+ "The agent creates ETKDGv3 parameters without setting useRandomCoords",
"The agent calls nvmolkit.embedMolecules.EmbedMolecules once on the molecule collection with confsPerMolecule=20",
"The agent calls MMFFOptimizeMoleculesConfs once on the molecule collection with maxIters=500 instead of retaining the RDKit per-molecule optimization loop",
"The agent calls GetConformerRMSMatrixBatch on the heavy-atom molecule collection",
@@ -102,7 +102,7 @@
"expected_output": "The agent writes a complete batch-oriented nvMolKit conformer workflow using compatible ETKDG parameters, batched MMFF and RMSD calls, invalid-molecule handling, and structured summaries.",
"assertions": [
"The code parses the SMILES and adds explicit hydrogens before ETKDG and MMFF",
- "The code uses ETKDGv3 with useRandomCoords = True",
+ "The code uses ETKDGv3; eigenvalue-based and random-coordinate initialization are both valid",
"The code calls EmbedMolecules once on the valid molecule collection with an explicit positive confsPerMolecule value",
"The code calls MMFFOptimizeMoleculesConfs once on the collection and handles molecules lacking MMFF parameters or reports the indexed ValueError cleanly",
"The code calls GetConformerRMSMatrixBatch on heavy-atom molecules rather than using the single-molecule API as its primary loop",
@@ -143,10 +143,10 @@
},
{
"id": "nvmolkit-usage-010",
- "prompt": "Here is an existing good nvMolKit ETKDG embedding script. Modify it to use nvMolKit autotuning for the HardwareOptions used by EmbedMolecules. Do not run or benchmark it; provide the updated script only.\n\n```python\nfrom pathlib import Path\nimport json\nimport time\n\nimport torch\nfrom rdkit import Chem\nfrom rdkit.Chem import AddHs\nfrom rdkit.Chem.rdDistGeom import ETKDGv3\n\nfrom nvmolkit.embedMolecules import EmbedMolecules\n\nsmiles_path = Path(\"molecules.smi\")\nsmiles = [\n line.split()[0]\n for line in smiles_path.read_text().splitlines()\n if line.strip() and not line.startswith(\"#\")\n]\nmols = [AddHs(Chem.MolFromSmiles(smi)) for smi in smiles]\n\nparams = ETKDGv3()\nparams.useRandomCoords = True\nparams.randomSeed = 0xC0FFEE\n\nstart = time.perf_counter()\nEmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)\ntorch.cuda.synchronize()\nelapsed = time.perf_counter() - start\n\nsummary = {\n \"molecules\": len(mols),\n \"conformers\": sum(mol.GetNumConformers() for mol in mols),\n \"elapsed_seconds\": elapsed,\n}\nPath(\"embedding_summary.json\").write_text(\n json.dumps(summary, indent=2, sort_keys=True)\n)\n```",
+ "prompt": "Here is an existing good nvMolKit ETKDG embedding script. Modify it to use nvMolKit autotuning for the HardwareOptions used by EmbedMolecules. Do not run or benchmark it; provide the updated script only.\n\n```python\nfrom pathlib import Path\nimport json\nimport time\n\nimport torch\nfrom rdkit import Chem\nfrom rdkit.Chem import AddHs\nfrom rdkit.Chem.rdDistGeom import ETKDGv3\n\nfrom nvmolkit.embedMolecules import EmbedMolecules\n\nsmiles_path = Path(\"molecules.smi\")\nsmiles = [\n line.split()[0]\n for line in smiles_path.read_text().splitlines()\n if line.strip() and not line.startswith(\"#\")\n]\nmols = [AddHs(Chem.MolFromSmiles(smi)) for smi in smiles]\n\nparams = ETKDGv3()\nparams.randomSeed = 0xC0FFEE\n\nstart = time.perf_counter()\nEmbedMolecules(mols, params, confsPerMolecule=10, maxIterations=-1)\ntorch.cuda.synchronize()\nelapsed = time.perf_counter() - start\n\nsummary = {\n \"molecules\": len(mols),\n \"conformers\": sum(mol.GetNumConformers() for mol in mols),\n \"elapsed_seconds\": elapsed,\n}\nPath(\"embedding_summary.json\").write_text(\n json.dumps(summary, indent=2, sort_keys=True)\n)\n```",
"expected_output": "The agent preserves the existing workflow, calls the supported tune_embed_molecules API on a representative workload, applies TuneResult.best_config through hardwareOptions= to the full EmbedMolecules call, and retains summary output.",
"assertions": [
- "The updated script preserves SMILES loading, AddHs, ETKDGv3 with useRandomCoords=True, full-workload embedding, and embedding_summary.json output",
+ "The updated script preserves SMILES loading, AddHs, ETKDGv3, full-workload embedding, and embedding_summary.json output",
"The script imports and calls nvmolkit.autotune.tune_embed_molecules or an equivalent supported import of that function",
"The script may tune on a representative subset while keeping the full collection for the production EmbedMolecules call",
"The script reads TuneResult.best_config and passes it to the full EmbedMolecules call via hardwareOptions=",
@@ -168,6 +168,21 @@
],
"expected_skill": "nvmolkit-usage",
"expected_script": null
+ },
+ {
+ "id": "nvmolkit-usage-012",
+ "prompt": "Write nvMolKit code that finds maximum common substructures for the explicit molecule pairs [(0, 1), (2, 3), (0, 2)]. Preserve that pair order, allow any atom and any bond to match, set a 5-second timeout for each pair, and report atom/bond counts plus whether each search timed out.",
+ "expected_output": "The agent constructs RDKit molecules, calls nvmolkit.mcs.findMCS once in explicit-pairs mode, and reads the ordered MCSBatchResult correctly, including each MCSResult's counts and canceled flag.",
+ "assertions": [
+ "The code imports findMCS from nvmolkit.mcs and calls it once for the batch",
+ "The code passes mode='pairs' and the explicit pairs [(0, 1), (2, 3), (0, 2)] without reordering or deduplicating them",
+ "The code uses atom_compare='any', bond_compare='any', and timeout_seconds=5",
+ "The code iterates in result.pairs order and materializes each item with result[pair_idx] or result.get_result(pair_idx)",
+ "The code reports num_atoms, num_bonds, and canceled for every requested pair",
+ "The agent explains that timeout_seconds is a per-pair budget and that a canceled result may contain the best partial MCS found"
+ ],
+ "expected_skill": "nvmolkit-usage",
+ "expected_script": null
}
]
}
diff --git a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/trigger_evals.json b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/trigger_evals.json
index 7d3760c3..07419470 100644
--- a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/trigger_evals.json
+++ b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/evals/trigger_evals.json
@@ -18,11 +18,16 @@
},
{
"id": "nvmolkit-usage-trigger-004",
+ "prompt": "Use nvMolKit to find maximum common substructures for a batch of explicit molecule pairs.",
+ "expected": "trigger"
+ },
+ {
+ "id": "nvmolkit-usage-trigger-005",
"prompt": "Write a pandas data cleaning script for a CSV of customers.",
"expected": "no_trigger"
},
{
- "id": "nvmolkit-usage-trigger-005",
+ "id": "nvmolkit-usage-trigger-006",
"prompt": "Use RDKit to calculate one descriptor for a single molecule; I do not have a GPU.",
"expected": "no_trigger"
}
diff --git a/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/references/advanced-usage.md b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/references/advanced-usage.md
new file mode 100644
index 00000000..caff65f2
--- /dev/null
+++ b/skills/bionemo-agent-toolkit/skills/nvmolkit-usage/references/advanced-usage.md
@@ -0,0 +1,79 @@
+# Advanced nvMolKit usage
+
+## Configuration
+
+Configuration objects expose operation-specific GPU and CPU execution controls.
+
+### `HardwareOptions` (ETKDG, MMFF, UFF)
+
+`from nvmolkit.types import HardwareOptions`. Passed via `hardwareOptions=` to `EmbedMolecules`, `MMFFOptimizeMoleculesConfs`, `UFFOptimizeMoleculesConfs`, and the `BatchedForcefield` constructors. Every field has an "auto" sentinel; the defaults are usually fine.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `preprocessingThreads` | int | `-1` (all visible CPUs) | CPU threads for preprocessing |
+| `batchSize` | int | `-1` (auto-tuned) | Number of conformers per GPU batch |
+| `batchesPerGpu` | int | `-1` (auto) | Concurrent batches per GPU; must be `>0` or `-1` |
+| `gpuIds` | `list[int]` | `[]` (all visible GPUs) | Specific device ordinals to target |
+
+Passing a `gpuIds` entry for a device that isn't visible raises `RuntimeError: invalid device ordinal`. For finding good values automatically across a representative sample, see `nvmolkit.autotune` (requires the `optuna` extra); each `tune_*` function returns a `TuneResult` whose `best_config` is a fully-populated `HardwareOptions` ready to pass back into the real call.
+
+`HardwareOptions` round-trips through `to_dict()` / `from_dict()` for persisting tuned configs to disk.
+
+### `SubstructSearchConfig` (substructure search)
+
+`from nvmolkit.substructure import SubstructSearchConfig`. Passed via `config=` to `hasSubstructMatch`, `countSubstructMatches`, and `getSubstructMatches`.
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `batchSize` | int | `1024` | (target, query) pairs per GPU batch |
+| `workerThreads` | int | `-1` (auto) | GPU runner threads per GPU |
+| `preprocessingThreads` | int | `-1` (auto) | CPU threads for preprocessing |
+| `maxMatches` | int | `0` (unlimited) | Max matches returned per (target, query) pair |
+| `uniquify` | bool | `False` | Drop duplicate matches that differ only in atom enumeration order |
+| `gpuIds` | `list[int] \| None` | `None` (current device only) | Specific device ordinals to target |
+
+Substructure search currently does not support chirality-aware matching, enhanced stereochemistry, or other advanced RDKit `SubstructMatchParameters` options.
+
+### `MCSConfig` (maximum common substructure search)
+
+`from nvmolkit.mcs import MCSConfig`. Pass it via `config=` to `findMCS`.
+The fields `batchSize`, `workerThreads`, `preprocessingThreads`,
+`executorsPerRunner`, and `gpuIds` control chunking and dispatch. Defaults
+autoselect execution settings; an empty `gpuIds` list uses the current device.
+`MCSConfig` supports `to_dict()` / `from_dict()` and can also be persisted with
+`nvmolkit.autotune.save()` / `load()`.
+
+## Custom forcefield options and constraints
+
+Reach for `MMFFBatchedForcefield` / `UFFBatchedForcefield` instead of the one-shot `MMFFOptimizeMoleculesConfs` / `UFFOptimizeMoleculesConfs` when you need any of:
+
+- Custom `maxIters` / `forceTol` per call
+- Per-molecule `nonBondedThreshold` (MMFF) or `vdwThreshold` (UFF), or per-molecule `ignoreInterfragInteractions`
+- Per-molecule `MMFFMolProperties` objects (e.g. MMFF94s vs MMFF94)
+- Distance, position, angle, or torsion constraints
+- Standalone `compute_energy()` / `compute_gradients()` without minimization
+
+```python
+from rdkit.Chem import AddHs, MolFromSmiles
+from rdkit.Chem.rdDistGeom import EmbedMultipleConfs
+from nvmolkit.batchedForcefield import MMFFBatchedForcefield
+
+mols = [AddHs(MolFromSmiles(smi)) for smi in ["CCO", "CCCCCC"]]
+for mol in mols:
+ EmbedMultipleConfs(mol, numConfs=5)
+
+ff = MMFFBatchedForcefield(
+ mols,
+ nonBondedThreshold=[100.0, 20.0],
+ ignoreInterfragInteractions=True,
+)
+
+ff[0].add_position_constraint(0, max_displ=0.1, force_constant=50.0)
+ff[1].add_distance_constraint(0, 4, relative=False, min_len=1.8, max_len=2.2, force_constant=25.0)
+
+energies, converged = ff.minimize(maxIters=500, forceTol=1e-4)
+for mol, mol_energies, mol_converged in zip(mols, energies, converged):
+ print(mol.GetNumConformers(), mol_energies, mol_converged)
+```
+
+All conformers of each input molecule are minimized in one batch. Constraints attached via `ff[i].add_*_constraint(...)` apply to every conformer of molecule `i`; constraint setters mark the wrapper dirty and the native forcefield rebuilds on the next call. Pass `output=CoordinateOutput.DEVICE` to `.minimize(...)` to keep optimized coordinates on the GPU (`Device3DResult`) instead of writing them back into RDKit conformers. UFF is the same shape: `UFFBatchedForcefield(mols, vdwThreshold=..., ...)`.