Skip to content
Get packs

Guide · Agent skill

How to use the AlphaGenome Variant Effects agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The alphagenome skill gives an AI agent the knowledge and scripts to look up precomputed AlphaGenome Atlas scores for single-letter DNA changes (SNVs) in the human GRCh38 genome, and to run the AlphaGenome model on variants the Atlas does not cover. This guide is for researchers and students who want to prioritise non-coding or regulatory variants from a VCF, credible set or region. By the end you will know how to install the skill, what it needs, how to phrase a request so the agent uses it, and what its outputs mean.

AlphaGenome Variant EffectsK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip. Download the alphagenome ZIP from the directory page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder. Confirm SKILL.md is at the top of the alphagenome folder.
  2. 2Install alphagenome. Run uv pip install alphagenome in an environment with Python 3.10 or later, using version 0.9.0 or later.
  3. 3Set your API key. Obtain a free non-commercial key from deepmind.google.com/science/alphagenome and export it as ALPHAGENOME_API_KEY.
  4. 4Check the connection. Run python atlas_query.py scorers from the scripts folder to confirm the key and network access work.
  5. 5Ask in plain language. Describe the variants, the GRCh38 build and what you want to know, such as ranking, mechanism or a portal link.
  6. 6Read the attributions. Check top_feature before trusting avi_phred, and use track scores to resolve regulatory mechanisms.

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file with instructions, plus optional reference files and scripts that an AI agent can read and run when a request matches the skill's description. This one is named alphagenome.

The skill covers two routes. The first is the AlphaGenome Atlas: precomputed scores for every possible SNV in GRCh38, about 9 billion variants, each with an AVI score, a genome-wide percentile, and 18 attributions explaining what drives the score. The second is the AlphaGenome model itself, which the agent can run on demand for variant scoring, in silico mutagenesis and REF-versus-ALT track prediction in human and mouse.

The skill is for research use only. It is not a clinical tool.

  • Atlas lookup: AVI, Phred, percentile and attributions for hg38 SNVs
  • On-demand model scoring for indels, mouse variants, custom windows and other cases the Atlas does not cover
  • Track-level scores for RNA-seq, DNase, ATAC, ChIP-TF, ChIP-histone, CAGE, PRO-cap, splicing, polyadenylation and contact maps
  • Atlas website deep links for each variant

Install the skill from the ZIP

Download the ZIP for the alphagenome skill from the directory page, then unzip it. You can install it in one of two places. For a personal install available in every project, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Check that the folder contains SKILL.md at its top level after unzipping.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

  • Personal: ~/.claude/skills/alphagenome/
  • Project: <your-project>/.claude/skills/alphagenome/
  • Claude apps: Settings → Capabilities → Skills

Set up Python, the alphagenome package and your API key

The skill needs Python 3.10 or later and the alphagenome package, version 0.9.0 or later. The source installs it with uv, and that is the command shown here. You also need a free non-commercial AlphaGenome API key, available from deepmind.google.com/science/alphagenome, set as the environment variable ALPHAGENOME_API_KEY. The skill also accepts ALPHA_GENOME_API_KEY as an alternative spelling.

Keep the key out of command lines and out of any file you commit. The scripts read it only from the environment. The first check is a single call that confirms both your key and network access work.

uv pip install alphagenome export ALPHAGENOME_API_KEY="..." cd skills/alphagenome/scripts python atlas_query.py scorers

Trigger the skill with natural requests

You do not need to name scripts. The skill loads when your request mentions AlphaGenome, AlphaGenome Atlas, AVI, AlphaGenome Variant Impact, DeepMind variant effect prediction, or asks to prioritise or interpret non-coding, regulatory, splicing, enhancer, promoter or chromatin-accessibility effects of SNVs from a VCF, credible set or region.

Name the genome build and the variant format in your request. Coordinates must be GRCh38. If you start from rsIDs or GRCh37 positions, ask the agent to convert them first, because the skill warns that a wrong build gives a plausible but wrong answer.

  • Rank the SNVs in candidates.vcf with AlphaGenome AVI and keep those above Phred 20.
  • What is the AlphaGenome AVI score for chr22:36201698:A>C, and which features drive it?
  • Using the AlphaGenome Atlas, check RNA-seq and DNase tracks for this variant in colon tissue.
  • Build AlphaGenome Atlas links for these three variants.

Understand the output

