design-thermostable-mutations

Files (24)

• SKILL.md
• README.md · agents/
• claude.yaml · agents/
• openai.yaml · agents/
• config.yaml
• evals.json
• literature-evidence-2022-2026.md · references/
• mutation-design-principles.md · references/
• mutation-design-workflow.md · references/
• report-template.md · references/
• stability-prediction-playbook.md · references/
• troubleshooting.md · references/
• use-case-playbook.md · references/
• consensus_stability_rank.py · scripts/
• design_thermostable_mutations.py · scripts/
• discover_candidate_sites.py · scripts/
• generate_mutation_library.py · scripts/
• run_colabfold_batch.py · scripts/
• run_decision_pipeline.py · scripts/
• run_foldx_batch.py · scripts/
• run_foldx_chunked.py · scripts/
• run_skill_evals.py · scripts/
• structure_residue_mapper.py · scripts/
• validate_skill_bundle.py · scripts/

SKILL.md (first lines)

# Skill: Design Thermostable Mutations

## Use When
Use this skill when users need mutation design or triage for proteins/enzymes and care about both:
- improved thermostability/heat tolerance
- preserved catalytic activity/bioactivity

Typical requests:
- "Which positions should I mutate first?"
- "Design a stability-focused mutation library without breaking active site chemistry"
- "Rank these candidate mutations by stability evidence"
- "Build a decision-grade shortlist for wet-lab validation"
- "Predict the stability impact of a specific variant (e.g., a clinical or engineered substitution)"

## Decision-Grade Guardrails (Default)
These are enforced by default unless explicitly overridden:
1. Bioactivity constraints must be supplied for design decisions:
   - active-site/catalytic/cofactor/disulfide/blocklist positions
2. Functional/protected positions are blocked from routine mutagenesis.
3. Non-conservative substitutions are rejected in conservative mode.
4. User-facing mutation notation is 1-based and WT residue-validated.

## Inputs
- Required:
  - WT sequence (`--sequence` or `--fasta`)
- Required for decision-grade design mode:
  - functional constraints (at least one: active/cofactor/disulfide/blocklist)
- Optional:
  - structure (`.pdb`/`.cif`/`.mmcif`)
  - mutation candidates (`A123V` format)
  - assay context (pH, temperature, ligand/cofactor state)

## Workflow
Choose the smallest workflow that still supports decision-grade confidence.

### Path A: Fast Heuristic Design (single-script)
Use when structure and external predictors are unavailable.

Script:
- `scripts/design_thermostable_mutations.py`

Capabilities:
- strict sequence/mutation validation
- protected-residue enforcement (default)
- conservative-substitution enforcement (default)
- heuristic DDG + local aggregation-risk filtering
- ranked candidate output with rejection reasons

### Path B: Structure-Aware Consensus (recommended)
Use when structure is available and shortlist quality matters.

0. One-command orchestrator (recommended entrypoint):
- `scripts/run_decision_pipeline.py`

1. Discover candidate sites with structural context and functional guardrails:
- `scripts/discover_candidate_sites.py`

2. Generate focused single/multi-site library:
- `scripts/generate_mutation_library.py`

3. Resolve sequence-to-structure numbering safely:
- `scripts/structure_residue_mapper.py`

4. Run structure-based scoring (FoldX wrappers):
- `scripts/run_foldx_batch.py`
- `scripts/run_foldx_chunked.py` (large libraries)

5. Aggregate multiple metrics with direction-aware consensus:
- `scripts/consensus_stability_rank.py`

6. Produce decision-ready report using:
- ranked consensus
- support fraction across tools
- functional risk flags
- assumptions and escalation notes

7. Optional AI-assisted route for structure generation/summary:
- `scripts/run_colabfold_batch.py`

Example:
```bash
python3 scripts/run_decision_pipeline.py \
  --sequence-fasta wt.fasta \
  --structure model.pdb \
  --active-site 57,102,195 \
  --cofactor-sites 64,66 \
  --blocklist-sites 1-5 \
  --run-foldx \
  --run-consensus
```

By default, the pipeline:
- requires functional constraints for decision-grade discovery
- blocks protected sites during library generation
- auto-derives protected sites from active/cofactor/disulfide/blocklist when not explicitly set

## Output Contract
Always include:
1. Baseline stability summary
2. Functional-constraint enforcement status
3. Ranked candidates with rationale
4. Rejection summary (rule-level counts)
5. Functional risk flags (active/cofactor/disulfide/interface/conservation)
6. Confidence and escalation section

For consensus workflows, also include:
- per-tool metric table
- consensus score and support fraction
- metric directionality and normalization choices

## References
- `references/mutation-design-workflow.md`
- `references/mutation-design-principles.md`
- `references/stability-prediction-playbook.md`
- `references/use-case-playbook.md`
- `references/report-template.md`
- `references/troubleshooting.md`
- `references/literature-evidence-2022-2026.md`

From Scientific-Tooling/structured-intelligence, MIT.

More from Scientific-Tooling/structured-intelligence