---

name: protein-mpnn description: "Use ProteinMPNN to design protein sequences from backbones, prepare constraint JSONL inputs, interpret scores/probability outputs, retrain models, and use custom checkpoints in a local ProteinMPNN checkout." disable-model-invocation: true metadata: disco-role: operating license: MIT

ProteinMPNN

Use this skill when a user is working in or around a ProteinMPNN checkout and needs help with sequence design, scoring, constraint preparation, output interpretation, retraining, or custom checkpoints.

What This Skill Covers

• Running protein_mpnn_run.py for single-PDB and parsed-JSONL design workflows.
• Preparing helper JSONL inputs for designed chains, fixed positions, tied positions, bias, omit masks, and PSSM-guided design.
• Choosing vanilla, soluble, CA-only, or custom checkpoint weights.
• Interpreting generated FASTA headers, score/probability NPZ files, and output folders.
• Validating training data layout, adapting training commands, and routing custom checkpoints back into inference.

Minimum Runtime Assumptions

ProteinMPNN is a script-style repository, not a packaged library. Future agents should assume the user has a ProteinMPNN checkout containing protein_mpnn_run.py, protein_mpnn_utils.py, helper_scripts/, training/, and any model weights they intend to use. The Python environment needs at least PyTorch and NumPy for inference; training and CIF preparation may need additional scientific dependencies.

Do not copy model checkpoints into this skill. Point ProteinMPNN commands at the user's own checkout weights or training outputs.

Route By Task

• Run design, scoring, or probability output: use sub-skills/inference-design/ for protein_mpnn_run.py commands, model-family choices, direct-PDB versus JSONL mode, score-only mode, probability flags, output interpretation, and runtime troubleshooting.
• Prepare constraints or JSONL inputs: use sub-skills/constraint-inputs/ for helper_scripts/ commands, parsed-PDB JSONL, chain assignment, fixed/design-only positions, tied positions, homooligomers, amino-acid bias, omit masks, PSSM dictionaries, and schema validation.
• Train or use custom checkpoints: use sub-skills/training-custom-models/ for training data layout, debug training, SLURM adaptation, checkpoint naming, resume behavior, and using --path_to_model_weights with inference.

Common First Questions

1. Is the user starting from one PDB file or a folder/batch of PDBs?
2. Are constraints needed before inference, such as fixed chains, tied residues, PSSM, or amino-acid bias?
3. Is the desired task sequence generation, score-only evaluation, conditional/unconditional probabilities, or training?
4. Which model family is intended: vanilla full-backbone, soluble full-backbone, CA-only, or custom checkpoint?
5. Is the run expected to be a safe dry run, CPU-compatible smoke check, or a full GPU/HPC job?

Safe Starter Checks

Use these checks before a full design or training run:

python - <<'PY'
import numpy, torch
print('numpy', numpy.__version__)
print('torch', torch.__version__, 'cuda', torch.cuda.is_available())
PY
python protein_mpnn_run.py --help

For constraint files, use the validator bundled in sub-skills/constraint-inputs/scripts/validate_constraint_jsonl.py. For custom training data, use sub-skills/training-custom-models/scripts/check_training_layout.py.

Shared References

• references/repo-provenance.md records the repository evidence baseline used to create this skill.
• references/troubleshooting.md covers cross-cutting install/import, checkout layout, dependency, and routing issues.

Boundaries

• This skill is not a substitute for the original model code or model weights.
• Do not run long training jobs, GPU-heavy inference, network downloads, or notebook workflows unless the user explicitly asks and the environment is appropriate.
• Do not depend on source repo examples or docs as runtime skill content; use the bundled references and scripts here, then adapt commands to the user's checkout.