🤖 NTv3 in Claude Code

The NTv3 Claude Skill provides a natural-language interface to NTv3 models and genomic analysis tools. It combines model outputs with external genomic data and annotations to support analysis and interpretation of genomic regions.

Current analyses include functional-track prediction, saliency (gradient-based attribution), single-nucleotide variant comparison and gene annotation, with further interpretation methods and tools planned as the skill develops.

Give the agent a gene or region and the analysis you want to run. It asks for any missing details, prepares an analysis plan and waits for your approval before running it.

🧭 How it works

The agent retrieves the reference sequence, runs the selected analyses and gathers relevant external data. Results are assembled into a locus-level report with an interactive genome browser, delivered as a Claude artifact. A Python script supports rerunning the analysis, and an optional notebook provides access to the saved results.

An evidence audit checks references to analysis files and literature and screens report claims for predefined forms of overstatement. Its decisions are recorded alongside the results.

NTv3 skill workflow: the natural-language request 'Predict K562 CAGE and DNase at HBE1 and show which bases drive the prediction', the LLM agent that clarifies inputs and resolves a plan, user approval, then NTv3 track prediction, gradient attribution and single-variant comparison with public ENCODE and UCSC context, an evidence audit, and a locus-level report published as a Claude artifact

🖥️ Example: the HBE1 locus in K562

User
Predict K562 CAGE and DNase at HBE1 and show which bases drive the prediction.
Agent
Species? human · Assembly? hg38 · Tracks? CAGE, DNase · Window length? 131,072 bp · Browser lanes? GENCODE (knownGene), ClinVar (clinvarMain)
Plan
Window chr11:5,204,408–5,335,480 (131,072 bp, GPU, centered on the HBE1 TSS)
Prediction region 49,152 bp · Tracks CAGE CNhs11250_P; DNase ENCSR921NMD
Measured signal ENCODE ENCSR921NMD (DNase) · Attribution CAGE · Evidence audit on
User
Approve→Agent  lookup → predict + saliency → evidence audit → locus-level report (Claude artifact)

Here, the skill uses NTv3_tracks to predict CAGE and DNase signal in K562 cells around HBE1. The 131,072-bp input is centered on the transcription start site; predictions cover the central 49,152 bp, including the β-globin locus control region.

The report brings together predicted CAGE and DNase tracks, measured DNase signal from ENCODE (ENCSR921NMD), and GENCODE and ClinVar annotations. CAGE attributions are shown below the signal tracks. Each lane has its own scale, so compare peak shapes rather than heights. The HBE1 TSS line and the HS1–HS5 labels of the locus control region were added for this figure.

NTv3 skill report browser for HBE1 in K562 over the 49,152 bp predicted crop, with its controls row, range line and ideogram: GENCODE and ClinVar lanes, the NTv3 predicted CAGE track, the measured and predicted DNase tracks, and the CAGE saliency, with the HBE1 TSS and HS1 to HS5 marked

Zooming in on HS4 shows the CAGE attributions at base resolution. Letter heights show the gradient × input of each base for the mean predicted CAGE over the 49,152-bp prediction region. The GATA- and AP-1-like boxes were added for this figure.

HS4, chr11:5,288,225-5,288,345 (120 bp), Saliency · CAGE lane: the saliency letters show a GATA site pair and an AP-1 site

HS4 · chr11:5,288,225–5,288,345 (hg38) · CAGE attribution

🎯 Current capabilities

Analysis What the skill does
Predict Predict functional tracks for a gene or genomic region, with the species and tracks selected for the analysis.
Saliency Show which bases drive a selected prediction, as gradient × input at base resolution.
Compare Predict each allele of a single-nucleotide variant and report the change in each selected track (alternative − reference).
Annotate Predict gene structures for a FASTA, or for the 1 Mb around a Predict run, with the clade-specific NTv3 annotation models.
Explain Show which model, window, crop and head produced each number, read from the run's saved files.

Scope: human (hg38) and mouse (mm10) for Predict, Saliency and Compare; any mammal, plant or insect FASTA for Annotate.

The Home tab describes the models and provides notebooks for running the analyses directly.

🚀 Run the skill

The skill requires Claude Code, Python 3.11 with uv, and network access to UCSC, ENCODE and Hugging Face. Install it from the NTv3 repository (its README has the details):

git clone https://github.com/instadeepai/nucleotide-transformer.git
cd nucleotide-transformer
"$(uv python find 3.11)" -m venv .venv
.venv/bin/pip install -e .      # on a GPU host: .venv/bin/pip install -e '.[gpu]'
uv sync --project ntv3_skills --python 3.11 --frozen
ntv3_skills/.venv/bin/ntv3 doctor

ntv3 doctor finds the Python that runs the model and says whether it sees a GPU; the skill picks the device from it.

GPU or CPU: with the gpu install on a GPU host, the skill uses the GPU for everything: windows up to 1,048,576 bp, such as the 131,072-bp example above, and Annotate (about 25 GB of GPU memory per 1 Mb window). On a laptop CPU, Predict, Saliency and Compare also run; from 16,384 bp the plan warns that it is slow and needs a lot of memory. On either device, Saliency above 131,072 bp comes with a warning that it may run out of memory.

Open Claude Code in the repository directory and try a request that runs on any laptop:

/ntv3 HBE1 at chr11 5266144 5270240 on hg38 in K562. Predict K562 CAGE with a 4,096 bp window and the GENCODE and ClinVar lanes.

The agent asks for any missing details and presents the analysis plan for approval. Once approved, NTv3_tracks predicts K562 CAGE over the central 1,536 bp of the window, at the 3′ end of HBE1, next to the measured ENCODE CAGE signal. Running Annotate on the 1 Mb around this run adds the NTv3 gene model, which matches the three coding exons of HBE1 in GENCODE:

NTv3 skill report browser for the 4,096 bp HBE1 window in K562: GENCODE V50, the NTv3 annotation lane with a three-exon minus-strand gene model matching HBE1, ClinVar, the measured CAGE signal and the NTv3 predicted CAGE track

Report browser for the request above, after Annotate with the mammals model · chr11:5,266,144–5,270,240 (hg38). Thin GENCODE blocks are UTRs; NTv3 predicts coding exons only.

More requests to try:

# Saliency
/ntv3 Predict K562 CAGE at HBE1 with a 4,096 bp window and show which bases drive it.
# Compare (rs334, the HBB sickle-cell variant)
/ntv3 Compare chr11 5227002 T A on hg38 in K562: CAGE with a 4,096 bp window.
# The 131 kb example above (GPU)
/ntv3 Predict K562 CAGE and DNase at HBE1 with a 131,072 bp window and show which bases drive the prediction.
# Annotate a genome (GPU)
/ntv3 Annotate /path/to/genome.fa with the mammals model.
# Annotate the 1 Mb around a Predict run (GPU)
/ntv3 Annotate the 1 Mb around my HBE1 run.

The skill's tools write only to results/ in the repository and upload nothing; the report reaches you as a Claude artifact, and every model download is listed in the plan you approve.

🔗 Links