{
  "skill": "alterlab-alphafold",
  "evals": [
    {
      "id": "fold-monomer",
      "prompt": "I have a protein sequence in a FASTA file and no known structure. Predict its 3D structure with AlphaFold and tell me how confident the prediction is.",
      "expected_output": "Invokes alterlab-alphafold: runs colabfold_batch on the FASTA (MMseqs2 MSA), produces ranked PDB/mmCIF models, and interprets pLDDT/pTM (and PAE) so the user knows which regions are reliable. Notes a CUDA GPU is required and heavy runs dispatch via alterlab-remote-compute.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "pLDDT" },
        { "type": "behavior", "value": "Runs ColabFold/AlphaFold2 and interprets confidence metrics rather than just returning coordinates." }
      ]
    },
    {
      "id": "fold-complex-multimer",
      "prompt": "Will these two proteins form a complex? Here are both chains — predict the dimer structure and score the interface.",
      "expected_output": "Invokes alterlab-alphafold in AF2-Multimer mode: folds the two chains as one complex (colon-joined FASTA or multi-record), reports ipTM and the inter-chain PAE to judge the predicted interface, not just intra-chain pLDDT.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "ipTM" }
      ]
    },
    {
      "id": "design-self-consistency",
      "prompt": "I designed a new sequence for a target backbone. Can you refold it with AlphaFold and check whether it actually folds back to the intended shape?",
      "expected_output": "Invokes alterlab-alphafold for a self-consistency check: refolds the designed sequence, compares to the target backbone (TM-score/RMSD), and accepts only if it returns to the target with high pLDDT and low PAE — the acceptance gate in a design→fold→score loop.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Frames the refold as a self-consistency validation against the intended backbone." }
      ]
    },
    {
      "id": "rank-and-confidence",
      "prompt": "AlphaFold gave me five models for my protein. How do I pick the best one and decide if the disordered-looking tail is real or just low confidence?",
      "expected_output": "Invokes alterlab-alphafold: ranks by pLDDT/pTM, selects rank 1, and explains that a low-pLDDT tail (<50) likely indicates disorder/unreliability rather than a confident extended conformation.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "rank" }
      ]
    },
    {
      "id": "near-miss-boltz",
      "prompt": "I want to co-fold my protein together with a small-molecule ligand (I have the SMILES) and estimate the binding affinity.",
      "expected_output": "Should NOT trigger this skill; defers to alterlab-boltz. AlphaFold2/ColabFold folds proteins and protein complexes but does not co-fold arbitrary small-molecule ligands or predict binding affinity — that is alterlab-boltz's (open AlphaFold3-alternative) job.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-boltz" }
      ]
    },
    {
      "id": "near-miss-alphafold-db",
      "prompt": "What's the AlphaFold predicted structure for human P53? I just want to download the existing model, not run anything.",
      "expected_output": "Should NOT trigger this skill; defers to alterlab-alphafold-db, which retrieves precomputed AlphaFold DB predictions by UniProt accession. This skill runs folding; it should not be used to fetch an already-computed model.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-alphafold-db" }
      ]
    }
  ]
}

# ColabFold / AlphaFold2 — Usage Reference

Deeper detail for `alterlab-alphafold`. Verified against ColabFold **1.6.3** (current release
as of 2026-09). Flags do shift between releases — check `colabfold_batch --help` when a
command is rejected.

## Install

ColabFold couples a folding engine (AlphaFold2 via JAX) with the fast MMseqs2 MSA step.
The upstream `sokrypton/ColabFold` install path is a conda env plus pip:

```bash
conda create -n colabfold -c conda-forge -c bioconda python=3.13 mmseqs2
conda activate colabfold

# CUDA 12 GPU (use jax[cuda13]/openmm[cuda13] on Blackwell or newer)
pip install colabfold[alphafold,openmm] jax[cuda12] openmm[cuda12]

# CPU only (slow — fine for testing the pipeline)
pip install colabfold[alphafold,openmm]

# MSA generation only, no structure prediction
pip install colabfold
```

