Update to Boltz

{
  "name": "boltz-small-molecule-screen",
  "description": "Screen existing small-molecule libraries with Boltz. Use when docking, scoring, or ranking a supplied SMILES or compound library against a target; also returns free Tier-1 ADME/ADMET (solubility, permeability, lipophilicity/logD) per molecule. Not for de novo molecule design, one-off docking, or ADME on bare SMILES with no target (use boltz-small-molecule-adme).",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 246
    },
    {
      "relative_path": "references/api.md",
      "size_in_bytes": 9495
    },
    {
      "relative_path": "references/results.md",
      "size_in_bytes": 2255
    }
  ],
  "skill_md_contents": "---\nname: boltz-small-molecule-screen\ndescription: Screen existing small-molecule libraries with Boltz. Use when docking, scoring, or ranking a supplied SMILES or compound library against a target; also returns free Tier-1 ADME/ADMET (solubility, permeability, lipophilicity/logD) per molecule. Not for de novo molecule design, one-off docking, or ADME on bare SMILES with no target (use boltz-small-molecule-adme).\n---\n\n## Workflow\n\nIf `boltz-api` is missing from `PATH`, use `boltz-cli-setup` for install/update guidance before retrying.\nIf 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.\nIf 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.\n\nUse this skill when the user already has candidate molecules.\n\n1. Normalize the library from raw SMILES, a CSV (auto-detect the SMILES column), `.smi`, or `.txt` into the `molecules` list. Each entry is `{smiles, id?}`; the optional `id` is echoed back as `external_id` on each result.\n2. Normalize the target: one or more protein sequences into `target.entities`, plus optional `pocket_residues` (0-based) and/or `reference_ligands` (SMILES of known binders to help locate the pocket).\n3. Keep default server-side filtering unless the user asks for custom filters — only add `molecule_filters` on explicit request.\n4. Author the payload YAML or JSON, run `estimate-cost`, show the USD cost, wait for explicit confirmation.\n5. `start` to submit (synchronous). Capture the ID.\n6. Launch `download-results` with the agent runtime's background/non-blocking command facility — it polls, paginates `list-results`, downloads every per-hit structure, and exits when terminal. 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.\n7. When done, rank from `<output-root>/<run-name>/results/index.jsonl`. Sort by `binding_confidence` for hit discovery or `optimization_score` for lead optimization; these are parallel intents, not a fallback hierarchy. Report the top 5-10 hits with `smiles`, the chosen ranking metric, key confidence metrics, and structure path. Each result also carries a free `adme` block (`solubility`, `permeability`, `lipophilicity`) — include it for developability triage when the user cares about ADME, or when a top hit looks risky. Read [references/results.md](references/results.md) for output layout, metrics, ADME, and filtered-input accounting.\n\n## Command Pattern\n\n```bash\n# Replace placeholders with concrete absolute paths before running.\n# Use a short descriptive run name, for example: sm-screen-<target>-<library>-v1\n\nboltz-api small-molecule:library-screen estimate-cost \\\n  --input @yaml:///absolute/path/payload.yaml\n\nboltz-api small-molecule:library-screen start \\\n       --idempotency-key \"<run-name>\" \\\n       --input @yaml:///absolute/path/payload.yaml \\\n       --raw-output --transform id\n\n# Copy the printed job ID into this command, then launch it in the agent\n# runtime's background/non-blocking mode.\n# Claude Code: Bash with run_in_background=true.\n# Codex: foreground shell command with yield_time_ms=1000; keep the returned session_id if one is provided.\n# Do not append \"&\" or use nohup in Codex.\nboltz-api download-results \\\n  --id \"<job-id-from-start>\" --name \"<run-name>\" \\\n  --root-dir \"/absolute/path/boltz-experiments\" \\\n  --poll-interval-seconds 30\n# -> /absolute/path/boltz-experiments/<run-name>/results/<pres_*>/...\n```\n\nPayload keys are `molecules`, `target`, `molecule_filters` — the API body field names, not the direct CLI flag names `--molecule` / `--target` / `--molecule-filters`.\n\n## Always Do This\n\n- Keep payload field names exactly as the API body names shown in `references/api.md`.\n- 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.\n- 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.\n- Direct object flags still work as overrides, such as `--target @yaml:///absolute/path/target.yaml`, `--molecule-filters @json:///absolute/path/filters.json`, or repeated `--molecule @json:///absolute/path/mol-1.json` entries. Piped YAML / JSON on stdin also works, but it must use API body field names. Never use `@file://` or `@./`.\n- Treat pocket residue indices as 0-based.\n- Do not invent medicinal-chemistry filters. Only add `molecule_filters` if the user asks; mention the catalog as an option.\n- Use the same slug as both `--idempotency-key` at submit and `--name` on `download-results` so re-runs resume via `.boltz-run.json`.\n- 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.\n- 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.\n- After the background/session starts, do not manually wait on it or run ad hoc polling loops. `download-results` emits JSONL progress on stderr by default; add `--progress-format text --verbose` only when you explicitly want human-readable logs.\n- 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 molecule 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.\n- 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`.\n- If detached download needs to be restarted, re-run `boltz-api download-results` with the same `--name \"<run-name>\"` and the same `--root-dir`.\n- Cost is a flat $0.025 per molecule (size-independent). `estimate-cost` returns the authoritative total — always use it.\n- Poll interval: `--poll-interval-seconds 30` is a reasonable downloader default. Wall-clock time scales roughly with the number of molecules: 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, and never tell the user a 10-candidate screen will take 30 minutes or hours.\n\n## Escape Hatch\n\n- Payload reference: <https://api.boltz.bio/docs/api/python/resources/small_molecule/subresources/library_screen/methods/start>\n- CLI flag names: `boltz-api small-molecule:library-screen start --help`\n\nRead [references/api.md](references/api.md) for the `molecules`, `target`, and `molecule_filters` shapes, including the built-in SMARTS filters and RDKit descriptor ranges. Read [references/results.md](references/results.md) after download when ranking hits or explaining missing/filtered inputs.\n\n## Outputs\n\nRank from `results/index.jsonl` after `download-results`; use [references/results.md](references/results.md) for the local file layout, metric meanings, and filtered-input accounting.\n"
}