From boltz
Boltz job status and result recovery. Use when listing jobs, checking progress, resuming downloads, recovering results, or downloading an existing job ID. Not for starting new jobs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/boltz:boltz-check-statusThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
If `boltz-api` is missing from `PATH`, use `boltz-cli-setup` for install/update guidance before retrying.
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 to recover state across sessions and to inspect or download results for prior Boltz jobs. No payload authoring — this skill only calls list / retrieve / download-results / download-status.
Use four modes:
download-status before remote API calls.created_at descending.download-results with the original run name when possible. Never run start again to resume.Read references/resume.md before recovering a dropped session, mapping job ID prefixes, or choosing a run name for download-results. Read references/api.md for per-resource list columns, retrieve fields, and result semantics.
# Replace placeholders with concrete absolute paths before running.
# Local helper: inspect local checkpoint state without API calls.
boltz-api --format json download-status \
--name "<run-name>" \
--root-dir "/absolute/path/boltz-experiments"
# Mode 1: list recent jobs across all 5 resources.
# NB: the CLI emits one JSON object per record (streamed, no {data:[]} wrapper).
# --limit is per-page and the CLI auto-paginates, so cap each explicit command with head.
boltz-api predictions:structure-and-binding list --limit 20 --format jsonl | head -20
boltz-api small-molecule:library-screen list --limit 20 --format jsonl | head -20
boltz-api small-molecule:design list --limit 20 --format jsonl | head -20
boltz-api protein:library-screen list --limit 20 --format jsonl | head -20
boltz-api protein:design list --limit 20 --format jsonl | head -20
# Mode 2: retrieve by ID. Pick the resource from the ID prefix in the workflow
# notes above. If the prefix is unknown, run these one at a time until one succeeds.
boltz-api predictions:structure-and-binding retrieve --id "<job-id>" --format json
boltz-api small-molecule:library-screen retrieve --id "<job-id>" --format json
boltz-api small-molecule:design retrieve --id "<job-id>" --format json
boltz-api protein:library-screen retrieve --id "<job-id>" --format json
boltz-api protein:design retrieve --id "<job-id>" --format json
# Mode 3: resume download. Use the agent runtime's managed long-running command mode.
boltz-api download-results \
--id "<job-id>" --name "<run-name>" \
--root-dir "/absolute/path/boltz-experiments" \
--poll-interval-seconds 30
download-status before retrieve.--root-dir. Do not cd into the run directory; that makes later relative paths point at the run directory instead of the user's workspace.idempotency_key.--name — it resumes into the existing dir with cursor.boltz-api. Prefer running the five list / retrieve commands explicitly over generating them from a shell loop; a fixed | head -20 cap is okay when listing to avoid runaway streamed output.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.download-results now emits machine-readable JSONL progress on stderr by default. Add --progress-format text --verbose only when you explicitly want human-readable logs.download-status for local checkpoint state or, in Codex, poll the saved session with an empty write_stdin to read JSONL stderr if the session is still running. Don't loop retrieve unless the user wants fresh remote status.retrieve surfaces only {"code":"VALIDATION_ERROR","message":"Request validation failed"} with no details, that's expected for predictions:structure-and-binding failures — other endpoints include field paths.start again on a failed or interrupted job. Fix the payload and submit with a new idempotency-key, or just resume with download-results.list / retrieve methods): https://api.boltz.bio/docs/api/pythonboltz-api <resource> list --help, boltz-api <resource> retrieve --help, boltz-api download-results --help, boltz-api download-status --help<output-root>/<run-name>/ — same layout as a fresh run. Read references/resume.md for resume behavior.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub boltz-bio/boltz-api-skills --plugin boltz