The `openmm` extra is what enables Amber relaxation. For a one-command installer covering
Linux/macOS/WSL2 there is LocalColabFold (`YoshitakaMo/localcolabfold`); a CUDA Docker image
is published as `ghcr.io/sokrypton/colabfold`.

## MSA modes

- **Hosted MMseqs2 API (default)** — `--msa-mode mmseqs2_uniref_env`. Fastest to start; your
  sequence goes to a public shared server, so disclose this for sensitive or unpublished
  sequences. Other choices: `mmseqs2_uniref_env_envpair`, `mmseqs2_uniref`, `single_sequence`.
- **Local database** — run `colabfold_search` against a local ColabFold DB and feed the
  resulting MSA directory to `colabfold_batch`. Needed on air-gapped HPC. Splitting the run
  this way (`--msa-only`, then predict) also keeps the GPU busy only during folding.

## Key flags

| Flag | Purpose |
|------|---------|
| `--num-models N` | how many of the 5 AF2 models to run (default 5) |
| `--num-recycle N` | recycling iterations; more can help hard targets |
| `--model-type alphafold2_multimer_v3` | multimer models for complexes (`auto` picks `alphafold2_ptm` for monomers, `alphafold2_multimer_v3` for complexes) |
| `--templates` | query PDB templates from the MSA server |
| `--amber --num-relax 1 --use-gpu-relax` | Amber-relax the top N ranked models (`--num-relax` defaults to 0, i.e. no relaxation) |
| `--msa-mode` | MSA source (see above) |
| `--msa-only` | fetch and store MSAs without predicting |
| `--rank` | early-stop criterion; `auto` ranks by pLDDT (monomer) or pTM (multimer) |
| `--pair-mode` / `--pair-strategy` | how chains' MSAs are paired for complexes |
| `--use-fast-kernels` | fused kernels, ~2.5x faster with slightly lower memory (`--kernel-backend auto`) |
| `--af3-json` | export the MSAs as an AlphaFold3-compatible input JSON instead of predicting |

## Outputs

Per FASTA record ColabFold writes: ranked structures (`*_rank_00N_*.pdb` or `.cif`, relaxed
versions only if `--num-relax` > 0), a scores JSON with `plddt` and `pae` arrays, and
coverage/pLDDT/PAE plots. Rank 1 is the highest-confidence model.

## Metric interpretation

- **pLDDT** (0–100, per residue): >90 very high, 70–90 confident, 50–70 low, <50 likely
  disordered.
- **pTM**: global fold confidence (0–1); >0.5 means the overall predicted fold is plausibly
  similar to the true structure.
- **ipTM**: interface confidence (0–1) and the load-bearing number for complexes. DeepMind's
  published bands (AlphaFold 3 output documentation): **>0.8** confident high-quality
  interface, **0.6–0.8** gray zone where the prediction may be right or wrong, **<0.6**
  likely a failed prediction. TM-based scores are strict on very short chains, so fall back
  to PAE/pLDDT for small entities.
- **PAE**: N×N expected error (Å) between residue pairs; confident relative domain/chain
  orientation shows as low off-diagonal blocks.

## Design self-consistency

For a design→fold→score loop, refold the designed sequence and accept only if it returns to
the intended backbone with high pLDDT and low PAE (compare via TM-score/RMSD). This is the
validation gate referenced by `alterlab-proteinmpnn`, `alterlab-ligandmpnn`, and
`alterlab-rfdiffusion`.

## GPU dispatch

`colabfold_batch` needs a CUDA GPU. Batch many targets as a SLURM array or a cloud GPU job via
`alterlab-remote-compute` (submit → poll `sacct`/provider status → harvest `out/`).

## AlphaFold 3

ColabFold also ships an AlphaFold3/OpenFold3 notebook, and DeepMind's own
`google-deepmind/alphafold3` provides the AF3 inference pipeline under Apache-2.0 with model
parameters distributed separately under Google's weights terms of use. The hosted
AlphaFold Server (`alphafoldserver.com`) is free for non-commercial use with a limited ligand
set. For an openly licensed local AF3-class model, see `alterlab-boltz` or `alterlab-chai`.