protein-sequence-similarity-search

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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/sss/ncbiblast and
    https://colabfold.com, 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
    BLAST 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.

## Goal

Take a user-provided amino acid sequence (or a path to a `.fasta` file), search
for sequence homologues using the fastest available method, generate a
Markdown-formatted table of the top hits, interpret key alignment metrics,
summarize the inferred protein functions, and save results locally for future
programmatic analysis.

## Core Rules

-   **Strict Validation**: For BLAST, only use database codes listed in the
    table below.
-   **No Hallucinations**: If a script throws an error or returns no hits,
    inform the user clearly. Do NOT invent sequence homologues.
-   **Do Not Parse Output Files**: Do not parse the JSON, a3m, or any other raw
    output files. Rely on the generated `.md` file for your summary. The JSON
    and other outputs are for subsequent tool use only.
-   **Always State the Method**: Every report must clearly state whether the
    search used the quick MMseqs2 (ColabFold API) or the slower EBI BLAST
    method.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output. Explicitly state that the corresponding program (MMSEQS2 or EBI
    BLAST) and Sequence Databases were used.

## Search Method Selection

Choose the search method based on the user's request:

If the **user says "quick search" or "fast search"**, **no specific method
requested / general homologue search**, of if you are unsure: Run MMseqs2 (fast,
default) using `mmseqs2_search.py`

If **MMseqs2 fails (exit code 2: RATELIMIT or API error)** or **User explicitly
requests "BLAST"** or **a specific BLAST database** (e.g. `uniprotkb_swissprot`,
`pdb`, `uniprotkb_human`): Run BLAST using `uniprot_blast.py`

## Instructions

1.  Identify the query from the user. It can be a raw sequence string (e.g.,
    "MKVLY...") or a path to a local file (e.g., "./data/sequence.fasta").

2.  **Determine the search method** using the list above.

### Path A: MMseqs2 Search (Default)

1.  **Generate File Names:** Generate descriptive output file names based on the
    input (e.g., `proteinA_mmseqs2.json` and `proteinA_mmseqs2.md`).
2.  Execute the MMseqs2 script:

    *   **Default:**

    ```
    uv run scripts/mmseqs2_search.py <SEQUENCE_OR_FILE> -o <generated-filename.md> -j <generated-filename.json>
    ```

    *   **With mgnify:**

    ```
    uv run scripts/mmseqs2_search.py <SEQUENCE_OR_FILE> -o <generated-filename.md> -j <generated-filename.json> --include-mgnify
    ```

3.  The script will query the ColabFold MMseqs2 API and poll for completion.
    This is typically fast (under 2 minutes).

4.  **If the script exits with code 2** (API failure, rate limit), automatically
    fall back to BLAST (Path B below). Inform the user: "MMseqs2 search failed,
    falling back to BLAST."

5.  **Read the Results:** Open and read the generated `.md` file.

### Path B: BLAST Search (Explicit or Fallback)

1.  **Database Selection & Validation:** Determine the most appropriate
    database(s) based on the user's prompt.
    *   Consult the **Available BLAST Databases** table below.
    *   If the user specifies a taxonomic group (e.g., "Find homologues in
        microbes"), select the corresponding `Database Code` (e.g.,
        `uniprotkb_bacteria`).
    *   If the user explicitly requests curated hits, use `uniprotkb_swissprot`.
    *   If no specific database is requested, do not specify `--databases`.
    *   **Validation:** Ensure the database code exactly matches an entry in the
        table. If the user requests a database not on the list, **do not
        proceed** and provide the allowed list.
2.  **Generate File Names:** (e.g., `proteinA_ebi_blast.json` and
    `proteinA_ebi_blast.md`).
3.  This API requires the user email address to be set in the USER_EMAIL
    environment variable for inclusion in request header.
4.  Execute the BLAST script:

    *   **Default (uniprotkb):**

    ```

From MarceloClaro/OpenCode_Ecosystem, MIT.

More from MarceloClaro/OpenCode_Ecosystem