af3-msa-search

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