按设计工作流程
- 作者仓库星标 80
- 作者仓库 blatant-why
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 92 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @001TMF · v1.0 · 未声明许可证
- 上下文用量评级
- 较高消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
{
"campaign_id": "tnf_alpha_20260520_001",
"engine": "boltzgen",
"protocol": "nanobody-anything",
"tier": "Standard",
"num_designs_per_scaffold": 5000,
"scaffolds": ["caplacizumab", "ozoralizumab"],
"compute_target": "local",
"compute_provider_source": ".by/config.json",
"estimated_wall_time_hours": 2.5,
"estimated_pass_rate_range": "20-40%",
"expected_passing_designs": 1500,
"rationale": "VHH modality (user-specified); 2 PDB co-crystals exist; pass rate is target-bucket median for well-studied antigens; local 1xH100 sufficient at this tier.",
"rerouting_triggers": ["local OOM (>1500 aa)", "<10% pass rate at 500 designs"],
"fallback_chain": ["local", "hpc(runpod)", "tamarind"],
"created_at": "2026-05-20T10:00:00Z"
}
# BY Design Workflow — Master Orchestration Skill
`by-design-workflow` is the **routing brain** of BY. It does not run any engine itself.
Instead, it answers four questions before any GPU compute is committed:
1. **Which engine?** — Protenix (fold), PXDesign (de novo binder), or BoltzGen (antibody / nanobody / fallback binder).
2. **Which preset / protocol / tier?** — Preview vs Standard vs Production vs Exploratory; `nanobody-anything` vs `antibody-anything` vs `protein-anything`; PXDesign `preview` vs `extended`.
3. **Which compute target?** — `local` (default), `hpc` (RunPod / Modal / SLURM via `by-deploy-compute`), or `tamarind` (cloud fallback).
4. **Accept or re-run?** — given the screening output, do the designs clear the quality bar, or does the campaign need a second pass with new hotspots, a new modality, or a different scaffold?
This skill encodes the canonical decision tree, the modality → tool mapping, the preset
comparison, the quality thresholds, and the accept-vs-re-run heuristics that other
skills depend on. It is the connective tissue between `by-research` / `by-campaign-manager`
(upstream) and the three tool wrappers `protenix`, `pxdesign`, `boltzgen` (downstream).
---
## When to Use This Skill
Use this skill when you have:
- ✅ **A new design project starting** — research is done, but the tool / preset / compute target has not been chosen yet
- ✅ **An ambiguous modality** — user said "I want a binder against X" without specifying antibody vs nanobody vs de novo
- ✅ **A target description but no plan** — PDB ID or sequence in hand, need a campaign sized end-to-end
- ✅ **A screening result and a decision to make** — designs are scored, should we lab-submit, re-run with new hotspots, or escalate?
- ✅ **A compute-target conflict** — local GPU OOMs on a 1500-residue target, decide HPC vs Tamarind vs target cropping
- ✅ **A novel target with no clear preset** — need to pick between Standard and Exploratory tiers based on prior-art density
- ✅ **A multi-target sweep request** — orchestrate the same protocol over N targets and decide whether to batch or serialize
Do NOT use this skill when:
- ❌ **You only need to run one engine right now** — invoke the engine's skill directly (`protenix`, `pxdesign`, or `boltzgen`). This skill is the planner, not a substitute for invoking the tool.
- ❌ **You are scoring or filtering existing designs** — that is `by-scoring` + `by-screening`.
- ❌ **You are managing campaign state / checkpoints / budget** — that is `by-campaign-manager`.
- ❌ **You need a PDB lookup, UniProt entry, or SAbDab query** — call the database MCP server directly or use `by-database`.
- ❌ **You are diagnosing a failed campaign in detail** — that is `by-failure-diagnosis` → `by-causal-reasoning`.
- ❌ **You want to skip the modality clarification step** — never trust a guessed modality. Always ask if the user has not specified.
🚨 **CRITICAL:** Never trust the routing decision without checking `.by/config.json` for the compute target. If `compute.fallback_allowed` is `false`, the choice between local / HPC / Tamarind is the **user's**, not yours. See `references/tool-selection-matrix.md` and the by-deploy-compute skill.
---
## Inputs
**Required:**
- **Target description** — exactly one of:
- PDB ID (e.g., `"7S4S"`) — most preferred; gives structure + chains + residue numbering
- UniProt accession (e.g., `"P01375"`) — sequence + features; structure inferred via Protenix if no PDB exists
- Bare sequence (FASTA) — least preferred; cannot resolve isoforms or residue numbering, requires Protenix fold first
- **Modality preference** (if known): `VHH` / `scFv` / `Fab` / `de_novo_binder` / `unknown`. If `unknown`, the skill ASKS — never guesses.
**Optional:**
- **Hotspot residues** (`label_seq_id` integers, per-chain) — if `by-research` or `by-epitope-analysis` already produced them, pass them through unchanged
- **Budget / timeline constraint** — e.g., `"under $500 cloud spend"`, `"results by Friday"`. Drives tier and compute-target choice.
- **Compute target preference** — `local` / `hpc` / `tamarind` / `auto`. Default `local`. Read `.by/config.json` first; explicit user override only on this turn.
- **Existing campaign plan** — `campaign_plan.md` from `by-campaign-manager`. If present, use it instead of re-deciding from scratch.
- **Prior-art context** — `design_recommendation.json` from `by-research`. If present, modality, scaffolds, and tier are already chosen; this skill validates and dispatches.
- **Acceptance criteria override** — non-default thresholds for ipSAE / ipTM / pLDDT / CA-RMSD (rarely used; default thresholds live in `references/quality-thresholds.md`).
See `references/tool-selection-matrix.md` for how each input combination maps to a routing decision.
---
## Outputs
This skill writes **routing artifacts**, not design data. Place them under the active
campaign directory at `campaigns/{target}/campaign_{date}_{id}/routing/`.
| File | Format | Purpose | Consumer |
|------|--------|---------|----------|
| `routing_decision.json` | JSON | Engine + preset + compute target + rationale | by-campaign-manager, the engine skill |
| `handoff_package.json` | JSON | Bundle of inputs the engine skill needs (target file, hotspots, YAML config skeleton) | protenix / pxdesign / boltzgen skill |
| `pass_rate_forecast.json` | JSON | Expected pass rate range + minimum-viable design count | by-campaign-manager (budgeting) |
| `accept_or_rerun.json` | JSON | After a campaign round: verdict (`ACCEPT` / `RERUN` / `SWITCH_TOOL` / `ESCALATE`) + reasoning | by-campaign-manager, the user |
**Key shape — `routing_decision.json`:**
```json
{
"campaign_id": "tnf_alpha_20260520_001",
"engine": "boltzgen",
"protocol": "nanobody-anything",
"tier": "Standard",
"num_designs_per_scaffold": 5000,
"scaffolds": ["caplacizumab", "ozoralizumab"],
"compute_target": "local",
"compute_provider_source": ".by/config.json",
"estimated_wall_time_hours": 2.5,
"estimated_pass_rate_range": "20-40%",
"expected_passing_designs": 1500,
"rationale": "VHH modality (user-specified); 2 PDB co-crystals exist; pass rate is target-bucket median for well-studied antigens; local 1xH100 sufficient at this tier.",
"rerouting_triggers": ["local OOM (>1500 aa)", "<10% pass rate at 500 designs"],
"fallback_chain": ["local", "hpc(runpod)", "tamarind"],
"created_at": "2026-05-20T10:00:00Z"
}
```
**Key shape — `accept_or_rerun.json`:**
```json
{
"campaign_id": "tnf_alpha_20260520_001",
"verdict": "RERUN",
"round_index": 1,
"metrics_summary": {
"designs_total": 500,
"ipsae_min_p50": 0.28,
"iptm_p50": 0.61,
"pass_rate": 0.08
},
"verdict_reasoning": "ipSAE p50 below 0.30 pass threshold; iptm acceptable. Hotspots likely too dispersed; shrink window from 8 to 4 residues centered on highest-conservation cluster.",
"next_action": "Re-run BoltzGen nanobody-anything with narrowed hotspots; same scaffolds; budget unchanged.",
"escalation_path": "If second round also fails, switch to PXDesign de novo (different paratope topology) before escalating to wet-lab epitope mapping."
}
```
---
## Clarification Questions
⚠️ **CRITICAL: ASK THIS FIRST** — never proceed without an unambiguous target + modality. Guessing burns compute.
1. **Target + modality (ASK THIS FIRST)** — What is the target (PDB ID or sequence), and what modality do you want — antibody (scFv / Fab), nanobody (VHH), de novo protein binder, or structure-only (no design, just folding)? If the user says "binder" without qualifier, ask the modality question explicitly.
2. **Compute target** — Local GPU (default), HPC (RunPod / Modal / SLURM), or Tamarind cloud? Read `.by/config.json` first; only ask if the file is missing or `compute.fallback_allowed` is `true` and the user has not specified.
3. **Tier and budget** — Preview (feasibility, ~5–500 designs), Standard (~5K designs), Production (~20K), or Exploratory (~50K, novel targets)? If the user gave a dollar budget or deadline, derive the tier from `references/preset-comparison.md`.
4. **Hotspots / epitope** — Already known (from `by-research` or `by-epitope-analysis`)? Or do we need to do epitope analysis first? For de novo binders without hotspots, PXDesign will run a hotspot-free preview but pass rates drop ~3×.
5. **Scaffold preference** — For antibody / nanobody runs: caplacizumab default for VHH, adalimumab default for scFv. Multiple scaffolds increase diversity but multiply design count. See `references/tool-selection-matrix.md` for the full list.
6. **Acceptance criteria** — Default thresholds (`ipSAE > 0.3`, `ipTM > 0.5`, `pLDDT > 70`, `CA-RMSD < 3.5 Å`)? Or stricter (`ipSAE > 0.5`, etc.) for high-stakes targets? Defaults live in `references/quality-thresholds.md`.
7. **Re-run policy** — If first-round pass rate is below 10%, what is the user's tolerance for re-running with adjusted hotspots vs switching tools vs escalating to wet lab? Default is **two re-runs, then switch tool, then escalate**.
---
## Decision Tree
This is the canonical routing logic. Walk it top-to-bottom; the first matching branch
wins. Full matrix (with rationale per cell) is in `references/tool-selection-matrix.md`.
```
User intent
│
├─ "Design a binder against <target>"
│ │
│ ├─ Antibody / nanobody?
│ │ ├─ Nanobody / VHH / single-domain / sdAb
│ │ │ → engine: boltzgen
│ │ │ protocol: nanobody-anything
│ │ │ default scaffolds: caplacizumab, ozoralizumab
│ │ │ typical pass rate: 15-40%
│ │ │
│ │ └─ Full antibody / scFv / Fab / IgG / mAb
│ │ → engine: boltzgen
│ │ protocol: antibody-anything
│ │ default scaffolds: adalimumab, tezepelumab
│ │ typical pass rate: 10-30%
│ │ note: post-design VH-(G4S)3-VL conversion for scFv
│ │
│ └─ De novo protein binder (non-antibody, non-nanobody)?
│ ├─ Standard target (PDB exists, hotspots known)
│ │ → engine: pxdesign
│ │ preset: extended (production) | preview (feasibility)
│ │ typical pass rate: 17-82% (target-dependent)
│ │
│ └─ PXDesign env/CUDA issue OR novel topology
│ → engine: boltzgen
│ protocol: protein-anything
│ typical pass rate: 10-25%
│
├─ "Predict / validate a structure" (no design)
│ → engine: protenix
│ model: base_default (recommended) | base_20250630 (latest) | mini (fast)
│ seeds: [42] single, [42,123,456,789,1024] ensemble
│ note: ALWAYS run before designing to validate target fold
│
├─ "Score / re-rank existing designs"
│ → NOT this skill. Dispatch to by-scoring + by-screening.
│
└─ "Analyze a target / find hotspots"
→ NOT this skill. Dispatch to by-research + by-epitope-analysis.
```
### Resolved routing — quick lookup
| Modality | Engine | Protocol / Preset | Default Tier | Pass Rate (median) | Default Compute |
|----------|--------|-------------------|--------------|--------------------|-----------------|
| VHH (nanobody) | BoltzGen | `nanobody-anything` | Standard | 25% | local GPU |
| scFv / Fab / IgG | BoltzGen | `antibody-anything` | Standard | 20% | local GPU |
| De novo binder (well-studied) | PXDesign | `extended` | Standard | 30-50% | local GPU |
| De novo binder (feasibility) | PXDesign | `preview` | Preview | 10-30% | local GPU |
| De novo binder (fallback) | BoltzGen | `protein-anything` | Standard | 15% | local GPU |
| Structure prediction | Protenix | `base_default` | n/a | n/a | local GPU |
| Multi-seed ensemble fold | Protenix | `base_default`, 5 seeds | n/a | n/a | local GPU |
For full matrix (rows: VHH / scFv / Fab / de novo / ligand-binding / structure-only;
columns: tool / preset / hotspot guidance / pass rate / compute), see
`references/tool-selection-matrix.md`.
---
## Quick Start
A typical "design a binder against TNF-alpha" request, end-to-end:
```text
User: "I want a nanobody against TNF-alpha. Use local GPU. Standard tier."
Agent (this skill):
1. Read .by/config.json → compute.default_provider="local", local engine paths.
2. Load research/design_recommendation.json (if exists) → modality=VHH, scaffolds=[caplacizumab, ozoralizumab].
3. python3 scripts/route_intent.py --mode route \
--intent-json intent.json --config-json .by/config.json \
--out-dir campaigns/tnf_alpha/.../routing/
✓ Routing decision written: routing/routing_decision.json
(engine=boltzgen, protocol=nanobody-anything, tier=Standard, compute=local)
✓ Handoff package written: routing/handoff_package.json
(scaffolds=2, designs_per_scaffold=5000)
4. python3 scripts/estimate_design_space.py \
--modality VHH --tier Standard --num-scaffolds 2 \
--target-class well_studied --compute-target local \
--out-dir campaigns/tnf_alpha/.../routing/
✓ Forecast written: routing/pass_rate_forecast.json
(total_designs=10000, expected_passing=3500, wall_hours=5.0, cost=$0.00)
5. Hand off to by-campaign-manager → writes campaign_plan.md
6. Hand off to boltzgen skill → runs the actual design
7. (Later) After by-screening completes:
python3 scripts/route_intent.py --mode accept-or-rerun \
--screening-summary screening_summary.json \
--routing-decision routing/routing_decision.json \
--out-dir campaigns/tnf_alpha/.../routing/
✓ Accept-or-rerun verdict written: routing/accept_or_rerun.json
(verdict=ACCEPT, pass_rate=24.0%)
```
Expected total time for the routing step (this skill): under 30 seconds. The
actual design compute is handled by the engine skill that follows.
---
## Residue Numbering Convention
All BY tools use **`label_seq_id`**: 1-indexed, sequential, per-chain, no gaps. This
differs from `auth_seq_id` (the PDB author numbering with gaps and insertion codes)
and from 0-indexed array positions.
| Identifier | Format | Used By |
|------------|--------|---------|
| `label_seq_id` | 1-indexed, sequential, per-chain integer | every BY engine (canonical) |
| `auth_seq_id` | PDB author numbering, may have gaps / insertion codes | external publications, PyMOL |
| Array index | 0-indexed Python position | internal scripts only |
**Tool-specific encoding:**
- PXDesign `hotspot_residues`: list of `"<chain><label_seq_id>"` strings, e.g. `["A45", "A50"]`.
- BoltzGen `epitope_residues`: list of `label_seq_id` integers per chain, e.g. `[45, 50, 52]`.
- Protenix: full sequences in JSON; no residue-level specification needed.
**Common pitfall:** users frequently paste residue numbers from a publication or
PyMOL session (`auth_seq_id`). Wrong hotspot numbering wastes the entire campaign.
This skill's handoff package stores the mapping `auth_seq_id_map` so the engine
skill can validate against the target structure before launching.
---
## Compute Target Selection
The compute target is read from `.by/config.json` → `compute.default_provider`. The
skill never silently overrides this — even if the requested target appears
unavailable, it ASKS the user before switching.
| Provider | Cost | Latency | When to Use | When NOT to Use |
|----------|------|---------|-------------|------------------|
| `local` | $0 | None (instant) | Default — user owns the hardware | Target > local memory budget |
| `hpc` (RunPod / Modal / SLURM) | $3-5 / GPU-hr | minutes (cold start) | Local OOM, multi-GPU production runs | When local has capacity |
| `tamarind` | $5+ / GPU-hr | minutes-hours (cold-start queue) | No local GPU, no HPC account | If local or HPC is available |
When `compute.fallback_allowed=true` in config, the skill may auto-promote
local → hpc → tamarind in the order specified by `compute.providers_priority`. When
`fallback_allowed=false`, ANY switch requires the user's explicit approval — this
is a budget-protection property and must not be bypassed.
See `by-deploy-compute/SKILL.md` for the canonical HPC dispatch logic. This skill
does NOT re-document compute setup — it only decides which provider to use.
---
## Campaign Cost Quick Reference
Rough budget envelopes (HPC pricing; local is $0 cash but consumes wall time):
| Campaign Profile | Total Designs | HPC Cost (approx) | Local Wall Time | When |
|------------------|---------------|--------------------|--------------------|------|
| Preview only | 500-1000 | $5-15 | ~1 hr | Feasibility |
| Standard, 1 modality | 5K-10K | $50-100 | 3-5 hr | Exploration |
| Standard, 2 modalities | 10K-20K | $100-200 | 6-10 hr | Modality comparison |
| Production, 1 modality | 20K-40K | $250-500 | 10-20 hr | Final candidate pool |
| Exploratory, multi-modality | 50K-100K | $1000-2000 | 25-50 hr | Novel target, publication-grade |
Adaptyv Bio lab follow-up adds $119-$215 per design; budget 5-20 lab tests for a
Standard campaign, 30-50 for Production. Turnaround 2-4 weeks.
---
## Standard Workflow
🚨 **MANDATORY: USE THE SCRIPTS BELOW TO PRODUCE ROUTING ARTIFACTS — DO NOT IMPROVISE INLINE DECISIONS** 🚨
Every routing decision must produce a `routing_decision.json` written by the script,
not free-text. Every accept-vs-re-run verdict must produce an `accept_or_rerun.json`.
1. **Read `.by/config.json`** — Pull `compute.default_provider`, `compute.fallback_allowed`, `compute.providers_priority`, and the local engine paths. If the file is missing, prompt for `by-session` first.
2. **Load upstream artifacts** — `campaigns/{target}/.../research/design_recommendation.json` (from `by-research`) and `campaigns/{target}/.../research/recommended_hotspots.json` (from `by-epitope-analysis`). If present, modality and scaffolds are already chosen.
3. **Resolve the routing decision** — Run `scripts/route_intent.py` with the merged inputs:
```bash
python3 scripts/route_intent.py \
--intent-json /path/to/intent.json \
--config-json /path/to/.by/config.json \
--out-dir campaigns/{target}/.../routing/
```
Writes `routing_decision.json`. Verification: `✓ Routing decision written: routing/routing_decision.json (engine=boltzgen, protocol=nanobody-anything)`.
4. **Forecast pass rate and design count** — Before launching compute, estimate budget:
```bash
python3 scripts/estimate_design_space.py \
--modality VHH \
--tier Standard \
--num-scaffolds 2 \
--out-dir campaigns/{target}/.../routing/
```
Writes `pass_rate_forecast.json`. Verification: `✓ Forecast written: routing/pass_rate_forecast.json (expected_passing=1500, wall_hours=2.5)`.
5. **Hand off to the engine skill** — The engine skill (`protenix`, `pxdesign`, or `boltzgen`) reads `routing_decision.json` + `handoff_package.json` and produces the actual designs. This skill does NOT invoke the engine directly.
6. **After screening, compute accept-or-rerun** — Once `by-screening` writes the per-round summary, run:
```bash
python3 scripts/route_intent.py \
--mode accept-or-rerun \
--screening-summary /path/to/screening_summary.json \
--routing-decision /path/to/routing_decision.json \
--out-dir campaigns/{target}/.../routing/
```
Writes `accept_or_rerun.json` with verdict ∈ {`ACCEPT`, `RERUN`, `SWITCH_TOOL`, `ESCALATE`}.
**Discipline:**
- ✅ Always write `routing_decision.json` before any compute is submitted
- ✅ Always re-read `.by/config.json` at the start — provider can change between sessions
- ✅ Always pass the resolved `compute_target` to the engine skill in the handoff package (do not let the engine guess)
- ❌ Do NOT silently switch compute providers when `compute.fallback_allowed=false`
- ❌ Do NOT skip the pass-rate forecast — it is what `by-campaign-manager` uses for budget gating
- ❌ Do NOT make the accept-vs-rerun call from memory — run the script so the verdict is auditable
---
## When Scripts Fail
Both scripts are stdlib-only Python (`json`, `argparse`, `pathlib`). Failure modes:
1. **Fix and Retry (90%)** — Almost always a missing input file or wrong path. Re-check the `--config-json` and `--intent-json` paths. Confirm `.by/config.json` exists by running `by-session`.
2. **Modify Script (5%)** — If the engine catalog changes (new protocol, new preset), edit the lookup tables at the top of `scripts/route_intent.py` and `references/tool-selection-matrix.md` together. Keep CLI signatures stable.
3. **Use as Reference (4%)** — If the routing decision needs custom logic (e.g., multi-target sweep), read the script for the canonical heuristics, then write the JSON by hand following the schema in `routing_decision.json`. Cite the source script in `rationale`.
4. **Write from Scratch (1%)** — Only if the inputs cannot be reconciled with the existing schema (rare). Document why in `routing/notes.md` and submit the new schema for review.
If the upstream artifacts (`design_recommendation.json`, `recommended_hotspots.json`) are
missing, the correct response is to invoke `by-research` first — not to invent values.
---
## Common Issues
| Issue | Cause | Solution | Details |
|-------|-------|----------|---------|
| User says "design a binder" without modality | Ambiguous request; could be VHH, scFv, or de novo | Ask Q1 explicitly. Do NOT default to VHH silently — confirm before routing. | `references/tool-selection-matrix.md` |
| Target has no PDB structure | Sequence-only target; no experimental fold | Run Protenix fold first (single seed for preview, 5-seed ensemble for production). Crop high-pLDDT domain if full-length is disordered. | `references/quality-thresholds.md` Fold-Validation |
| Target > 1500 residues, local OOMs | BoltzGen / PXDesign exceeds 80 GB at full target | Crop to binding domain + 10 Å buffer; if still OOM, switch compute target to HPC (RunPod A100/H100 80GB) via by-deploy-compute. | `references/preset-comparison.md` Memory-by-Tier |
| Multi-chain complex target (e.g., trimer) | Hotspots span multiple chains; tools default to one target chain | Set target as the assembled complex; specify hotspots with chain prefix (`A45,B112`); pre-validate fold with Protenix multimer prediction. | `references/tool-selection-matrix.md` Multi-Chain |
| Multi-target screening request | User wants the same protocol against N targets | Sequential: one routing decision per target; share scaffold pool. Parallel: batch via by-deploy-compute HPC array job. Choose by total design count: < 5K total → sequential; ≥ 5K → batch. | `references/preset-comparison.md` Multi-Target |
| Off-target / polyspecificity concern | Therapeutic candidate must avoid binding human paralogs | Add post-design polyspecificity screen via by-screening (`screen_cross_validate`); reduce composite weight on `ipSAE_min` and add explicit cross-reactivity penalty. | `references/quality-thresholds.md` Polyspecificity |
| Low compute budget, large design space | Tier mismatch: user wants Production but budget covers Preview | Run Preview tier first, gate Production on Preview pass rate ≥ 15%; if not, escalate to user. Never silently shrink Production to Preview. | `references/preset-comparison.md` Budget-Gating |
| `compute.default_provider="local"` but local GPU absent | `.by/config.json` stale or wrong machine | Run `by-session` to re-detect compute; if no local GPU, prompt user to switch to `hpc` or `tamarind`. Never silently route to cloud. | by-deploy-compute SKILL.md |
| PXDesign fails twice in a row | CUDA / env mismatch on local install | Switch to BoltzGen `protein-anything` (de novo fallback) after 1 failed launch. Do NOT spend multiple cycles fixing PXDesign env mid-campaign. | `references/tool-selection-matrix.md` De-Novo-Fallback |
| Designs have good ipTM but low ipSAE | Interface confident but partial; ipSAE asymmetry > 0.3 | Re-run with tightened hotspots (drop 1-2 residues at the edges); if asymmetric ipSAE persists, switch modality (de novo → VHH may engage differently). | `references/quality-thresholds.md` ipSAE-Asymmetry |
| Pass rate < 10% on Preview | Hotspots too dispersed or wrong epitope | Re-run epitope analysis (`by-epitope-analysis`); narrow hotspot window to 3-5 spatially clustered residues. If second Preview also fails, escalate. | `references/quality-thresholds.md` Re-Run-Criteria |
| Modality unclear, user wants "best chance" | No modality preference, novel target | Default order: VHH (highest pass rate, simplest), then scFv, then de novo. Justify the choice in `routing_decision.json.rationale`. | `references/tool-selection-matrix.md` Modality-Selection |
| Target is a ligand / small molecule, not protein | Wrong tool family — BY engines are protein-protein interfaces | Refuse the campaign politely. Suggest small-molecule docking tools (out of scope for BY). Document refusal in `routing/notes.md`. | `references/tool-selection-matrix.md` Out-Of-Scope |
| Glycosylated surface near hotspots | BoltzGen does not model glycans by default | Implementation-engineer persona in `by-research` Phase 6 should have flagged this. Shift hotspot window or accept reduced confidence. | by-research SKILL.md Phase 6 |
---
## Best Practices
1. 🚨 **CRITICAL: Always read `.by/config.json` first.** The compute provider is the user's choice, not yours.
2. 🚨 **CRITICAL: Never silently default a modality.** Ask Q1 if the user said "binder" without qualifier.
3. ✅ **REQUIRED: Write `routing_decision.json` before any compute is submitted.** It is the audit trail.
4. ✅ **REQUIRED: Pass `compute_target` explicitly to the engine skill.** Do not let `boltzgen` / `pxdesign` / `protenix` guess from environment.
5. ✅ Run Preview before Production for any novel target. Cheaper to fail at 500 designs than 20,000.
6. ✅ Validate target fold with Protenix before any design run on a target with no experimental structure.
7. ✅ Use `label_seq_id` (1-indexed, sequential, per-chain) for hotspot residues. Convert from `auth_seq_id` if user provides PDB numbering.
8. ✅ Prefer `local` compute when available — fastest, free, and the user already paid for the hardware.
9. ✨ **Optional:** Run a hypothesis-debate (`by-hypothesis-debate`) when multiple modalities are viable. A few minutes of reasoning saves hours of compute.
10. ❌ Do NOT skip the pass-rate forecast even on "obvious" campaigns — it is the budget gate.
11. ❌ Do NOT bypass `by-campaign-manager` for the actual campaign plan. This skill makes the routing decision; `by-campaign-manager` owns the plan and state machine.
12. ❌ Do NOT improvise new presets / protocols / scaffolds. If the catalog needs an addition, update `references/tool-selection-matrix.md` and `scripts/route_intent.py` together.
---
## Suggested Next Steps
After this skill produces `routing_decision.json` and `handoff_package.json`, chain into:
1. **`by-campaign-manager`** — write the canonical `campaign_plan.md` from the routing decision and the pass-rate forecast. Required before any compute is committed; manages state machine + budget + checkpoints.
2. **The engine skill** — one of:
- **`protenix`** — for structure prediction / fold validation. Always run this first if the target has no experimental structure.
- **`pxdesign`** — for de novo protein binder design. Write YAML → `pxdesign pipeline` → read `summary.csv`.
- **`boltzgen`** — for antibody / nanobody design (or de novo fallback). Write entities YAML → `boltzgen run` → read `final_designs_metrics_*.csv`.
3. **`by-deploy-compute`** (if compute target is `hpc`) — packages the engine container, syncs target data, dispatches the job. Handles RunPod / Modal / SLURM.
4. **`by-screening`** — runs the full screening battery (ipSAE, ipTM, pLDDT, RMSD, liabilities, developability) on the design output. Writes `screening_summary.json`.
5. **`by-scoring`** — applies canonical formulas (composite, multi-seed aggregation, asymmetry checks) on top of screening output.
6. **Back to `by-design-workflow`** (this skill) in `accept-or-rerun` mode — after screening, compute the verdict (`ACCEPT` / `RERUN` / `SWITCH_TOOL` / `ESCALATE`).
7. **`by-failure-diagnosis`** (conditional) — invoked when the verdict is `RERUN` or `SWITCH_TOOL`; identifies the specific failure mode driving low pass rate.
This chain works because every downstream skill expects exactly the JSON shapes this skill writes. The handoff package is the contract; bypassing it forces the next skill to re-derive routing context from scratch.
---
## Related Skills
**Upstream (run before this):**
- `by-session` — initializes config, ensures `.by/config.json` exists with compute provider.
- `by-research` — produces `design_recommendation.json` (modality, scaffolds, tier).
- `by-epitope-analysis` — produces `recommended_hotspots.json` (residue list with confidence).
- `by-hypothesis-debate` — produces adversarial-ranked strategy when multiple modalities are viable.
**Downstream (run after this):**
- `by-campaign-manager` — writes `campaign_plan.md` from routing decision + forecast.
- `protenix`, `pxdesign`, `boltzgen` — the three engine wrappers that actually run the design.
- `by-deploy-compute` — HPC dispatch for `hpc` compute target.
- `by-screening` + `by-scoring` — evaluate the design output.
- `by-failure-diagnosis` — diagnose RERUN / SWITCH_TOOL verdicts.
**Alternative / complementary:**
- `by-database` — direct PDB / UniProt / SAbDab lookups without the campaign overhead.
- `by-display` — render the routing decision + forecast as a user-facing table.
---
## References
**Detailed documentation (this skill):**
- [`references/tool-selection-matrix.md`](references/tool-selection-matrix.md) — full modality × tool × preset × hotspot × pass rate × compute matrix with per-cell rationale.
- [`references/preset-comparison.md`](references/preset-comparison.md) — Preview vs Standard vs Production vs Exploratory comparison across BoltzGen + PXDesign; cost, time, diversity, recommended use case for each.
- [`references/quality-thresholds.md`](references/quality-thresholds.md) — acceptance criteria by modality (ipSAE / ipTM / pLDDT / CA-RMSD); when to ACCEPT, RERUN, SWITCH_TOOL, ESCALATE.
**Scripts:**
- [`scripts/route_intent.py`](scripts/route_intent.py) — CLI: input intent JSON (target, modality, budget, compute pref) → output `routing_decision.json` + `handoff_package.json`; also handles `accept-or-rerun` mode after screening.
- [`scripts/estimate_design_space.py`](scripts/estimate_design_space.py) — CLI: input modality + tier + scaffold count → estimate total design count, wall time hours, expected passing designs based on canonical pass-rate buckets.
**Cross-skill canonical sources:**
- [`templates/.claude/skills/README.md`](../README.md) — canonical terminology, skill linkage map, end-to-end workflow.
- [`templates/CLAUDE.md`](../../../CLAUDE.md) — BY agent identity, compute provider selection, campaign workflow overview.
- [`by-research/SKILL.md`](../by-research/SKILL.md) — produces upstream `design_recommendation.json`.
- [`by-campaign-manager/SKILL.md`](../by-campaign-manager/SKILL.md) — consumes downstream `routing_decision.json`.
- [`by-deploy-compute/SKILL.md`](../by-deploy-compute/SKILL.md) — HPC dispatch details (do not re-document here).
- [`by-scoring/SKILL.md`](../by-scoring/SKILL.md) — canonical ipSAE / ipTM / composite formulas.
- [`by-screening/SKILL.md`](../by-screening/SKILL.md) — full screening battery + PASS / FAIL gates.
**External documentation:**
- BoltzGen: project README in the local install (see `compute.local.boltzgen.path` in `.by/config.json`).
- PXDesign: project README in the local install (see `compute.local.pxdesign.path`).
- Protenix: https://github.com/bytedance/Protenix
章节与文件索引
按说明文件中的顺序排列。
何时使用此技能
输入
输出
澄清问题
决策树
文件/命令 -> by-design-workflow · nanobody-anything · antibody-anything · protein-anything · preview · extended · local · hpc
内容校验值 -> 889eee9f6578
当前原文的自动摘译,尚未人工审校。
何时使用此技能
当您满足以下条件时,请使用此技能: ✅ 一个新的设计项目开始 - 研究已完成,但尚未选择工具/预设/计算目标 ✅ 模棱两可的模式 - 用户说“我想要针对 X 的结合剂”,但没有指定抗体、纳米抗体或从头 ✅ 目标描述,但没有计划 - 手中有 PDB ID 或序列,需要一个端到端的活动规模 ✅ 筛选结果和做出的决定 - 设计已评分,我们应该实验室提交,用新的重新运行热点,还是升级?
输入
必需:目标描述 - 恰好是以下之一:PDB ID(例如,
"7S4S") - 最优先;给出结构+链+残基编号UniProt登录(例如,"P01375")-序列+特征;如果不存在 PDB,则通过 Protenix 推断结构 裸序列 (FASTA) — 最不推荐;无法解析同种型或残基编号,需要先进行 Protenix 折叠输出
该技能编写路由工件,而不是设计数据。将它们放在
campaigns/{target}/campaign_{date}_{id}/routing/的活动活动目录下。文件·格式·目的·消费者routing_decision.json·JSON·引擎+预设+计算目标+基本原理·由营销经理,引擎技能handoff_package.json·JSON·引擎技能所需的输入包(目标文件,热点,YAML配置框架)·protenix / pxdesign / Bolzgen技能澄清问题
⚠️ 重要:首先要问这个——没有明确的目标+模式,切勿继续。猜测燃烧计算。靶点 + 形式(首先询问这个) - 靶点是什么(PDB ID 或序列),您想要什么形式 - 抗体 (scFv / Fab)、纳米抗体 (VHH)、从头蛋白结合剂或纯结构(无设计,仅折叠)?如果用户在没有限定词的情况下说出“binder”,请明确询问模态问题。
决策树
这是规范的路由逻辑。从上到下走一遍;第一个匹配的分支获胜。完整矩阵(每个单元格的基本原理)位于
references/tool-selection-matrix.md中。