Guide · Agent skill

How to use the Geniml genomic interval agent skill

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

The Geniml skill gives an AI agent a safety-first workflow for machine learning on genomic interval sets, which are BED files listing chromosome regions such as peaks. It is aimed at bioinformatics and computational biology researchers who are preparing peak files for Geniml embeddings. After reading this guide you will be able to install the skill, ask the agent for a validation or training plan in plain language, and know which checks the bundled scripts do and do not perform.

Geniml Genomic Interval ToolkitK-Dense-AI/scientific-agent-skills · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in your project. You can also upload it under Settings, then Capabilities, then Skills.
2Create a pinned Python environment. Use uv to create a Python 3.12 environment and install the pinned geniml and gtars packages. Add the optional ML or consensus packages only if your task needs them.
3Prepare your local inputs. Place your BED files and a trusted chromosome-sizes file on your machine. The skill works only with explicit local regular files and rejects URLs and symlinks by default.
4Ask for a validation plan. Ask the agent to validate your BED file against the declared assembly. Run the bed_validator.py command it shows and review the proposed actions. The validator does not change your file.
5Plan the embedding or universe run. Ask the agent for a Region2Vec, scEmbed or consensus plan. Review the bounds on workers, epochs and output size before approving anything.
6Run commands yourself. Execute any training or package commands yourself after you have approved them. The bundled scripts plan and validate but do not train models.

What the Geniml skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent reads when it is relevant to a task. This skill covers Geniml, a toolkit for machine learning and statistical work on genomic interval sets. Once it is installed, the agent treats coordinates, genome assemblies, token vocabularies, model files and sample grouping as explicit contracts that must match before any analysis starts.

In practice the agent can validate BED files and universe files against a chromosome-sizes file, plan Region2Vec or scEmbed training runs, inspect whether a model and its tokenizer are compatible, and assess consensus peak universes. The bundled Python scripts only validate and produce plans. They do not run training, import Geniml, or contact the internet. You or the agent run any actual training commands, after you have installed the packages yourself.

Validate BED structure and the declared assembly against a trusted local chromosome-sizes file
Plan Region2Vec or scEmbed runs, including bounds on workers, epochs and output size
Check model and tokenizer compatibility before reuse
Assess consensus universes built with coverage-based methods

Install the skill in Claude

Download the skill ZIP from this page. You can then install it in one of two ways. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

After installing, start a new session so the agent can see the skill. The skill's main instruction file is SKILL.md, and it sits alongside a references folder and a scripts folder.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into .claude/skills/ inside your project
Claude apps: Settings, then Capabilities, then Skills, then upload

Install the Python packages for Geniml

The skill's tested stack uses Python 3.12 managed with uv. Create a separate project environment, then install the pinned Geniml and gtars packages. Do not skip the pins, because the skill's checks were run against this exact stack.

Region2Vec and scEmbed need extra libraries, and the consensus recipes need two more. Install only what your workflow needs. The source notes that Geniml requires Zarr below version 3, so keep the AnnData and Zarr pins shown here. Never force an incompatible install with --no-deps.

Required: Python 3.12 (tested) managed with uv, plus geniml and gtars
Optional for Region2Vec or scEmbed: torch, gensim, huggingface-hub, scanpy, anndata and zarr
Optional for consensus universes: pyBigWig and hmmlearn
You also supply your own BED files and a trusted chromosome-sizes file

uv venv --python 3.12
uv pip install "geniml==0.8.4" "gtars==0.10.0"

Ask the agent for a validation plan first

Start with validation before any analysis. The bed_validator.py script checks structure and the declared assembly, then reports proposed actions. It never rewrites your BED file. You can ask the agent in ordinary language, for example: check whether my peak file matches GRCh38 and the chromosome sizes file I provided.

The source specifies a coordinate convention to expect. BED intervals are normally 0-based and half-open, meaning the start is included and the end is excluded. Reject negative coordinates, intervals where the end is not greater than the start, unknown contigs, and mixed assemblies. Sorting never fixes an assembly mismatch.

