by-design-workflow
- Repo stars 80
- Author updated Live
- Author repo blatant-why
- Domain
- Design
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 92 / 100 · audit passed
- Author / version / license
- @001TMF · v1.0 · no license declared
- Token usage
- Heavy
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: by-design-workflow
description: Instead, it answers four questions before any GPU compute is committed: This skill encodes the c…
category: design
runtime: Python
---
# by-design-workflow output preview
## PART A: Task fit
- Use case: Instead, it answers four questions before any GPU compute is committed: 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 t….
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When to Use This Skill / Inputs / Outputs” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Instead, it answers four questions before any GPU compute is committed: 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 t…”.
- **02** When the source has headings, the agent prioritizes “When to Use This Skill / Inputs / Outputs” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/path`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “When to Use This Skill / Inputs / Outputs”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: by-design-workflow
description: Instead, it answers four questions before any GPU compute is committed: This skill encodes the c…
category: design
source: 001TMF/blatant-why
---
# by-design-workflow
## When to use
- Instead, it answers four questions before any GPU compute is committed: This skill encodes the canonical decision tree…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “When to Use This Skill / Inputs / Outputs” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "by-design-workflow" {
input -> user goal + target files + boundaries + acceptance criteria
context -> When to Use This Skill / Inputs / Outputs
rules -> SKILL.md triggers / order / output contract
runtime -> Python | read files, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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:
- Which engine? — Protenix (fold), PXDesign (de novo binder), or BoltzGen (antibody / nanobody / fallback binder).
- Which preset / protocol / tier? — Preview vs Standard vs Production vs Exploratory;
nanobody-anythingvsantibody-anythingvsprotein-anything; PXDesignpreviewvsextended. - Which compute target? —
local(default),hpc(RunPod / Modal / SLURM viaby-deploy-compute), ortamarind(cloud fallback). - 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, orboltzgen). 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
- PDB ID (e.g.,
- Modality preference (if known):
VHH/scFv/Fab/de_novo_binder/unknown. Ifunknown, the skill ASKS — never guesses.
Optional:
- Hotspot residues (
label_seq_idintegers, per-chain) — ifby-researchorby-epitope-analysisalready 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. Defaultlocal. Read.by/config.jsonfirst; explicit user override only on this turn. - Existing campaign plan —
campaign_plan.mdfromby-campaign-manager. If present, use it instead of re-deciding from scratch. - Prior-art context —
design_recommendation.jsonfromby-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:
{
"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:
{
"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.
- 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.
- Compute target — Local GPU (default), HPC (RunPod / Modal / SLURM), or Tamarind cloud? Read
.by/config.jsonfirst; only ask if the file is missing orcompute.fallback_allowedistrueand the user has not specified. - 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 fromreferences/preset-comparison.md. - Hotspots / epitope — Already known (from
by-researchorby-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×. - 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.mdfor the full list. - 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 inreferences/quality-thresholds.md. - 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:
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 oflabel_seq_idintegers 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.
- Read
.by/config.json— Pullcompute.default_provider,compute.fallback_allowed,compute.providers_priority, and the local engine paths. If the file is missing, prompt forby-sessionfirst. - Load upstream artifacts —
campaigns/{target}/.../research/design_recommendation.json(fromby-research) andcampaigns/{target}/.../research/recommended_hotspots.json(fromby-epitope-analysis). If present, modality and scaffolds are already chosen. - Resolve the routing decision — Run
scripts/route_intent.pywith the merged inputs:
Writespython3 scripts/route_intent.py \ --intent-json /path/to/intent.json \ --config-json /path/to/.by/config.json \ --out-dir campaigns/{target}/.../routing/routing_decision.json. Verification:✓ Routing decision written: routing/routing_decision.json (engine=boltzgen, protocol=nanobody-anything). - Forecast pass rate and design count — Before launching compute, estimate budget:
Writespython3 scripts/estimate_design_space.py \ --modality VHH \ --tier Standard \ --num-scaffolds 2 \ --out-dir campaigns/{target}/.../routing/pass_rate_forecast.json. Verification:✓ Forecast written: routing/pass_rate_forecast.json (expected_passing=1500, wall_hours=2.5). - Hand off to the engine skill — The engine skill (
protenix,pxdesign, orboltzgen) readsrouting_decision.json+handoff_package.jsonand produces the actual designs. This skill does NOT invoke the engine directly. - After screening, compute accept-or-rerun — Once
by-screeningwrites the per-round summary, run:
Writespython3 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/accept_or_rerun.jsonwith verdict ∈ {ACCEPT,RERUN,SWITCH_TOOL,ESCALATE}.
Discipline:
- ✅ Always write
routing_decision.jsonbefore any compute is submitted - ✅ Always re-read
.by/config.jsonat the start — provider can change between sessions - ✅ Always pass the resolved
compute_targetto 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-manageruses 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:
- Fix and Retry (90%) — Almost always a missing input file or wrong path. Re-check the
--config-jsonand--intent-jsonpaths. Confirm.by/config.jsonexists by runningby-session. - Modify Script (5%) — If the engine catalog changes (new protocol, new preset), edit the lookup tables at the top of
scripts/route_intent.pyandreferences/tool-selection-matrix.mdtogether. Keep CLI signatures stable. - 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 inrationale. - Write from Scratch (1%) — Only if the inputs cannot be reconciled with the existing schema (rare). Document why in
routing/notes.mdand 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
- 🚨 CRITICAL: Always read
.by/config.jsonfirst. The compute provider is the user's choice, not yours. - 🚨 CRITICAL: Never silently default a modality. Ask Q1 if the user said "binder" without qualifier.
- ✅ REQUIRED: Write
routing_decision.jsonbefore any compute is submitted. It is the audit trail. - ✅ REQUIRED: Pass
compute_targetexplicitly to the engine skill. Do not letboltzgen/pxdesign/protenixguess from environment. - ✅ Run Preview before Production for any novel target. Cheaper to fail at 500 designs than 20,000.
- ✅ Validate target fold with Protenix before any design run on a target with no experimental structure.
- ✅ Use
label_seq_id(1-indexed, sequential, per-chain) for hotspot residues. Convert fromauth_seq_idif user provides PDB numbering. - ✅ Prefer
localcompute when available — fastest, free, and the user already paid for the hardware. - ✨ Optional: Run a hypothesis-debate (
by-hypothesis-debate) when multiple modalities are viable. A few minutes of reasoning saves hours of compute. - ❌ Do NOT skip the pass-rate forecast even on "obvious" campaigns — it is the budget gate.
- ❌ Do NOT bypass
by-campaign-managerfor the actual campaign plan. This skill makes the routing decision;by-campaign-managerowns the plan and state machine. - ❌ Do NOT improvise new presets / protocols / scaffolds. If the catalog needs an addition, update
references/tool-selection-matrix.mdandscripts/route_intent.pytogether.
Suggested Next Steps
After this skill produces routing_decision.json and handoff_package.json, chain into:
by-campaign-manager— write the canonicalcampaign_plan.mdfrom the routing decision and the pass-rate forecast. Required before any compute is committed; manages state machine + budget + checkpoints.- 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→ readsummary.csv.boltzgen— for antibody / nanobody design (or de novo fallback). Write entities YAML →boltzgen run→ readfinal_designs_metrics_*.csv.
by-deploy-compute(if compute target ishpc) — packages the engine container, syncs target data, dispatches the job. Handles RunPod / Modal / SLURM.by-screening— runs the full screening battery (ipSAE, ipTM, pLDDT, RMSD, liabilities, developability) on the design output. Writesscreening_summary.json.by-scoring— applies canonical formulas (composite, multi-seed aggregation, asymmetry checks) on top of screening output.- Back to
by-design-workflow(this skill) inaccept-or-rerunmode — after screening, compute the verdict (ACCEPT/RERUN/SWITCH_TOOL/ESCALATE). by-failure-diagnosis(conditional) — invoked when the verdict isRERUNorSWITCH_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.jsonexists with compute provider.by-research— producesdesign_recommendation.json(modality, scaffolds, tier).by-epitope-analysis— producesrecommended_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— writescampaign_plan.mdfrom routing decision + forecast.protenix,pxdesign,boltzgen— the three engine wrappers that actually run the design.by-deploy-compute— HPC dispatch forhpccompute 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— full modality × tool × preset × hotspot × pass rate × compute matrix with per-cell rationale.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— acceptance criteria by modality (ipSAE / ipTM / pLDDT / CA-RMSD); when to ACCEPT, RERUN, SWITCH_TOOL, ESCALATE.
Scripts:
scripts/route_intent.py— CLI: input intent JSON (target, modality, budget, compute pref) → outputrouting_decision.json+handoff_package.json; also handlesaccept-or-rerunmode after screening.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— canonical terminology, skill linkage map, end-to-end workflow.templates/CLAUDE.md— BY agent identity, compute provider selection, campaign workflow overview.by-research/SKILL.md— produces upstreamdesign_recommendation.json.by-campaign-manager/SKILL.md— consumes downstreamrouting_decision.json.by-deploy-compute/SKILL.md— HPC dispatch details (do not re-document here).by-scoring/SKILL.md— canonical ipSAE / ipTM / composite formulas.by-screening/SKILL.md— full screening battery + PASS / FAIL gates.
External documentation:
- BoltzGen: project README in the local install (see
compute.local.boltzgen.pathin.by/config.json). - PXDesign: project README in the local install (see
compute.local.pxdesign.path). - Protenix: https://github.com/bytedance/Protenix
Decide Fit First
Design Intent
How To Use It
Boundaries And Review