Antibody and nanobody binder design using BoltzGen (BoltzGen diffusion + Protenix refolding). Covers entity YAML specification, CLI invocation, protocol selection (nanobody-anything / antibody-anything), MSA modes, and output parsing. Use this skill whenever the user needs to design an antibody or nanobody binder against a protein target.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Antibody and nanobody binder design using BoltzGen (BoltzGen diffusion + Protenix refolding). Covers entity YAML specification, CLI invocation, protocol selection (nanobody-anything / antibody-anything), MSA modes, and output parsing. Use this skill whenever the user needs to design an antibody or nanobody binder against a protein target.
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)
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:
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.
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
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/ab_design_spec.yamlentities:-file:path:./antigen.cifinclude:-chain:id:Bbinding_types:-chain:id:Bbinding:100..115,140..148-file:path:$BOLTZGEN_DIR/example/# from BoltzGen repofab_scaffolds/adalimumab.6cr1.yaml
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.cifinclude:-chain:id:Abinding_types:-chain:id:Abinding:45..52,78..85-file:path:$BOLTZGEN_DIR/example/# from BoltzGen repofab_scaffolds/adalimumab.6cr1.yaml
