boltz-protein-design

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill when the user wants de novo protein / peptide / antibody / nanobody binders.

1. Decide on target exploration first (new targets). For a new target where the user hasn't already fixed the binding site and crop, your first action — before authoring a payload, normalizing the target, or running estimate-cost — is to raise the choice between a target-exploration pass and designing directly, with a recommendation for this target:

   • Unknown site, or a multi-domain / large target → recommend exploration (it scouts different input configurations for generation, ≈50 designs each, and finds the best before a full run).
   • A well-characterized site → it's fine to recommend going (mostly) direct, perhaps with a quick check of whether conditioning on the epitope beats letting the model find its own spot. State this plainly, as part of a conversation with the user about their target and goals, and let them choose.

   Phrase it as a question that works with the user (they may know their target's biology), e.g.:

   "This is a fresh target — I'd suggest a quick exploration pass that scouts a few framings and picks the best before a full run. Or, if you already know the site and crop, we can design directly. Which would you like?"

   Do not mention a campaign size or tier here — not even folded into this opening approach question. The full-run size is settled later, after the scouting runs pick a winner (its yield informs the tier), so don't ask it up front when exploration is on the table. If the user opts into exploration — or has already said they want to explore / let the design find its own epitope — read references/target-exploration.md, follow it, then resume at step 8 with the chosen framing and recommended num_proteins. If they want to design directly, continue below.

2. Normalize the target (same shape as protein-screen): structure_template if a CIF/PDB is available, else no_template.

3. Pick the binder_specification variant. Supported variants include:

   • boltz_curated — recommended default for antibody and nanobody design. Boltz selects from maintained scaffold/template lists (binder: boltz_antibody or boltz_nanobody).
   • structure_template — redesign motifs in an existing binder scaffold (CIF + design_motifs with replacement / insertion segments).
   • no_template — generate from the sequence DSL (fixed residues + designed segments like 5..10 or 8).

4. For antibody or nanobody requests, ask before authoring the payload: "I recommend Boltz's curated antibody/nanobody scaffolds for this. Do you want the curated default, or do you have custom scaffold structures/CDR motifs to use?" If the user picks curated, use type: boltz_curated; if they want custom scaffold control, use type: structure_template.

5. Pick modality: peptide, antibody, nanobody, or custom_protein for structure_template and no_template (use custom_protein for a "miniprotein" or generic "protein binder"). If the user already named the modality, take it as given — don't ask again. Do not include modality on boltz_curated; use binder instead.

6. Pick num_proteins — see Run sizing. Valid range is 10 to 1,000,000 (server rejects outside it); 10 is the hard floor but it is a test size, not a campaign. When the user has not given a count, propose a campaign tier (default 50,000), not the floor.

7. Supported optional features include rules such as excluded amino acids, excluded sequence motifs with X wildcards, and max hydrophobic fraction. Add rules only on request; read references/api.md for exact shapes and examples.

8. Author the payload YAML or JSON, then run estimate-cost and apply the spending gate (Always Do This) before start. (Cost model — tiered by total complex length, estimate-cost is the only source: see ## Cost in api.md.)

9. start to submit. Capture the ID.

10. Launch download-results through the runtime's long-running or non-blocking command facility. Use the mechanism the runtime documents; consult boltz-cli-setup if unsure. After launching the downloader, always report the job ID, run name, and output directory. If the runtime can schedule follow-up checks, schedule a download-status check and state the cadence; otherwise include the download-status command.

11. Rank from <output-root>/<run-name>/results/index.jsonl by binding_confidence descending. Use iptm and min_interaction_pae as tiebreakers. optimization_score is not emitted for this endpoint. Read references/results.md for output layout and metric details.