AutoGineer
Generated banner for Boltz Protein Screen
Generated logo for Boltz Protein Screen

Boltz Protein Screen

OpenAIOfficialCreated by BoltzDistributed by OpenAI

  • Skill
  • Tool integration
  • Science and research
  • MIT
  • No issues found
Download ZIP

From the author

Screen existing protein binders with Boltz. Use when ranking a supplied protein, peptide, antibody, nanobody, or binder library against a target. Not for designing new proteins or screening small molecules.
— the description by Boltz

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The boltz-protein-screen skill provides a structured workflow for evaluating candidate protein binders—such as peptides, antibodies, or nanobodies—against a defined biological target. It handles the submission of binder libraries, manages cost estimation, and automates the retrieval and ranking of results based on binding confidence metrics. This skill is designed for screening existing libraries rather than de novo protein design or small molecule screening.

What it does

  • Normalizes binder libraries into complex entities for screening.
  • Supports target definition via existing 3D structures or raw sequences.
  • Provides cost estimation before job submission.
  • Automates the background download and monitoring of screening results.
  • Ranks screening hits based on binding confidence and interaction metrics.

When to use it

  • When you have a library of candidate proteins, peptides, or antibodies to test.
  • When you need to rank binders against a specific target structure or sequence.
  • When you require a systematic, automated approach to process large binder libraries.
  • When you need to identify high-confidence binders from a pre-existing set.

Advantages

  • Streamlines the end-to-end process from library submission to result ranking.
  • Ensures cost transparency through mandatory estimation steps.
  • Provides clear ranking criteria using standard binding metrics.
  • Handles complex multi-chain candidates like antibodies.

Usage examples

“Screen my library of 50 nanobody sequences against the target protein in target.cif.”
The agent will normalize the sequences, prepare the payload using the provided CIF file, estimate the cost, and upon confirmation, submit the job and monitor the download.
“Rank the results from my recent protein screen job.”
The agent will parse the index.jsonl file in the output directory and present the candidates sorted by binding_confidence, using iptm as a tiebreaker.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/openai/boltz-protein-screen/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip boltz-protein-screen.zip -d .agents/skills

Documentation by Boltz

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 already has candidate proteins / peptides / antibodies / nanobodies.

  1. Normalize the binder library into proteins — a list of candidate complexes. For a simple sequence library each entry has one protein entity; multi-chain candidates (antibody heavy+light) are also allowed.

  2. Pick the target variant:

    • structure_template — user has a CIF/PDB file or URL; select which chains are polymer vs ligand, which residues to keep (crop_residues), and optionally epitope_residues / flexible_residues.

    • no_template — user has only sequences; pass them as target.entities plus optional epitope_residues.

  3. Don't add bonds / constraints unless the user asks for geometry constraints.

  4. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation.

  5. start to submit. Capture the ID.

  6. Launch download-results with the agent runtime's background/non-blocking command facility. In Claude Code, use Bash with run_in_background: true. In Codex, run download-results as a foreground shell command with yield_time_ms: 1000; if Codex returns a session_id, keep it for optional same-thread polling, but treat download-status plus the run directory as the durable source of truth. In Codex app/desktop runtimes that expose same-thread heartbeat automations, create a heartbeat that checks download-status periodically 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 the download-status command.

  7. Rank hits 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.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: protein-screen-<target>-<library>-v1

boltz-api protein:library-screen estimate-cost \
  --input @yaml:///absolute/path/payload.yaml

boltz-api protein:library-screen start \
       --idempotency-key "<run-name>" \
       --input @yaml:///absolute/path/payload.yaml \
       --raw-output --transform id

# 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 30

Payload keys are proteins, target — API body field names.

Always Do This

  • For structure_template, embed CIF/PDB bytes with @data:///abs/path/target.cif inside the structure.data field. Don't use bare @path (automatic file-type detection once sent CIF as plain text into a base64 field and broke the server parser).

  • Residue indices are 0-based. epitope_residues and flexible_residues must be subsets of crop_residues.

  • Keep payload field names exactly as the API body names shown in references/api.md.

  • Use absolute paths for the output root, payload files, and embedded target files. Do not cd into the run directory for follow-up commands; pass the same --root-dir and use absolute paths so later relative paths do not drift.

  • Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json for estimate-cost and start. Keep --idempotency-key and --workspace-id top-level; if they also appear inside --input, the top-level flags win.

  • Direct object flags still work as overrides, such as --target @yaml:///absolute/path/target.yaml or repeated --protein @json:///absolute/path/protein-1.json entries. Piped YAML / JSON on stdin also works, but it must use API body field names. Never use @file:// or @./.

  • Use the same slug as both --idempotency-key and --name.

  • 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 over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines around the boltz-api invocation 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 next download-results command.

  • Prefer the agent runtime's background/non-blocking command mode for download-results. In Codex specifically, keep download-results in the foreground and set the shell tool yield to 1000 ms; Codex will return a session_id if the command is still running. Do not append & or use nohup in Codex because the tool runner may clean up shell-backgrounded descendants before .boltz-run.json is fully written.

  • After the background/session starts, do not manually wait on it or run ad hoc polling loops. Wall-clock time scales roughly with the number of candidates in the library: under 100 often finishes in a few minutes, 100-1,000 may take several minutes to tens of minutes, and larger screens can take longer or hours depending on inputs and system load. Don't quote a fixed duration. --poll-interval-seconds 30 is a reasonable downloader default. download-results emits JSONL progress on stderr by default; add --progress-format text --verbose only 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 run boltz-api --format json download-status --name "<run-name>" --root-dir "/absolute/path/boltz-experiments" and stop once terminal. Choose cadence by candidate count: under 100 -> every 1-2 minutes; 100-1,000 -> every 5 minutes; over 1,000 -> every 15 minutes. Post only material status changes or terminal completion/failure. Poll the saved session_id with an empty write_stdin only for interactive, user-requested progress checks. Never run a manual poll loop in the current turn.

  • 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-results with the same --name "<run-name>" and the same --root-dir.

  • Cost is tiered by total complex length (target + candidate); the combined length sets the tier. Do not state or estimate a dollar figure yourself — to say anything about cost, run estimate-cost and quote only the number it returns.

