protein-sequence-msa

Prerequisites

1. uv: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH.

2. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in this skill directory then (1) prominently notify the user to check the terms at https://www.ebi.ac.uk/jdispatcher/msa/clustalo and https://www.ebi.ac.uk/about/terms-of-use/, then (2) create the file recording the notification text and timestamp.

3. .env file: Make sure the .env file exists in your home directory. Create one if it does not exist.

4. USER_EMAIL (optional but recommended): Recommended by the EBI for Clustal Omega job tracking, but the skill works without it. If the variable is missing from .env, do NOT ask the user to paste it into the chat (this would leak the value into the agent's context). Instead, give the user this command — substituting ENV_FILE with the resolved literal path to the .env file:

   printf "Enter contact email: " && read email && echo "USER_EMAIL=$email" >> "ENV_FILE" && echo "Saved."
   

   The scripts load credentials automatically via dotenv. NEVER read, print, or inspect the .env file or its variables (e.g. no cat, grep, echo, printenv, or os.environ.get on keys). Credentials must stay out of the agent's context.

Core Rules

• Use the Wrapper: ALWAYS execute the alignment using scripts/msa_align.py rather than writing your own curl or custom Python requests. The script automatically enforces the required rate limit to respect EBI's Terms of Use.
• Notification: If this skill is used, ensure this is mentioned in the output.

• Always state the method: Every report must clearly state that the alignment was performed using EBI Clustal Omega.

• No Hallucinations: Do NOT invent alignments or conservation metrics. Report only what is present in the alignment file.

Goal

Take a file containing multiple protein sequences in FASTA format, perform multiple sequence alignment using the EBI Clustal Omega API, save the resulting alignment locally for future programmatic analysis, and interpret the results towards addressing the user's specific research objective (e.g., assessing similarity, identifying conserved domains, or analyzing key residues).

Instructions

1. Prepare Input File: The input must be a plain text file containing two or more protein sequences in FASTA format. Each sequence header must start with a > symbol. Example:

   >Sequence_1_Name
   MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQ
   QRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG
   >Sequence_2_Name
   MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQ
   QRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG
   

2. Execute Alignment: Run the alignment script:

   uv run scripts/msa_align.py <INPUT_FASTA> -o <OUTPUT_FILE>
   

   Always specify the output file with -o or --output.

3. Interpret and Report Results: Analyze the Clustal Omega alignment by selecting metrics and mapping strategies aligned with the research objective. Note that while Clustal Omega produces a Global Alignment, pairwise metrics can be extracted to evaluate specific relationships within the set:

   • Identity Metric Options: The choice of denominator determines how insertions/deletions (gaps) affect the final percentage. Select the most appropriate calculation based on the biological context:
     • Pairwise - Sequence Coverage: (Identical Residue Matches) / (Length of Shorter Sequence). Use when determining if a specific domain or fragment is fully preserved within a larger protein. This ignores gaps in the longer sequence, focusing purely on the "content" of the shorter one.
     • Pairwise - Global Identity: (Identical Residue Matches) / (Total Alignment Columns). Use when comparing full-length sequences of similar expected length. This is the most conservative metric; it penalizes for all gaps (indels) introduced by any sequence in the MSA.
     • Pairwise - Overlap Identity: (Identical Residue Matches) / (Total Alignment Columns - Terminal Gaps). Use when comparing a fragment to a full-length protein or when sequences have long unaligned "tails." This focuses on similarity only where the sequences physically overlap.
     • Multisequence - Conservation Index: (Fully Conserved Columns) / (Total Alignment Columns). Use for quantifying the percentage of residues that are 100% identical across the entire alignment set. This identifies the core evolutionary signature of the protein family.
   • Feature Mapping: Leverage known biological data from specific sequences to ground the analysis:
     • Knowledge Gathering: Identify relevant known sites or regions (e.g., catalytic residues, binding motifs) from your input or via external tools.
     • Coordinate Projection: Map these features onto the corresponding Column Indices of the alignment.
     • Targeted Discussion: Use these columns to drive the assessment:
       • Local Conservation: Analyze if the known functional residues are invariant across the set.
       • Region-Specific Metrics: Calculate identity/similarity specifically within the mapped functional regions rather than the whole sequence.
       • Goal Contribution: Discuss how this data contributes to your goal, e.g. using conservation to corroborate a prediction or divergence to reject a functional hypothesis.

References

• Multiple Sequence Alignment: https://www.ebi.ac.uk/jdispatcher/msa/clustalo