# Zero Shot Mutation Workflow

> Zero-shot mutation engineering with VenusFactory PLMs. Use when the user wants beneficial mutations, directed evolution candidates, or stability/fitness ranking from a FASTA sequence or PDB structure. Do NOT use for ProteinMPNN inverse folding (proteinmpnn_design_workflow), sequence homology search (protein_sequence_similarity_search), or experimental wet-lab protocols alone.

- Skill: `ai4protein/zero-shot-mutation-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ai4protein/zero-shot-mutation-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai4protein/zero-shot-mutation-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: ai4protein (https://skillmd.com/u/ai4protein)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ai4protein/zero-shot-mutation-workflow

---


# Zero-Shot Mutation Workflow

## Overview

Orchestrates VenusFactory mutation tools: sequence-only PLMs (ESM-1v / ESM2 / VenusPLM) or structure-aware PLMs (ESM-IF1 / SaProt / ProtSSN / MIF-ST). Outputs CSV + heatmap paths in the rich JSON envelope — treat scores as **computational hypotheses**, not wet-lab results.

## VenusFactory execution

1. `read_skill` with `skill_id: zero_shot_mutation_workflow` (this file).
2. Call the hub tools below by **exact name** (do not invent Forge/ESM SDK calls).
3. Parse `status`, `file_info.file_path`, and any `data` / heatmap paths.

## Project Tools (VenusFactory2)

| Tool | Args | Returns | When |
|------|------|---------|------|
| **zero_shot_mutation_sequence_prediction** | `sequence` **or** `fasta_file`; `model_name` (default `ESM2-650M`); `backend` (`local`/`pjlab`); optional `out_dir` | status JSON + CSV/heatmap | Only sequence available |
| **zero_shot_mutation_structure_prediction** | `structure_file` (PDB); `model_name` (default `ESM-IF1`); `backend`; optional `out_dir` | status JSON + CSV/heatmap | PDB available (prefer over sequence-only) |
| **read_fasta** | `file_path` | sequence content | Inspect uploaded FASTA |
| **get_seq_from_pdb_chain_a** | `pdb_file` | chain A sequence | Need sequence from structure |
| **render_protein_structure** | `pdb_path`, **`out_dir`**, style options | image under `file_info` | Visualize top mutation sites |

Sequence models: `ESM-1v`, `ESM2-650M`, `ESM-1b`, `VenusPLM`.  
Structure models: `ESM-IF1`, `SaProt`, `ProtSSN`, `MIF-ST` (and related names exposed by the tool).

## Workflow

### A. Sequence-only path

1. Ensure FASTA via `read_fasta` or pass `sequence` directly.
2. Call `zero_shot_mutation_sequence_prediction` with an explicit `out_dir` under the session workspace.
3. Summarize top-ranked substitutions; warn that scores are model-dependent.

### B. Structure path (preferred when PDB exists)

1. Validate PDB path (may come from `predict_structure_esmfold` or `download_alphafold_structure_by_uniprot_id`).
2. Call `zero_shot_mutation_structure_prediction`.
3. Optional: `render_protein_structure` highlighting candidate sites; optional cross-check with `predict_residue_function` (Activity/Binding/Conserved Site).

## When NOT to use

- Designing a new sequence for a fixed backbone → `proteinmpnn_design_workflow`
- Need experimental structure QA / AlphaFold confidence → `alphafold_database` / `protein_structure_pipeline`
- Homolog discovery → `protein_sequence_similarity_search` or `foldseek_structural_similarity`

## Common mistakes

- Calling non-existent ESM Forge APIs instead of hub tools.
- Using structure models without a real PDB path.
- Presenting zero-shot ranks as measured ΔΔG / activity without caveats.
- Omitting `out_dir` when the session needs a stable artifact path.