dbsnp-database

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

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

```bash
# Look up variant rs7412: type