How to use the polars-bio genomic intervals agent skill

What an agent skill is and what this one makes the agent do

An agent skill is a folder with a SKILL.md file and supporting reference files. When the skill is installed, the agent can read these instructions and follow them for matching tasks. This skill covers genomic interval arithmetic and bioinformatics file input and output through Polars and DataFusion.

Once installed, the agent can find overlapping or nearest genomic intervals, merge or subtract regions, compute coverage and complement regions, and read or write common files such as BED, VCF, BCF, BAM, CRAM, GFF, GTF, FASTA and FASTQ. The skill also tells the agent to record the assembly and coordinate convention, and to check results against small hand-computable examples.

Install the polars-bio skill from the ZIP

Download the skill ZIP from this page and unzip it. To make it available to Claude Code for all your projects, place the unzipped skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

The skill also needs the Python library. The skill's own install instructions use the command below. Pin the versions exactly as shown, because the skill was tested against them.

• Confirm the Requires section above matches your Python version before installing.
• Keep this environment separate from other packages that need different Arrow or DataFusion releases.

Ask for genomic interval work in plain language

You do not need to name the skill. Describe the task in terms of genomic regions, files or formats, and mention Polars if that is your stack. The skill description covers overlap, nearest, merge, coverage, complement and subtraction, plus lazy file I/O, SQL queries and migration from bioframe.

Good requests name the files and the question. Include the assembly if you know it, and say whether you need hit counts, covered bases or read depth, because these are different results.

• Find which ChIP-seq peaks in peaks.bed overlap genes in genes.bed, and give one row per peak.
• Count how many VCF variants fall inside each target region, keeping the region IDs.
• Convert my bioframe overlap and closest code to polars-bio and flag boundary differences.
• Compute the uncovered regions of this genome, using the chromosome sizes file as bounds.
• Read this BAM file lazily and summarise read depth on chr1.

Understand the coordinate convention before you run anything

The default convention is 1-based closed, including BED reads that the library converts. Setting use_zero_based=True on a genomic reader gives 0-based half-open output. This argument converts positions, so it is not just a label. For example, a BED interval [0,10) becomes [1,10] by default and stays [0,10) with the override.

For DataFrames you build yourself, metadata only labels existing numbers and does not convert them. Convert closed [s,e] to half-open by using s-1 and e, set the metadata after conversion, and never convert twice. The skill's example also turns on the coordinate check option so mismatches raise errors.

• Inspect pb.get_metadata(frame) after transformations and SQL steps.
• Expect CoordinateSystemMismatchError when inputs disagree about their convention.
• Expect MissingCoordinateSystemError if strict mode is on and metadata is missing.

Read files lazily and inspect a small result first

Use scan_* functions for lazy plans and read_* functions for eager reads. Lazy plans do not guarantee bounded memory at every stage, so check schemas and inspect a small result before scaling up. Use the file-specific reader for each format, and check the schema of your real input, because the examples are templates.

BED readers expose BED4 fields. BED3 gives a null name, and extra BED6 or BED12 fields are not kept by the default reader. Use the schema route described in the skill when you need strand or block fields.

• Use the same assembly for every input file in a join.
• Filter and select columns early, then collect.

Choose the right operation for the question

The most common mistake is choosing an operation that answers a different question. overlap returns intersecting pairs, so a query can appear several times. count_overlaps counts target records per query, including zero. coverage returns the number of covered bases, which is not read depth. nearest returns up to k neighbours, and a distance of zero can mean overlap or simple adjacency.

merge and cluster combine overlapping regions, and boundary behaviour depends on min_dist. complement needs explicit finite genome bounds, because without a view it uses an effectively unbounded extent. The skill also notes that on_cols is exposed in some signatures but is not implemented in this release, so split inputs by that key yourself if you need per-group analysis.

• For one result per original query row, ask for left output with distinct output.
• Test boundary fixtures with bookended intervals before trusting merge results.
• Do not treat an arbitrary equidistant nearest candidate as the unique annotation.

Safety notes: scripts, network and credentials

This skill runs scripts and its allowed tools include Read, Write, Edit and Bash. It uses the network only when you read remote data, and that is when provider credentials may be needed. Reading local files does not require network access. For external-reference CRAM files you need a local FASTA and its .fai index.

Read the skill's files and any scripts before you let the agent run them, especially in a project that holds sensitive data. Keep credentials out of prompts and project files where possible.

• Do not use the output for clinical or diagnostic decisions without independent validation.
• Validate maximum coordinates before running, especially for concatenated genomes or custom coordinate spaces above the default overlap index bound.
• Keep provenance: preserve IDs, coordinate metadata and the assembly name when you save results.