boltz-structure-and-binding
Predict structures and binding for one defined complex with Boltz. Use when folding a protein, RNA, DNA, or ligand complex, docking one ligand, predicting an interface, or scoring binding. Not for screening libraries or design.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- boltz-structure-and-binding
- description
- Predict structures and binding for one defined complex with Boltz. Use when folding a protein, RNA, DNA, or ligand complex, docking one ligand, predicting an interface, or scoring binding. Not for screening libraries or design.
02 资源文件 3
- 参考文档agents/openai.yaml243 B
- 参考文档references/api.md9.6 KB
- 参考文档references/results.md1.6 KB
03 SKILL.md 正文
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 for one defined complex, not a library workflow.
-
Normalize the inputs into
entities. Each entity is{type, chain_ids, value}— note pluralchain_ids(an array, even for one chain) and the field isvalue, notsequence:{"entities": [{"type": "protein", "chain_ids": ["A"], "value": "MKTAYIAKQRQISFVKSHFSRQ"}]}typeis one ofprotein | rna | dna | ligand_smiles | ligand_ccd. Chain IDs go in entity order (A,B,C, …) unless the user specifies otherwise. Readreferences/api.mdfor per-type field variants (cyclic,modifications, ligand CCD codes, etc.) before authoring your first payload — agent guesses likesequence:orchain_id: "A"(singular) fail with unclear 400 errors. -
If the user wants binding metrics, add a flat
bindingblock with an explicittypefield. For ligand-protein binding use:binding: type: ligand_protein_binding binder_chain_id: BFor protein-protein binding use:
binding: type: protein_protein_binding binder_chain_ids: [B]Do not nest the variant name under
binding(for example, nobinding.ligand_protein_bindingobject). -
Supported optional features include
constraints,bonds,modifications,model_options, and binding metrics; only add them if the user asks. Read references/api.md for exact shapes and examples. -
Author the payload YAML or JSON, run
estimate-cost, show the USD cost, wait for explicit confirmation. -
startto submit (synchronous). Capture the ID. -
Launch
download-resultswith the agent runtime's background/non-blocking command facility so polling + download continue without blocking the agent session. In Claude Code, use Bash withrun_in_background: true. In Codex, rundownload-resultsas a foreground shell command withyield_time_ms: 1000; if Codex returns asession_id, keep it for optional same-thread polling, but treatdownload-statusplus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checksdownload-statusperiodically and posts a concise completion or failure update when the download reaches a terminal state. After launching the downloader, always report the job ID, run name, and output directory. Include the next check cadence if the heartbeat was created; otherwise include thedownload-statuscommand.
Command Pattern
# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: sab-<target>-<ligand>-v1
# 1. estimate
boltz-api predictions:structure-and-binding estimate-cost \
--model boltz-2.1 \
--input @yaml:///absolute/path/payload.yaml
# 2. confirm with user, then submit
boltz-api predictions:structure-and-binding start \
--model boltz-2.1 \
--idempotency-key "<run-name>" \
--input @yaml:///absolute/path/payload.yaml \
--raw-output --transform id
# 3. Copy the printed job ID into this command, then launch it in the agent
# runtime's background/non-blocking mode.
# Claude Code: Bash with run_in_background=true.
# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.
# Do not append "&" or use nohup in Codex.
boltz-api download-results \
--id "<job-id-from-start>" --name "<run-name>" \
--root-dir "/absolute/path/boltz-experiments" \
--poll-interval-seconds 10
# -> /absolute/path/boltz-experiments/<run-name>/outputs/archive.tar.gz, .boltz-run.json
Always Do This
- Keep payload field names exactly as the API body names shown in
references/api.md; then pass the merged payload with--input @yaml:///absolute/path/payload.yamlor@json:///absolute/path/payload.json. Never use@./payload.yamlor@file://for object-typed payloads. - Use absolute paths for the output root, payload files, and embedded structure files. Do not
cdinto the run directory for follow-up commands; pass the same--root-dirand use absolute paths so later relative paths do not drift. - Residue indices are 0-based wherever the payload asks for residue positions (constraints, modifications, contact tokens).
- For CIF/PDB bytes embedded in
--target/structure.data, use@data:///absolute/path/file.cif— it detects binary and base64-encodes. Don't use bare@pathfor binary data. - Use the same slug as both
--idempotency-keyat submit time and--nameat download time so re-runs are idempotent and resume from.boltz-run.json. - In permission-gated agents such as Claude Code, keep each Boltz call as a top-level command that starts with
boltz-api. Prefer concrete arguments oversh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around theboltz-apiinvocation unless the user already allowed that exact command form. Use--raw-output --transform id, read the printed ID, then paste that literal ID into the nextdownload-resultscommand. - Prefer the agent runtime's background/non-blocking command mode for
download-results. In Codex specifically, keepdownload-resultsin the foreground and set the shell tool yield to 1000 ms; Codex will return asession_idif the command is still running. Do not append&or usenohupin Codex because the tool runner may clean up shell-backgrounded descendants before.boltz-run.jsonis fully written. - After the background/session starts, do not manually wait on it or run ad hoc polling loops.
download-resultsemits JSONL progress on stderr by default; add--progress-format text --verboseonly when you explicitly want human-readable logs. - In Codex app/desktop runtimes with same-thread heartbeat automation support, schedule a heartbeat after launching
download-results. The heartbeat should runboltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments"on a sensible cadence, post only material status changes or terminal completion/failure, and stop once terminal. Poll the savedsession_idwith an emptywrite_stdinonly for interactive, user-requested progress checks. Do not loopretrieveyourself. - If the current host has no heartbeat automation support, do not claim an automatic next check. Report the job ID, run name, output directory, and the command needed to check
download-status. - If detached download needs to be restarted, re-run
boltz-api download-resultswith the same--name "<run-name>"and the same--root-dir. - Poll interval: keep
--poll-interval-seconds 10for SAB — predictions usually finish in under a few minutes. - Cost: there is no published per-unit rate to cite for SAB — run
estimate-costand state only the figure it returns. Don't estimate or comment on cost.
Escape Hatch
For anything not covered in references/api.md:
- Payload reference: https://api.boltz.bio/docs/api/python/resources/predictions/subresources/structure_and_binding/methods/start
- CLI flag names:
boltz-api predictions:structure-and-binding start --help(schema details aren't there — just flag names and types)
Read references/api.md for entity shapes, binding variants, bonds, constraints, model options, and input examples. Read references/results.md when summarizing downloaded outputs, metrics, or validation quirks.
Outputs
Summarize metrics.json and point the user at the downloaded CIF path. Read references/results.md for the local layout, nested metrics, binding metric variants, and SAB validation quirks.
SAB 400 validation quirk
If the server rejects a payload with only {"code":"VALIDATION_ERROR","message":"Request validation failed"}, inspect entities, binding, and constraints; read references/results.md for details.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.