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:
   bash

   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

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:
   bash

   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