# Variant Annotation

Annotates VCF variants and normalizes HGVS with public annotators and gnomAD frequencies.

- Repository: https://github.com/maziyarpanahi/openmed (5755 stars)
- Category: Data and ML
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add maziyarpanahi/openmed --skill annotating-variants -g -a claude-code -y`
Codex: `npx skills add maziyarpanahi/openmed --skill annotating-variants -g -a codex -y`
Cursor: `npx skills add maziyarpanahi/openmed --skill annotating-variants -g -a cursor -y`
Gemini CLI: `npx skills add maziyarpanahi/openmed --skill annotating-variants -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add maziyarpanahi/openmed`

## Description

Annotates VCF variants and normalizes HGVS nomenclature with public, license-free annotators (Ensembl VEP REST, VEP/SnpEff/ANNOVAR offline) and links variants to gnomAD population frequencies and the clinical context OpenMed extracts. Use when the user wants to predict variant consequences, map HGVS to genomic coordinates, annotate a VCF, attach allele frequencies, or pair variants with phenotype/oncology context. Trigger keywords: VCF, HGVS, variant annotation, VEP, SnpEff, ANNOVAR, consequence, missense, gnomAD, allele frequency, GRCh38, rsID, transcript. Pairs adjacent to OpenMed: combine annotated variants with Genomics/Oncology entities and phenotype from openmed.analyze_text. Tools used are free; restricted clinical databases are user-supplied.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Annotating variants & normalizing HGVS

Turn raw genomic variants, VCF rows, rsIDs, or **HGVS** strings, into annotated,
consequence-predicted records, and link them to the **clinical context** OpenMed
extracts from text (genes, variants, oncology findings, phenotype). The workhorse
for a quick, no-install annotation is the **Ensembl VEP REST API**; for scale,
run **VEP**, **SnpEff**, or **ANNOVAR** offline.

These annotators are **free and license-permissive**. Restricted clinical
interpretation databases (e.g. licensed HGMD) are **user-supplied**, this skill
sticks to open resources (Ensembl, gnomAD, ClinVar).

## When to use

- You have a VCF / HGVS / rsID and need consequence predictions (missense,
  stop-gain, splice), affected transcripts, and protein change.
- You need to **normalize HGVS** to genomic coordinates (and back) on a known
  build (GRCh38 by default; GRCh37 via the dedicated endpoint).
- You want **gnomAD** population allele frequencies to flag common vs rare.
- You are pairing molecular findings with the phenotype/oncology context that
  OpenMed pulls from notes or literature.

## Quick start (real Ensembl VEP REST call)

Base URL: `https://rest.ensembl.org` (GRCh38). For GRCh37 use
`https://grch37.rest.ensembl.org`. Default species is `human`/`homo_sapiens`.

```python
import requests

REST = "https://rest.ensembl.org"
HEADERS = {"Content-Type": "application/json", "Accept": "application/json"}

def vep_hgvs(hgvs: str) -> list[dict]:
    """Annotate a single HGVS variant (GET)."""
    r = requests.get(f"{REST}/vep/human/hgvs/{hgvs}", headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()

The rest: https://github.com/maziyarpanahi/openmed/blob/HEAD/skills/annotating-variants/SKILL.md