clinvar-database
Use when needing clinical significance, pathogenicity classifications (e.g., Pathogenic, Benign, VUS), clinical evidence rationales, or finding "hard positive" benchmark controls for human genomic variants.
Install / Use
npx skills add google-deepmind/science-skills --skill clinvar_databaseInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
CommunicationSupported Platforms
Our assessment of clinvar-database
clinvar-database scores 95/100 on our quality scale, 58th of 394 Communication skills we index (top 15%).
Its SKILL.md is 15 KB long, well organised into 33 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.
With 3,137 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so clinvar-database is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
clinvar-database compared with similar skills
All 4 of these similar skills score higher than clinvar-database; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| clinvar-database (this skill)by google-deepmind | 95 | 3.1k | 2mo ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install clinvar-database?
- Run
npx skills add google-deepmind/science-skills --skill clinvar-database. The install tabs above show the steps for each supported agent. - Which AI agents does clinvar-database work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is clinvar-database safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is clinvar-database still maintained?
- The repository was last updated about 2 months ago, so clinvar-database is actively maintained.
Skill content
View source on GitHubname: clinvar-database description: > Use when needing clinical significance, pathogenicity classifications (e.g., Pathogenic, Benign, VUS), clinical evidence rationales, or finding "hard positive" benchmark controls for human genomic variants.
ClinVar Database
Prerequisites
uv: Read theuvskill and follow its Setup instructions to ensureuvis installed and on PATH.- User Notification: If .licenses/clinvar_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/clinvar/, then (2) create the file recording the notification text and timestamp.
.envfile: Make sure the.envfile exists in your home directory. Create one if it does not exist.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 thecredentialsskill to check for and request this key if this skill looks relevant to the user's request.
Overview
ClinVar is the primary consensus record for clinical classifications of human genomic variations. It provides the "clinical ground truth" for pathogenicity labels (Pathogenic, Likely Pathogenic, Benign, VUS) based on assertions from global laboratories.
When to Use
Use when you need to:
- Find the current clinical significance and star rating (review status) for a specific variant.
- Fetch clinician notes, assertion criteria, or rationales for previous clinical laboratory classifications.
- Retrieve the preferred condition name and associated HPO terms for a specific variant.
- Find a list of variant controls (e.g., "Find all Pathogenic variants in the HBB gene within 50bp of a signal").
- Check for conflicting interpretations for a given variant and identify the organizations submitting each classification.
Do NOT use when you need to:
- Find specific allele frequencies in global populations (use gnomAD).
- Describe the normal biological role of a protein and typical inheritance patterns (use OMIM).
- Predict mechanistic effects of novel mutations, like frameshifts or exon skipping (use AlphaGenome).
- Find recommended surveillance schedules for patients with a pathogenic variant (use GeneReviews).
- Generate or view 3D structural models of affected proteins (use PDB / AlphaFold).
Quick Start
ClinVar queries are executed via a robust Python wrapper script to handle strict rate limiting and XML/JSON parsing.
Example: Search for BRCA1 variants
uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json
Core Rules
- Retmax Constraint: The search command defaults to
--retmax 200. For any "List all" or gene-wide request, you MUST explicitly set--retmaxhigher (e.g., 1000) to ensure data completeness. - Use the Wrapper: Prefer the wrapper script for standard queries. It handles rate limiting, retries, and the complex XML parsing for you. If the script's parsed output does not contain the specific fields you need, you may modify the script or query the NCBI E-utilities API directly — but be aware that the raw XML schemas are complex and vary between record types.
- If the rate limit is hit, the script will throw a clear error. You MUST
use the safe credentials protocol in the
credentialsskill to check for and request theNCBI_API_KEYto help the user add it to their.envfile. - Notification: If this skill is used, ensure this is mentioned in the output.
Utility Scripts
1. count — Count Matching Variants
Purpose: Check how many variants match a query without fetching IDs. Use to
decide whether a full search is warranted.
Arguments:
--query: (Required) NCBI Entrez search query string.--output: (Required) Output JSON file path.
Example: uv run scripts/clinvar_api.py count \ --query "TP53[gene] AND \"uncertain significance\"[clinsig]" \ --output count.json Output:
{"total_count": <int>}
2. search — Search Variants
Purpose: Identify variants based on genomic location, gene symbols, or clinical attributes using NCBI Entrez search syntax. The search command automatically paginates through all matching results to ensure complete, deterministic retrieval.
# Fetch ALL matching variants (default behavior)
uv run scripts/clinvar_api.py search \
--query "BRCA1[gene]" --output results.json
# Search by Chromosome and Position Range
uv run scripts/clinvar_api.py search \
--query "11[chr] AND 5225000:5226000[chrpos]" --output results.json
# Combine terms using Entrez syntax
uv run scripts/clinvar_api.py search \
--query "HBB[gene] AND pathogenic[clinsig]" --output results.json
# Cap results at 50
uv run scripts/clinvar_api.py search \
--query "TP53[gene]" --retmax 50 --output results.json
Arguments:
--query: (Required) NCBI Entrez search query string.--retmax: Maximum total number of variant IDs to return. Default is 0, which means "fetch all matching results." Set to a positive integer to cap the result set.--page_size: Number of IDs to fetch per API request (default: 500, max: 10000 per NCBI limits).--output: (Required) Output JSON file path.
Output: A JSON object containing:
total_count— Total number of matching variants in ClinVar.fetched_count— Number of IDs actually retrieved.variant_ids— List of ClinVar Variation ID strings.
3. summary — Get Interpretation Summary
Purpose: Retrieve top-line clinical significance labels, star ratings (review status), and basic phenotype data for rapid variant screening.
# Get summary for one or more Variation IDs
uv run scripts/clinvar_api.py summary \
--variant_ids 12345 67890 --output summary.json
Arguments:
--variant_ids: (Required) One or more ClinVar Variation IDs.--output: (Required) Output JSON file path.
Output: A JSON list of summary objects, each containing:
variant_id,title,clinical_significance,review_status,
last_evaluated,phenotypesgenes— list of{gene_id, symbol, strand}variation_type— e.g., single nucleotide variant, Deletion, Insertionmolecular_consequences— list of strings (e.g., ["missense variant",
"nonsense"])
4. evidence — Get Clinical Evidence
Purpose: Fetch the full clinical record for a single variant, including free-text clinician rationales, assertion methods, and specific submitter notes.
# Get full evidence for a single Variation ID
uv run scripts/clinvar_api.py evidence \
--variant_id 12345 --output evidence.json
Arguments:
--variant_id: (Required) A single ClinVar Variation ID.--output: (Required) Output JSON file path.
Output: A JSON object containing:
variant_idallele_info—{chromosome, position_start, position_stop, reference_allele, alternate_allele, cytogenetic_band, dbsnp_rsid}(GRCh38 preferred)conditions— list of{name, medgen_cui, omim_id, orphanet_id, hpo_terms}functional_consequences— list of{value, sequence_ontology_id}structural_variant_details—{outer_start, inner_start, inner_stop, outer_stop, copy_number}(present only for CNVs, otherwise null)citation_references— list of PubMed IDs cited in the global "Citations" sectionsubmissions— list of per-submitter records, each containing:submitter_name,classification,curator_notes,assertion_criteriadate_last_evaluated— when the submitter last reviewed the classification
Typical Workflows
Count-First Workflow (Recommended)
For large or unknown result sets, use count first to decide whether to
proceed, then search (which auto-paginates and returns total_count /
fetched_count), then summary to screen.
# Step 1: Gauge size (optional — search also returns total_count)
uv run scripts/clinvar_api.py count \
--query "HBB[gene] AND pathogenic[clinsig]" --output count.json
# Step 2: Fetch all variant IDs (auto-paginates)
uv run scripts/clinvar_api.py search \
--query "HBB[gene] AND pathogenic[clinsig]" --output ids.json
# Step 3: Get summaries (extract variant_ids from search output)
uv run scripts/clinvar_api.py summary \
--variant_ids 12345 67890 --output summary.json
Deep Dive: search → evidence
When you need the full clinical picture for a specific variant — including
submitter rationales, PubMed citations, ontology-linked conditions, and allele
coordinates — use evidence.
uv run scripts/clinvar_api.py evidence \
--variant_id 12345 --output evidence.json
Workflow: Robust Variant Discovery (Triangulation)
ClinVar metadata is inconsistent. To fulfill "List all" requests, do not rely on a single filter. Perform the following in a single turn and merge results:
- Search by exact label (e.g.,
"3 prime UTR variant"[molecular_consequence]). - Search by HGVS nomenclature pattern (e.g.,
c.*). - Search by genomic coordinate range (using
[chrpos]).
This "triangulation" ensures structural variants with missing labels are not overlooked.
Verifying Coding vs. Non-Coding Status via HGVS
molecular_consequences alone can be ambiguous (e.g., splice donor variant
appears in both coding and non-coding contexts). Always cross-check the title
field for HGVS patterns:
c.-…— 5' UTR (non-coding)c.*…— 3' UTR (non-coding)c.123+N/c.123-N— intronic (non-coding)p.Trp146Argetc. — protein effect (coding)
A variant with UTR/intronic HGVS and no p. annotation is non-coding, even with
splicing labels. Conversely, any p. annotation indicates a coding effect.
ClinVar Metadata Reference
- 3' UTR
- Search String:
"3 prime UTR variant"[mol_consequence] - HGVS:
c.*
- Search String:
- 5' UTR
- Search String:
"5 prime UTR variant"[mol_consequence] - HGVS:
c.-
- Search String:
- To find "high-confidence" variants or expert-reviewed consensus, use the
review_statusfilter. This is the most efficient way to distinguish between single-laboratory assertions and panel-reviewed ground truth.
When to Use Which Fields
- Quick pathogenicity label — Use
summary→clinical_significance - Gene symbol and strand — Use
summary→genes - Variant type (SNV, del, etc.) — Use
summary→variation_type - Protein-level effect — Use
summary→molecular_consequences - Genomic coordinates (GRCh38) — Use
evidence→allele_info - Linked conditions (ontology) — Use
evidence→conditions - SO functional consequence — Use
evidence→functional_consequences - CNV breakpoints/copy number — Use
evidence→structural_variant_details - PubMed references — Use
evidence→citation_references - Date of last lab review — Use both →
last_evaluated - Clinician rationales — Use
evidence→submissions[].curator_notes
Retrieving Genomic Coordinates (Default HG38/GRCh38)
To get precise genomic coordinates in the format <chrom>:<pos>:<ref>><alt>
(e.g., chr5:70951945:G>A), you must use the evidence command, as these
details are not available in the summary output.
**You MUST always include genomic coordinates in the format
<chrom>:<pos>:<ref>><alt> when listing or presenting variants, even if not
explicitly requested by the user. If coordinates are missing from the summary,
use the evidence command or dbSNP fallback to r
Truncated for display — read the full file on GitHub.
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
