/dbsnp_database

name: dbsnp-database
description: >
  Use when you want to look up, map, and search for short genetic variants
  (SNPs, indels) in NCBI's dbSNP database. Resolves between rsIDs, genomic
  coordinates in VCF format, and HGVS strings. For an rsID, returns variant
  type, gene associations, clinical significance, allele frequencies, and
  genomic coordinates (GRCh38).

dbSNP Database Integration

Prerequisites

1. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure `uv` is installed and on PATH. 2. **User Notification**: If .licenses/dbsnp_database_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://www.ncbi.nlm.nih.gov/snp/, 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. You can register for a key for free at https://www.ncbi.nlm.nih.gov/account/settings/. You **MUST** use the safe credentials protocol in the `credentials` skill to check for and request this key if this skill looks relevant to the user's request.

Core Rules

• **Use the Wrapper**: ALWAYS execute the provided wrapper script

`scripts/dbsnp_cli.py` to query the database rather than constructing custom HTTP or curl requests. The script automatically handles rate limiting, retries, and JSON parsing.

• **Command Choice**: Do NOT use `search-region` to find the rsID of a

specific variant; use `resolve-variant` instead.

• **Output Size**: Avoid using `--full` on `get-variant` unless specifically

needed, as raw payloads can exceed 1 MB.

• **Shell Safety**: Always wrap HGVS strings in single quotes to prevent shell

expansion errors.

• **Notification**: If this skill is used, ensure this is mentioned in the

output.

When to Use

**Use this skill when you need to:**

• Map a genomic variant to its canonical rsID (from VCF coordinates or HGVS

notation).

• Retrieve summary data for an rsID: variant type, gene associations, clinical

significance, and population allele frequencies.

• Convert an rsID back to genomic coordinates on a specific assembly.
• Find all known variants within a chromosomal region.

**Do NOT use when you need to:**

• Obtain clinical pathogenicity classifications with submitter rationales (use

**clinvar-database**).

• Get precise population-level allele frequencies stratified by ancestry (use

**gnomad-database**).

• Predict the functional effect of a novel mutation (use

**alphagenome-single-variant-analysis**).

• View 3D protein structures affected by a variant (use

**alphafold-database-fetch-and-analyze / pdb-database**).

Command Selection Guide

**Pick the right command on the first try.** Match the user's input to the correct subcommand below — one command call is almost always sufficient.

• User gives you…: Run this command
• An rsID (e.g. `rs7412`, `rs268`): `get-variant`
• Genomic coordinates: chrom pos ref alt (e.g. `8 19962213 C T`):

`resolve-variant`

• An HGVS string (e.g. `NC_000008.11:g.19962213del`): `resolve-hgvs`
• An rsID and they want coordinates back: `resolve-rsid`
• A chromosomal region (chrom start end): `search-region`

> [!CAUTION] **Do NOT use `search-region` to find the rsID of a specific > variant.** If the user provides a chromosome, position, reference allele, and > alternate allele (four values), use `resolve-variant` — it is a direct, > single-API-call lookup. `search-region` is only for surveying all variants > within a positional range and returns hundreds/thousands of results.

Quick Start

# Look up variant rs7412: type, gene, clinical significance, MAF
uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json

# Find the rsID for a variant at chr8:19962213 C>T
uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

All subcommands write JSON to disk. Always save output in the `/tmp/` directory. The `--output` flag is required.

Commands

1. `get-variant` — Fetch Variant Record

Retrieve the RefSNP record for one rsID. By default the output is abbreviated to the most useful fields. Both `rs268` and `268` are accepted.

uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json

*Arguments:*

• `rsid` (positional, required): The RefSNP identifier.
• `--assembly`: RefSeq assembly accession (default: `GCF_000001405.40` =

GRCh38).

• `--full`: Return the complete raw JSON payload — see warning below.
• `--output`: Output file path (default: `/tmp/dbsnp_output.json`).

*Abbreviated output fields:*

• `refsnp_id`: Numeric rsID
• `variant_type`: e.g. `snv`, `ins`, `del`, `delins`
• `genes`: Sorted list of gene symbols (locus names)
• `clinical_significances`: List of clinical significance labels
• `minor_allele_frequencies`: Study name, allele count, total count
• `placements`: Genomic placements for the requested assembly

> [!WARNING] **About `--full`:** The raw RefSNP payload is typically 50–500 KB > and can exceed 1 MB for clinically significant variants with many submissions. > Only use `--full` when you specifically need data absent from the abbreviated > output — for example: > > - The complete HGVS nomenclature across every transcript and protein > isoform. > - Full submission history with individual submitter details and timestamps. > - Population-level allele frequency breakdowns by sub-population within a > study (e.g. per-population gnomAD counts). > - Th