The Atlas route returns one row per variant. avi_raw is the composite model output, and the 18 attributions sum to it. avi_phred is -10 log10 of the tail probability, so Phred 20 corresponds to the top 1 % and Phred 30 to the top 0.1 %. The top_feature column names the largest absolute attribution. The skill's advice is to rank rather than apply one genome-wide threshold, since pathogenic regulatory variants often sit in lower AVI bins than coding or splice-motif variants.

Read the attribution before the number. A top feature of MERGED_SPLICING or ALPHAMISSENSE points to a splice or coding mechanism. MAX_ABS_DNASE, MAX_ABS_CHIP_TF or MAX_ABS_RNA_SEQ points to a regulatory mechanism you can resolve by track. CACTUS_241_WAY or PHASTCONS_470_WAY on top means conservation drives the score and the molecular mechanism is still unresolved.

  • avi_cdf_quantile: cumulative quantile against all genome-wide SNVs
  • top_feature and top_feature_value: largest absolute SHAP attribution
  • error: per-variant failure, reported without crashing the run
  • atlas_url: deep link to the variant on the portal

Safety notes: scripts and network

This skill runs scripts and uses the network. Its scripts send requests to gdmscience.googleapis.com on port 443. Review the scripts in the scripts folder (_common.py, atlas_query.py, score_variants.py, atlas_link.py) before running them on sensitive data, and confirm you are comfortable with variant coordinates leaving your machine.

API outputs must not be used to train other models, and they are not for diagnostic procedures or medical decisions. Authentication failures may appear as ValueError or PermissionError, depending on the status the service returns.

  • Network: gdmscience.googleapis.com:443 only
  • Key: read from ALPHAGENOME_API_KEY, never written to files by the skill
  • Rule from the source: a high AVI is one line of evidence, not a verdict

Tips for reliable results

Normalise your input before it reaches the skill. Use the chr prefix, write MT as chrM, and use 1-based positions. Give single-nucleotide changes only. For intervals, use 1-based closed coordinates such as chr11:5225727-5226575. The scripts convert these to the SDK's internal format.

Check the REF base against a GRCh38 FASTA file. The scripts reject a returned variant that differs from your request, but they cannot confirm the genome build for you.

  • Use chr-prefixed coordinates; rsIDs are not accepted by the API or the portal
  • Ask for tracks only when you need a mechanism, since the --with-tracks option adds detail to the output
  • Use the model route, not the Atlas, for indels and mouse variants

What people use it for

  • Ranking the non-coding SNVs in a VCF from a variant-calling run by AVI and Phred score
  • Checking which regulatory tracks, such as DNase or RNA-seq in a chosen tissue, drive a variant's score
  • Scanning an hg38 region such as a 1 kb window for high-impact SNVs
  • Generating Atlas website links to share specific variants with collaborators
  • Comparing reference and alternate predicted tracks for a hypothesis about a motif or tissue

Frequently asked questions

Is the AlphaGenome Variant Effects skill free to use?

The skill is MIT licensed. The AlphaGenome API key it needs is free for non-commercial use, obtained from deepmind.google.com/science/alphagenome. Commercial use falls outside that key's terms, so check the terms before relying on it.

What do I need to run the alphagenome skill?

You need Python 3.10 or later, the alphagenome package version 0.9.0 or later, network access to gdmscience.googleapis.com on port 443, and a free non-commercial API key set as ALPHAGENOME_API_KEY.

Why does my AlphaGenome lookup fail for an rsID or GRCh37 position?

The Atlas covers only GRCh38 SNVs and does not accept rsIDs. Convert the variant to GRCh38 coordinates first, using the genomic-coordinates skill or a similar tool, then ask again.

Can the skill score indels or mouse variants?

The Atlas is SNV-only and hg38-only, so indels and mouse variants need the on-demand model route through score_variants.py or Python. The model also supports mouse, as mm10 for model use only.

Is AlphaGenome a clinical or diagnostic tool?

No. The source states that outputs are for research and theoretical modelling only, and must not be used for diagnostic procedures or medical decisions. A high AVI is one line of evidence, not a verdict.

How does AlphaGenome compare with other variant tools?

The source does not compare AlphaGenome with other variant tools. It does point to other skills for different needs: folklore-variant-evidence and database-lookup for ClinVar and ACMG framing, and genomic-intelligence for keyless promoter and enhancer predictions.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a bioinformatics researcher, student or pipeline developer who needs predicted regulatory and splicing effects for GRCh38 SNVs and can get a free non-commercial DeepMind API key. Pick something else if you need clinical or diagnostic decisions, a keyless tool, or support for indels, rsIDs or GRCh37 without first converting them.

Download the skill

Find exactly what
you're looking for