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.ncbi.nlm.nih.gov/ and https://www.ncbi.nlm.nih.gov/home/about/policies/, 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. NCBI_API_KEY

   (optional): Raises the NCBI rate limit from 3 to 10 requests/second. The skill works without it, but a key is recommended if the user plans many queries or encounters a 429 error. The user can obtain one for free by registering at https://www.ncbi.nlm.nih.gov/account/settings/. If the variable is missing from

   .env

   , do NOT ask the user to paste it into the chat (this would leak the key 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 NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "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.

• Use the Wrapper: ALWAYS execute the provided helper scripts to query the database rather than accessing the database directly. The scripts automatically enforce the required rate limit gracefully.
• API Key Support: If the user provides an

  NCBI_API_KEY

  in their environment, the query speed limits are automatically increased significantly.
• Notification: If this skill is used, ensure this is mentioned in the output.

• fetch-protein

  — Direct protein accession lookup (GenPept, RefSeq)

• fetch-nucleotide

  — Direct nucleotide accession lookup

• cds-translate

  — Fetch CDS and translate to protein (3 methods)

• search

  — Free-text search of any NCBI database

• elink

  — Follow cross-database links (PubMed→Protein, etc.)

• gene-protein

  — Search protein by gene name + organism

• locus-protein

  — Search protein by locus tag + organism

• pubmed-proteins

  — Find proteins linked to a PubMed article

• patent-search

  — Extract protein sequences from patents

• organism-length

  — Last-resort search by organism + exact AA length

bash uv run scripts/ncbi_fetch.py patent-search --patent-number US10123456 -o /tmp/patent.json

patent[Properties]

bash uv run scripts/ncbi_fetch.py patent-search --keywords WRR4B Albugo --organism "Arabidopsis thaliana" -o /tmp/patent.json

[!IMPORTANT] Patent convention: In molecular biology patents, SEQ ID NO: 1 is typically the DNA sequence and SEQ ID NO: 2 is the primary protein. Higher SEQ ID NOs are variants or related sequences. Prefer Sequence 2 when selecting the primary protein of interest.

[SLEN]

uv run scripts/ncbi_fetch.py organism-length \
  --organism "Arabidopsis thaliana" --length 1048 --retmax 50 \
  -o /tmp/result.json

[!NOTE] This often returns multiple candidates. Use the JSON output headers to identify the correct protein.

1. Direct accession —

   fetch-protein

   with GenPept/RefSeq accession
2. CDS translation —

   cds-translate

   with nucleotide/CDS accession
3. PubMed-linked —

   pubmed-proteins

   with PMID + gene name
4. Locus lookup —

   locus-protein

   with locus tag + organism
5. Gene + organism —

   gene-protein

   with gene name + organism
6. Patent search —

   patent-search

   with patent number or keywords
7. Organism + length —

   organism-length

   as last resort

• All subcommands return JSON with a

  results

  array
• Each result has

  sequence

  (AA string),

  length

  , and

  header

  /metadata
• When multiple results are returned, select by:
  • Closest match to expected length (

    target_length

    )
  • Header relevance (matching gene name, "disease resistance" keywords)
  • Source priority (RefSeq > GenPept > patent)

• NCBI E-utilities docs: https://www.ncbi.nlm.nih.gov/books/NBK25499/
• Entrez search syntax: https://www.ncbi.nlm.nih.gov/books/NBK49540/
• Database list: protein, nuccore, gene, pubmed, pmc, biosample, etc.
• Common accession formats:

  • XP_

    /

    NP_

    — NCBI RefSeq protein

  • AAA

    to

    AZZ

    + digits — GenPept (translated GenBank)

  • MK

    ,

    MN

    ,

    HQ

    , etc. + digits — GenBank nucleotide

  • ENSG

    ,

    ENST

    ,

    ENSP

    — Ensembl (use

    ensembl-database

    skill instead)

  • Q

    ,

    P

    ,

    O

    + digits — UniProt (use

    uniprot-database

    skill instead)