How to use the Gtars Genomic Interval Toolkit agent skill

What the gtars skill makes the agent do

Without a skill, an agent will often write quick scripts that load a BED file and count overlaps without checking the data. The gtars skill changes that. Before analysis, the agent is told to check coordinates, assembly, chromosome names and strand, and to run bundled local validators that inspect files without changing them.

The skill covers set operations, overlaps and counts, consensus and coverage, tokenization, fragment processing, and refget/BEDbase planning. It is written for Python, Rust and the gtars command-line tool, and asks for explicit approval before any network access or downloads.

• Validate BED interval files against an assembly and chromosome sizes before use
• Compare and combine interval sets with overlaps, intersections, reduction and coverage
• Plan refget and BEDbase work, which requires approval for network and storage

Install the gtars skill from the ZIP

Download the skill ZIP from the skill page and unzip it. For a personal setup, place the folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder so that only that project uses it.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills. Either way, the skill's own files are the ones described in SKILL.md, including its scripts and reference notes.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements and safety notes first

The skill needs Python 3.10 or newer. The Python package is a native extension from PyPI, and the skill's examples were exercised on Python 3.12. Rust and gtars-cli are optional, for command-line or Rust use, and need a Rust toolchain that supports Edition 2024. uv or pip can set up an isolated environment.

Treat installation as running code. Installing Gtars through Python loads native code, and installing the CLI through Cargo compiles native code and may run dependency build scripts. The skill asks you to confirm the official source, review the release and checksums, and use isolation and resource limits. Remote constructors, pretrained tokenizers, refget and BEDbase caching all need explicit network and storage approval. The bundled audit scripts use only the Python standard library and make no network calls.

• Python 3.10 or newer; optional Rust toolchain for CLI or Rust work
• Installing the package runs native code: review it first
• Network access, downloads and caching need your explicit approval
• Scripts run locally; the bundled inspectors do not change input files

Ask for work in plain language

You do not need special command syntax. Describe the file and the goal, for example that you have a BED file and want to check it against a named assembly, or that you want to know how two region sets overlap or how much of one is covered by the other. The skill's description lists the tasks it supports, so requests that match those tasks are the ones it is built for.

Give the agent the details it needs to follow the data contract: the assembly, the chromosome sizes file if you have one, whether the file must be sorted, and where outputs should go. If you do not know the assembly, say so; the skill is designed not to guess it from filenames or chr prefixes.

• Validate: "Check this BED file against GRCh38 before I use it"
• Compare: "Count how many query regions overlap the universe file"
• Summarise: "Give me the fraction of these peaks covered by the gene set"

Run the local validator on a BED file

The skill's first step is a local validator that inspects a file without changing it. You can run the same command yourself to see what the agent will check. It asks for an assembly label, a chromosome sizes file and a sorting requirement.

The validator enforces the coordinate rules: BED intervals are 0-based and half-open, start must be less than end, and no end may exceed its contig length. Contig names must match exactly, so 1 and chr1 are treated as different names.

Use the Python API for overlaps and coverage

In Python, gtars models are imported from submodules rather than the top-level gtars package. RegionSet holds a set of intervals, and methods such as count_overlaps, any_overlaps and coverage return one result per query region or a single fraction, depending on the method.

Set RegionSet.sort() mutates the object and returns None, so do not assign its result. File-backed RegionSet objects sort lexicographically by contig and start when loaded, so do not rely on original row order. Loading does not merge overlapping intervals; call reduce() when you want that.

• Import from gtars.models, for example Region and RegionSet
• Overlap methods use ordinary half-open overlap, so [0,10) and [10,20) do not overlap
• reduce(), and consensus, merge overlapping and adjacent intervals

Keep strand and provenance under your control

The skill warns that strand is not reliably carried through every operation. A file-backed RegionSet starts its strand list as unspecified, sort() does not reorder that list, and several set operations drop strand. If strand matters scientifically, validate it separately and keep the original file.

The skill also asks for provenance: record file checksums, the assembly accession, the lockfile and artifact hashes, and the resource limits used. Outputs should go to a dedicated folder, and existing files should not be overwritten unless you approve it.

• Keep the original file and sort a copy when an operation needs sorting
• Record checksums, assembly, and library versions with the results
• Set limits on input size, memory, disk and run time for larger jobs