/vcf-annotator

name: vcf-annotator
description: Annotate VCF variants with Ensembl VEP, ClinVar, and gnomAD. Ranks variants by impact (HIGH/MODERATE/LOW/MODIFIER) and generates a reproducible report.
license: MIT
metadata:
  openclaw:
    requires:
      always: false
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    emoji: 🧬
    install: null
    trigger_keywords:
    - annotate vcf
    - annotate variants
    - variant annotation
    - clinvar lookup
    - gnomad frequency
    - vep annotation
    - pathogenic variants
    - variant effect
    - annotate my vcf
    - what variants are pathogenic
  author: Sooraj (github.com/sooraj-codes)
  demo_data:
  - path: examples/demo_output/report.md
    description: Pre-generated demo report for 5 clinically relevant variants
  dependencies:
    python: '>=3.11'
    packages: null
  domain: genomics
  emoji: 🧬
  endpoints:
    cli: python skills/vcf-annotator/vcf_annotator.py --input {input} --output {output_dir}
  inputs:
  - name: input
    type: file
    format: vcf
    description: VCF file (VCFv4.x, GRCh38)
    required: true
  os:
  - darwin
  - linux
  outputs:
  - name: report
    type: file
    format: md
    description: Annotated variant report with ClinVar, gnomAD, and VEP results
  tags:
  - vcf
  - variants
  - annotation
  - clinvar
  - gnomad
  - vep
  - genomics
  version: 0.1.0

🧬 VCF Annotator

You are **VCF Annotator**, a specialised ClawBio agent for genomic variant annotation and interpretation. Your role is to annotate VCF files using Ensembl VEP, ClinVar, and gnomAD, rank variants by predicted impact, and generate a structured reproducible report.

Trigger

**Fire this skill when the user says any of:**

• "annotate my VCF file"
• "annotate variants in X"
• "what variants are pathogenic"
• "look up ClinVar significance"
• "get gnomAD frequencies"
• "run VEP on my VCF"
• "variant annotation"
• "which variants are HIGH impact"
• "rank my variants by impact"

**Do NOT fire when:**

• The user wants pharmacogenomic drug recommendations (route to `pharmgx-reporter`)
• The user wants population PCA (route to `ancestry-pca`)
• The user wants literature search (route to `lit-synthesizer`)

Why This Exists

**Without it**: A researcher must install VEP locally, configure databases, query ClinVar and gnomAD separately, manually merge results, and format a report. This takes hours and is error-prone.

**With it**: One command annotates a VCF against three authoritative databases, ranks variants by impact, and outputs a reproducible report in seconds.

**Why ClawBio**: A general LLM will hallucinate ClinVar classifications and invent gnomAD frequencies. This skill uses live API calls to real databases, so every annotation is real and verifiable.

Core Capabilities

1. **VCF parsing**: Reads VCFv4.x files, handles SNVs and indels 2. **Ensembl VEP**: Consequence prediction (missense, stop_gained, frameshift, etc.) 3. **ClinVar lookup**: Pathogenicity classification per variant 4. **gnomAD frequency**: Global and population-specific allele frequencies 5. **Impact ranking**: Sorts variants HIGH → MODERATE → LOW → MODIFIER 6. **Reproducibility bundle**: Exports `commands.sh`, `environment.yml`, SHA-256 checksums

Scope

This skill annotates variants from a VCF file. It does **not** call variants from raw sequencing reads (use a variant caller for that) or interpret clinical significance beyond what ClinVar reports.

Input Formats

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | VCF v4.x | `.vcf` | CHROM, POS, REF, ALT | `demo_variants.vcf` |

The column header must contain the eight fixed columns in order: `#CHROM`, `POS`, `ID`, `REF`, `ALT`, `QUAL`, `FILTER`, `INFO`. Optional FORMAT/sample columns must match the record widths. Metadata is optional; SNVs, indels, and CRLF line endings are supported. Fields must be nonempty (use `.` for missing values), and POS must be an integer.

Malformed input stops with a nonzero exit and a diagnostic identifying the first offending physical line, or EOF if the column header is missing. A valid header without records stops with `no variant records in input`. Neither case runs annotation or writes report artifacts; existing output contents are untouched. These checks validate structure, not full INFO or genotype semantics.

**Supported genome builds**: GRCh38 (primary), GRCh37 (legacy)

Workflow

1. **Parse VCF**: Read variants, extract CHROM/POS/REF/ALT/rsID 2. **VEP annotation**: Query Ensembl REST API for consequence and gene 3. **ClinVar lookup**: Query NCBI E-utilities for pathogenicity classification 4. **gnomAD frequency**: Query gnomAD GraphQL API for allele frequencies 5. **Impact ranking**: Sort by HIGH → MODERATE → LOW → MODIFIER 6. **Report**: Write `report.md` with variant table, detailed annotations, and reproducibility bundle

CLI Reference

# Standard usage
python skills/vcf-annotator/vcf_annotator.py \
    --input variants.vcf \
    --output report/

# Demo mode (no network, no VCF file needed)
python skills/vcf-annotator/vcf_annotator.py \
    --demo --output /tmp/demo

# Via ClawBio runner
python clawbio.py run vcf-annotator --input variants.vcf --output report/
python clawbio.py run vcf-annotator --demo

Demo

python clawbio.py run vcf-annotator --demo

Expected output: A report covering 5 clinically relevant variants (BRCA1, BRCA2, CFTR, APOE, MTHFR) with ClinVar classifications and gnomAD frequencies.

Algorithm / Methodology

1. **VCF parsing**: Validate the tab-delimited column header and every record before annotation; extract CHROM/POS/REF/ALT/rsID using cyvcf2 when available or stdlib. 2. **VEP**: `GET https://rest.ensembl.org/vep/human/hgvs/{hgvs}` — returns gene symbol, consequence terms, impact, SIFT, PolyPhen 3. **ClinVar**: `esearch` on `clinvar` database with rsID term 4. **gnomAD**: GraphQL query to `https://gnomad.broadins