| name | af3-msa-search |
| description | Run ColabFold MSA search from a FASTA file and automatically clean resulting A3M files into paired/unpaired outputs for downstream AF3-style pipelines. |
MSA-Search
Generate MSA artifacts from one FASTA file, then clean them:
- per-batch raw
.a3m files under msas/
- cleaned
unpairedMSA/ and pairedMSA/ under processed_msas/
- per-batch logs and resumable
.done markers
Scope
- This skill only does two steps:
- MSA search
- post-search A3M cleanup
Run
Use this single entrypoint:
bash skills/af3-msa-search/scripts/start_production.sh \
--query /abs/path/to/all.fasta
start_production.sh behavior:
- starts one detached outer
tmux session (SSH-safe),
- inherits environment variables from the current shell session,
- runs
launch_and_watch.sh immediately,
launch_and_watch.sh starts run.sh (inner tmux by default),
- keeps running in background tmux until search+cleanup complete,
- writes
${out_root}/.ready_for_next_step when finished.
No next-step handoff hooks are included in this skill.
Long-Running Policy
When using this skill in an interactive chat, do not wait for full completion.
After launching start_production.sh, perform only a minimal health check, then end the turn:
- confirm tmux session exists (
tmux has-session -t <session>)
- confirm pipeline log is being written and reached active run markers (for example
[Split] / [Run] batch_...)
- confirm no immediate errors (
[Error], [Fatal], Traceback) in pipeline.log and logs/
If checks pass, report the session/log paths and stop. Let the job continue in background.
Environment
This skill reads only LOCALCOLABFOLD_* variables from the current shell.
If you store them in .envrc, load/export them before running.
Common variables:
LOCALCOLABFOLD_IMAGE
LOCALCOLABFOLD_DB_DIR
LOCALCOLABFOLD_GPUS
LOCALCOLABFOLD_THREADS
LOCALCOLABFOLD_BATCH_SIZE
LOCALCOLABFOLD_RESUME
LOCALCOLABFOLD_USE_GPU_SERVER
- optional:
LOCALCOLABFOLD_QUERY, LOCALCOLABFOLD_OUT_ROOT, LOCALCOLABFOLD_TMUX_SESSION
Output Contract
Under --out-root:
msas/batch_000001/ : raw MSA files (*.a3m) and .done
processed_msas/batch_000001/unpairedMSA/ : cleaned unpaired outputs
processed_msas/batch_000001/pairedMSA/ : cleaned paired outputs
logs/ : gpuserver logs + per-batch logs
tmp/batches/ : split FASTA chunks
.ready_for_next_step : completion marker after cleanup
If --resume 1, completed batches are skipped.
Quality Control
After completion (offline follow-up):
- confirm no failures in
logs/batch_*.log
- confirm expected batches have
msas/<batch>/.done
- spot-check cleaned outputs exist under
processed_msas/
Failure Handling
- DB prefix/index missing: verify
${db}.dbtype and ${db}.idx/${db}.index
- zero FASTA records: fix FASTA header/sequence formatting
- batch failed with no
.a3m: inspect corresponding logs/batch_*.log
- gpuserver crash: inspect
logs/gpuserver_*.log, retry with --use-gpu-server 0