Escape Hatch

Read references/api.md for the proteins list shape and both target variants (structure_template with chain_selection, and no_template with epitope hints). Read references/results.md after download when ranking screened binders or explaining outputs.

Outputs

Rank from results/index.jsonl after download-results; use references/results.md for local file layout and metric meanings.

Files

references/api.md

Protein Screen — Payload Reference

Covers the protein:library-screen endpoint. Prefer a single merged top-level --input payload. Field names are API body field names.

Minimal CLI pattern:

boltz-api protein:library-screen estimate-cost --input @yaml:///absolute/path/payload.yaml
boltz-api protein:library-screen start --idempotency-key "<run-name>" --input @yaml:///absolute/path/payload.yaml --raw-output --transform id

In permission-gated agents, keep the submit command as a top-level boltz-api ... start invocation. Read the printed job ID from stdout and paste it into the later download-results command.

Keep --idempotency-key and --workspace-id top-level; if they also appear inside --input, the top-level flags win. Direct object flags still work as overrides, such as --target @yaml:///absolute/path/target.yaml or repeated --protein @json:///absolute/path/protein-1.json entries. Piped YAML / JSON on stdin remains supported when you need it, but the body must use API field names.

Contents

  • Top-level request

  • proteins (candidate library)

  • target — variant 1: structure_template

  • target — variant 2: no_template

  • bonds and constraints

  • Cost

  • Outputs (after download-results)

  • Escape hatch

Top-level request

# payload.yaml
proteins:
  - entities:
      - type: protein
        chain_ids: [B]
        value: "MKTAYIAKQRQISFVKSHFSRQ"
  - entities:
      - type: protein
        chain_ids: [B]
        value: "AVGRHEAVGTYCR"
target:
  type: no_template
  entities:
    - type: protein
      chain_ids: [A]
      value: "QRTVEKATLLPNMPGQVLGHSSVLA"
  epitope_residues:
    A: [42, 43, 44]

Top-level fields:

  • proteins (required) — list of candidate binder complexes. Each entry is a mini-complex with its own entities list.

  • target (required) — discriminated union: structure_template or no_template.

Also passed as separate start flags:

  • --idempotency-key <slug>

  • --workspace-id <id> (admin keys only)

proteins (candidate library)

Each entry represents one candidate binder complex to score against the target. For a simple sequence library each entry contains one protein entity:

proteins:
  - entities:
      - type: protein
        chain_ids: [B]
        value: "MKTAYIAKQRQISFVKSHFSRQ"
    id: binder-001                 # optional; returned as external_id

Multi-chain candidates (e.g. antibody heavy + light) put multiple entities in one entry:

proteins:
  - entities:
      - type: protein
        chain_ids: [H]
        value: "EVQLVES...QVTVSS"
      - type: protein
        chain_ids: [L]
        value: "DIQMTQ...VEIKR"

Supported entity types inside proteins[].entities:

  • protein

  • rna

  • dna

  • ligand_smiles

  • ligand_ccd

Entity fields: type, value, chain_ids, modifications (optional), cyclic (optional bool).

Each proteins[] entry may also include an optional client-side id. The server echoes it as external_id on the corresponding result; use it to map ranked hits back to FASTA records, CSV rows, or library IDs.

target — variant 1: structure_template

Use when the user has a 3D structure (CIF/PDB file or URL).

target:
  type: structure_template
  structure:
    type: url
    url: "https://example.com/target.cif"
  chain_selection:
    A:
      chain_type: polymer
      crop_residues: all                # or [0, 1, 2, ...] for specific 0-based indices
      epitope_residues: [42, 43, 44]    # optional; subset of crop_residues
      flexible_residues: [40, 41, 42]   # optional; subset of crop_residues
    B:
      chain_type: ligand
