boltzgen

Antibody and nanobody binder design using BoltzGen (BoltzGen diffusion + Protenix refolding). Covers entity YAML specification, CLI invocation, protocol selection (nanobody-anything / antibody-anythin

SKILL.md

GitHub

BoltzGen — Antibody / Nanobody Binder Design

You are an expert at running BoltzGen for antibody and nanobody design. This skill teaches the exact Write → Bash → Read pattern for invoking the tool via CLI. Never call MCP functions directly — always use the Write tool to create the entities YAML, the Bash tool to run the CLI, and the Read tool to parse results.


1. Prerequisites

Requirement Details
Tool path Set via PROTEUS_AB_DIR or BOLTZGEN_DIR env var
CLI binary boltzgen (on PATH after env setup)
GPU Required — CUDA-capable, ≥24 GB VRAM recommended
Env: PROTEUS_MODELS_DIR ~/.cache/boltzgen (model weights)
Env: LAYERNORM_TYPE openfold (required for correct inference)
Target structure CIF or PDB file with clean chain IDs

2. When to Use BoltzGen

User wants a binder...
│
├── Antibody or nanobody format required?
│   ├── YES, nanobody (VHH / single-domain)
│   │   └── boltzgen  protocol: nanobody-anything
│   ├── YES, full antibody (VH/VL Fab)
│   │   └── boltzgen  protocol: antibody-anything
│   └── NO, any format acceptable
│       └── Consider proteus-prot (de novo miniprotein) first;
│           switch to boltzgen if proteus-prot fails
│
├── Need to validate an existing antibody structure?
│   └── Use proteus-fold instead
│
└── Need to score an existing antibody design?
    └── Use by-scoring skill (ipSAE)

3. Protocols

Protocol Format Chains Design Speed Recommended Designs
nanobody-anything VHH single-domain 1 chain Faster 10–50
antibody-anything VH/VL Fab pair 2 chains Slower 20–100
protein-anything De novo miniprotein binder 1 chain Fast 10–100
peptide-anything Peptide binder 1 chain Fastest 20–100
protein-redesign Redesign existing binder 1 chain Fast 10–50

Choose nanobody when: smaller binder preferred, tissue penetration needed, or faster iteration desired.

Choose antibody when: Fc effector function needed, higher affinity required, or therapeutic antibody format mandated.

Choose protein-anything when: de novo binder design (no scaffold template), miniprotein format (65-150 aa), or when PXDesign is unavailable/failing. BoltzGen generates completely novel binder structures without requiring a scaffold template. Same entity YAML format as nanobody — specify target chain with hotspot residues, BoltzGen generates de novo binder structures.

BoltzGen as PXDesign Fallback

If PXDesign fails (CUDA incompatibility, env issues, missing deps), use BoltzGen protein-anything as a direct replacement for de novo design:

# Instead of: pxdesign pipeline -i config.yaml ...
# Use:
boltzgen run spec.yaml --protocol protein-anything --num_designs 50 --budget 10

The entity YAML spec is identical. BoltzGen's protein-anything produces 65-150 aa miniprotein binders — same output class as PXDesign but using BoltzGen's diffusion model. Confidence metrics (ipTM, pLDDT) and screening are the same downstream.


4. How to Run (Write → Bash → Read)

Step 1: Write the entities YAML spec

Use the Write tool to create a design specification file. See references/entities-yaml-spec.md for the full format.

# /path/to/workspace/design_spec.yaml
entities:
- file:
    path: ./target.cif
    include:
    - chain:
        id: A
    binding_types:
    - chain:
        id: A
        binding: 7..12,27..34

Binding residues use .. range notation: a list like [7,8,9,10,11,12,27,28,29,30] becomes 7..12,27..30. These are label_seq_id values (1-indexed, sequential, no gaps).

To include scaffold templates, add a second entity pointing to a scaffold YAML:

- file:
    path: $BOLTZGEN_DIR/example/  # from BoltzGen repofab_scaffolds/adalimumab.6cr1.yaml

Step 2: Run the CLI via Bash

PROTEUS_MODELS_DIR="$HOME/.cache/boltzgen" \
LAYERNORM_TYPE="openfold" \
boltzgen run /path/to/workspace/design_spec.yaml \
  --protocol nanobody-anything \
  --num_designs 20 \
  --msa-mode none \
  --budget 48 \
  --output /path/to/workspace/output \
  --prefilter

Step 3: Read the output CSV

# Primary location
cat <output_dir>/final_ranked_designs/final_designs_metrics_*.csv

# Fallback: recursive search
find <output_dir> -name 'final_designs_metrics_*.csv'

Use the Read tool on the CSV. Results are sorted by iptm descending.


5. CLI Parameters

Flag Type Default Description
<spec_path> positional required Path to entities YAML file
--protocol string required nanobody-anything or antibody-anything
--num_designs int 10 Number of designs to generate
--msa-mode string none MSA strategy: none, precomputed, or nim
--budget int 48 Sampling budget (diffusion steps)
--output path auto Output directory
--prefilter flag off Enable pre-filtering before Protenix refolding

Budget guidance: 48 for preview, 96–128 for production. Higher budget increases diversity but costs more GPU time.


6. MSA Modes

Mode Source When to Use
none No MSA Default. Fast. Sufficient for most design runs
precomputed A3M files When you have pre-built alignments from MMseqs2 or HHblits
nim NVIDIA NIM API Remote MSA generation. Requires NIM API access

Start with none. Only use precomputed or nim if initial designs show poor structural confidence (pLDDT < 70).


7. Entities YAML Specification (Summary)

The entities YAML defines target chains, binding residues, and optional scaffold templates. Full specification in references/entities-yaml-spec.md.

Key rules:

  • Each entity is a file: block with path, include, and optional binding_types
  • include lists which chains to use: - chain: { id: A }
  • binding_types specifies epitope residues using range notation: binding: 7..12,27..34
  • Binding residues use label_seq_id (1-indexed, sequential, per-chain)
  • Scaffolds are separate entities pointing to scaffold YAML files

Range Notation

Convert residue lists to .. ranges for contiguous stretches:

Input Range Notation
[7, 8, 9, 10, 11, 12] 7..12
[7, 8, 9, 27, 28, 29, 30] 7..9,27..30
[5, 10, 15] 5..5,10..10,15..15
[1, 2, 3, 4, 5, 20, 21, 22, 50] 1..5,20..22,50..50

Singletons are expressed as N..N.


8. Output Format

Output CSV: <output_dir>/final_ranked_designs/final_designs_metrics_*.csv

Column Type Description
design_id string Unique design identifier
iptm float Interface predicted TM-score (0–1)
ptm float Predicted TM-score (0–1)
plddt float Per-residue confidence, mean (0–100)
design_iptm float Design-stage ipTM before refolding
ipsae_min float Min of directional ipSAE scores (0–1)
rmsd float CA-RMSD between designed and refolded (Angstroms)
sequence string Full amino acid sequence

Sorted by iptm descending. Apply hard filters: ipTM > 0.5, pLDDT > 70, RMSD < 3.5 A. Then rank by composite score (see by-scoring skill).


9. Pipeline Stages

BoltzGen runs a 6-stage internal pipeline. See references/pipeline-stages.md for details.

Design (BoltzGen) → Inverse Fold (AntiFold) → [Pre-filter] → Protenix Refold → Analysis → Filtering

The --prefilter flag enables stage 3, which discards low-confidence designs before the expensive Protenix refolding step. Recommended for production runs (num_designs ≥ 50).


10. Common Mistakes

Mistake Consequence Fix
Using auth_seq_id instead of label_seq_id for binding residues Wrong epitope, wasted campaign Always convert author numbering to label_seq_id first
Missing LAYERNORM_TYPE=openfold env var Silent numerical errors or crashes Always set both env vars
Missing PROTEUS_MODELS_DIR env var Model weights not found Set to ~/.cache/boltzgen
Budget too low (< 32) Poor diversity, repetitive designs Use ≥ 48 for preview, ≥ 96 for production
Skipping --prefilter on large runs Wastes GPU time refolding bad designs Enable for num_designs ≥ 50
Using antibody protocol when nanobody suffices Slower, needs more designs Match protocol to actual format need
Forgetting scaffold entity in YAML Uses default scaffolds only Add explicit scaffold if specific template desired
Binding residues on buried surface Designs cannot reach epitope Verify surface exposure (SASA > 0.25)

11. Troubleshooting

Symptom Likely Cause Fix
FileNotFoundError on model weights PROTEUS_MODELS_DIR not set or wrong path Verify ~/.cache/boltzgen exists with weights
CUDA out of memory GPU VRAM insufficient Reduce --num_designs or --budget; use smaller batch
All designs have ipTM < 0.4 Bad epitope selection or target issue Re-examine binding residues; verify target with proteus-fold
No CSV output found Run failed silently or wrong output path Check stderr; look recursively for final_designs_metrics_*.csv
Very similar sequences across all designs Budget too low or diversity not explored Increase --budget; try different binding residues
LAYERNORM_TYPE error Env var missing Export LAYERNORM_TYPE=openfold before running
Slow run with --msa-mode nim Network latency to NIM API Switch to none for faster iteration

12. Examples

Example 1: Nanobody against a single-chain target

# 1. Write the entities YAML (via Write tool)
# Target: chain A of cleaned PDB, epitope at residues 45-52 and 78-85
# workspace/nb_design_spec.yaml
entities:
- file:
    path: ./target_clean.cif
    include:
    - chain:
        id: A
    binding_types:
    - chain:
        id: A
        binding: 45..52,78..85
# 2. Run CLI (via Bash tool)
PROTEUS_MODELS_DIR="$HOME/.cache/boltzgen" \
LAYERNORM_TYPE="openfold" \
boltzgen run workspace/nb_design_spec.yaml \
  --protocol nanobody-anything \
  --num_designs 20 \
  --msa-mode none \
  --budget 48 \
  --output workspace/nb_output
# 3. Read results (via Read tool)
# Look for: workspace/nb_output/final_ranked_designs/final_designs_metrics_*.csv

Example 2: Antibody with scaffold template

# workspace/ab_design_spec.yaml
entities:
- file:
    path: ./antigen.cif
    include:
    - chain:
        id: B
    binding_types:
    - chain:
        id: B
        binding: 100..115,140..148
- file:
    path: $BOLTZGEN_DIR/example/  # from BoltzGen repofab_scaffolds/adalimumab.6cr1.yaml
PROTEUS_MODELS_DIR="$HOME/.cache/boltzgen" \
LAYERNORM_TYPE="openfold" \
boltzgen run workspace/ab_design_spec.yaml \
  --protocol antibody-anything \
  --num_designs 50 \
  --msa-mode none \
  --budget 96 \
  --output workspace/ab_output \
  --prefilter

Example 3: Multi-chain target with scattered epitope

# workspace/multichain_spec.yaml
entities:
- file:
    path: ./complex.cif
    include:
    - chain:
        id: A
    - chain:
        id: B
    binding_types:
    - chain:
        id: A
        binding: 22..28,55..55
    - chain:
        id: B
        binding: 10..16

This targets residues on both chain A and chain B of a multi-chain complex.


13. Scaffold Templates

Pre-built scaffold YAMLs for antibody framework selection. Located at: $BOLTZGEN_DIR/example/ # from BoltzGen repo

Available Fab Scaffolds (14)

Scaffold PDB File
Adalimumab 6cr1 fab_scaffolds/adalimumab.6cr1.yaml
Belimumab 7m3n fab_scaffolds/belimumab.7m3n.yaml
Crenezumab 5vzo fab_scaffolds/crenezumab.5vzo.yaml
Dupilumab 8d96 fab_scaffolds/dupilumab.8d96.yaml
Golimumab 5wuv fab_scaffolds/golimumab.5wuv.yaml
Guselkumab 7unp fab_scaffolds/guselkumab.7unp.yaml
mAb1 7q0g fab_scaffolds/mab1.7q0g.yaml
Necitumumab 5stx fab_scaffolds/necitumumab.5stx.yaml
Nirsevimab 8hkq fab_scaffolds/nirsevimab.8hkq.yaml
Sarilumab 7moe fab_scaffolds/sarilumab.7moe.yaml
Secukinumab 5yy2 fab_scaffolds/secukinumab.5yy2.yaml
Tezepelumab 6oaj fab_scaffolds/tezepelumab.6oaj.yaml
Tralokinumab 6ux9 fab_scaffolds/tralokinumab.6ux9.yaml
Ustekinumab 3hn3 fab_scaffolds/ustekinumab.3hn3.yaml

Available Nanobody Scaffolds (4)

Scaffold PDB File
Caplacizumab 7eow nanobody_scaffolds/caplacizumab.7eow.yaml
Vobarilizumab 7xl0 nanobody_scaffolds/vobarilizumab.7xl0.yaml
Gefurulimab 8coh nanobody_scaffolds/gefurulimab.8coh.yaml
Ozoralizumab 8z8v nanobody_scaffolds/ozoralizumab.8z8v.yaml

Default Behavior

If no scaffold entity is added to the entities YAML, boltzgen uses its built-in default scaffolds. Explicit scaffolds are useful when:

  • A specific antibody framework is required (e.g., adalimumab for anti-TNF)
  • The user requests a humanized template from a known therapeutic
  • Nanobody design needs a specific starting framework

Adding a Scaffold to Entities YAML

entities:
- file:
    path: ./target.cif
    include:
    - chain:
        id: A
    binding_types:
    - chain:
        id: A
        binding: 45..52,78..85
- file:
    path: $BOLTZGEN_DIR/example/  # from BoltzGen repofab_scaffolds/adalimumab.6cr1.yaml