Coordinates are 0-based, half-open: length is end minus start
Mixed assemblies, unknown contigs and silent renaming should be rejected
BED3 files have no strand; keep column 6 values if present

python skills/geniml/scripts/bed_validator.py \
  --input data/peaks.bed \
  --assembly GRCh38 \
  --chrom-sizes refs/GRCh38.chrom.sizes

Plan Region2Vec or scEmbed runs and check compatibility

For Region2Vec, the agent can plan a run that uses a tokenizer built from your universe file and a Parquet file with one list-valued tokens column. One important point: only token IDs that survive frequency filtering during training receive learned weights. Universe membership alone does not prove a token has an embedding, so the agent should report the fraction of excluded tokens.

For scEmbed, the AnnData var table must contain chr, start and end columns, and rows are cells. The skill's inspectors check model artifacts and tokenizer compatibility before you reuse them, and the reference files cover the export and encoding details.

Region2Vec needs a Parquet file with a tokens column, one document per row
Record token frequencies and min_count settings
scEmbed reads chr, start and end from AnnData var
Released tokenize_anndata and ScEmbed.encode calls fail with this gtars version, so the skill uses explicit Region construction

Assess consensus peak universes

A consensus universe is a reference set of intervals built from coverage across many BED files. The skill covers four methods: coverage cutoff, coverage cutoff with flexible core and boundary fields, a maximum-likelihood flexible universe, and a hidden-state model over start, core and end coverage. The source says no single method is universally best, so choose using training-only data, assay-specific validation and held-out fit measures.

All source BED files and the chromosome sizes must agree on assembly and naming before the universe is built. Ask the agent to run a consensus plan from your local files, and it will flag inputs that break that contract.

Coverage cutoff (CC) and coverage cutoff with flexible fields (CCF)
Maximum-likelihood flexible universe (ML)
Hidden-state model (HMM)
Needs pyBigWig and hmmlearn for the consensus recipes

What people use it for

Checking whether a set of ChIP or ATAC peak files uses the same assembly and contig naming before building embeddings
Planning a Region2Vec run with a tokenizer built from a fixed universe file and a documented token-frequency report
Inspecting whether a saved model and its tokenizer still match before reusing them on new data
Comparing candidate consensus universes built from training-only peak sets

Frequently asked questions

How do I install the Geniml agent skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings, Capabilities, then Skills. Start a new session afterwards so the agent picks it up.

What do I need to run the Geniml skill?

You need Python 3.12 managed with uv, the pinned geniml and gtars packages, and your own local BED files plus a trusted chromosome-sizes file. Region2Vec, scEmbed and the consensus recipes need extra optional libraries. The skill does not download data for you.

Is the Geniml skill free to use?

The skill's content is licensed under MIT, as stated in its frontmatter. Geniml itself is licensed under BSD-2-Clause according to the source. Check each package's licence before commercial use.

Does the skill train models or access the internet?

No. The bundled scripts only validate inputs and produce plans. They do not import Geniml, run training, or make network requests. Any download of a model or dataset needs your explicit approval first, and any training commands are run by you.

What is the difference between Region2Vec and scEmbed?

Region2Vec learns vectors for genomic regions from how they co-occur within interval sets, using a Parquet token file. scEmbed works on single-cell data stored in AnnData, where rows are cells and nonzero features mark accessible regions. The skill plans both but treats their inputs as different contracts.

Why does my tokenizer have more entries than my universe has rows?

With gtars 0.10.0, seven special tokens are added to a BED vocabulary, so the tokenizer length is not the same as the number of universe rows. Keep the universe row order and the exact special-token map when you reuse the tokenizer.

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 researcher or analyst who wants a documented, checksum-minded compatibility check on genomic interval files before running Geniml. Pick something else if you want one-click training, need clinical or patient-level decisions, or must use a Python stack other than the tested 3.12 setup without verifying it yourself.

Download the skill