structure source variants

URL:

structure:
  type: url
  url: "https://example.com/target.cif"

Base64 (for a local file — use @data:// in the CLI, which detects binary and encodes):

structure:
  type: base64
  media_type: chemical/x-cif
  data: "@data:///abs/path/to/target.cif"

Do not use bare @path/to/file.cif here — automatic file-type detection has historically miscategorized CIF as plain text and broken the server parser. Prefer @data:// explicitly.

chain_selection values

Polymer chain:

A:
  chain_type: polymer
  crop_residues: all                  # or [int, ...]
  epitope_residues: [int, ...]        # optional; must be subset of crop_residues
  flexible_residues: [int, ...]       # optional; must be subset of crop_residues
  non_binding_residues: [int, ...]    # optional; subset of crop_residues, must NOT overlap epitope_residues

Ligand chain:

B:
  chain_type: ligand

All residue indices are 0-based.

target — variant 2: no_template

Use when the user has only sequences.

target:
  type: no_template
  entities:
    - type: protein
      chain_ids: [A]
      value: "QRTVEKATLLPNMPGQVLGHSSVLA"
      modifications: []               # optional
  epitope_residues:
    A: [42, 43, 44]                   # optional; 0-based
  epitope_ligand_chains: [C]          # optional
  bonds: []                           # optional
  constraints: []                     # optional

Optional fields:

  • epitope_residues — {chain_id: [0-based residue_index, ...]}. Hints the binding epitope.

  • non_binding_residues — {chain_id: [0-based residue_index, ...]}. Residues where binder contact is discouraged; must not overlap epitope_residues on the same chain.

  • epitope_ligand_chains — list of ligand chain IDs if the epitope includes a ligand.

  • bonds, constraints — same shapes as the structure-and-binding skill (see below).

bonds and constraints

Only include when the user explicitly asks for geometry constraints.

Bond shape
bonds:
  - atom1:
      type: polymer_atom
      chain_id: A
      residue_index: 12       # 0-based
      atom_name: SG
    atom2:
      type: ligand_atom
      chain_id: D
      atom_name: C1
Pocket constraint
constraints:
  - type: pocket
    binder_chain_id: B
    contact_residues:
      A: [42]                 # 0-based
    max_distance_angstrom: 6.0
    force: false              # optional
Contact constraint
constraints:
  - type: contact
    max_distance_angstrom: 5.0
    token1:
      type: polymer_contact
      chain_id: A
      residue_index: 42       # 0-based
    token2:
      type: polymer_contact
      chain_id: B
      residue_index: 10
    force: false

Token variants: polymer_contact {chain_id, residue_index} or ligand_contact {chain_id, atom_name}.

Atom-level ligand references (bonds and ligand_contact) support ligand_ccd only — a ligand_smiles chain referenced by atom is rejected; use a ligand_ccd entity instead.

Cost

Cost is tiered by total complex length (target + candidate), so there is no flat per-candidate rate to cite — it changes with size. Run estimate-cost on the full payload and quote only the estimated_cost_usd it returns; do not state or estimate a dollar figure yourself.

Outputs (after download-results)

Under <output-root>/<run-name>/:

  • .boltz-run.json

  • run.json — sanitized remote run record

  • results/index.jsonl — one scored candidate per line, copied from list-results metadata plus local artifact paths

  • results/<pres_*>/metadata.json — per-result metadata copied from the list-results record

  • results/<pres_*>/archive.tar.gz — one dir per scored candidate

  • results/<pres_*>/files/result/{metrics.json, <result-id>_predicted.cif, pae.npz} (the CIF is named <pres_*>_predicted.cif — prefer the paths.structure field from index.jsonl over hard-coding the filename)

Per-result fields (available in results/index.jsonl, results/<pres_*>/metadata.json, and the list-results stream):

  • id — server-assigned pres_* ID

  • external_id — echoed from the optional id on your input proteins[] entry

  • entities — echoed input entities for this candidate

  • metrics.binding_confidence — primary ranking metric

  • metrics.structure_confidence

  • metrics.iptm (higher is better)

  • metrics.min_interaction_pae (lower is better)

  • metrics.helix_fraction, metrics.sheet_fraction, metrics.loop_fraction

  • artifacts.structure.url, artifacts.archive.url (presigned, short-lived)

  • warnings — optional array of {code, message} quality flags (e.g. low_confidence, unusual_geometry); empty or absent on clean results. Surface them when presenting top hits.

optimization_score is not emitted for protein:library-screen. Sorting by it returns an empty list.

Rank from results/index.jsonl after download-results by binding_confidence descending. Use iptm (higher better) and min_interaction_pae (lower better) as tiebreakers.

Escape hatch

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Boltz
Publisher
OpenAI (Official)
Distributed by
OpenAI
Source
openai/plugins · plugins/boltz-api-cli/skills/boltz-protein-screen · commit d420d13
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from plugins/boltz-api-cli/LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Boltz or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download boltz-protein-screen.zip