Skip to content
Get packs

Guide · Agent skill

How to use the pysam agent skill for BAM, VCF and FASTA files

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

The pysam skill gives an AI agent a working knowledge of the pysam Python library and HTSlib-based genomic file formats, including SAM/BAM/CRAM, VCF/BCF, FASTA/FASTQ and tabix tables. This guide explains what the skill changes, how to install it, how to ask for help in plain language, and which safety limits to know. By the end you will be able to get useful, correctly scoped summaries and code from your agent for files you already have.

pysam Genomic File ToolkitK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip. Download the pysam skill ZIP from this page and unzip it. Keep the folder name intact.
  2. 2Place the skill folder. Move the folder to ~/.claude/skills/ for personal use, or to .claude/skills/ inside a project. Alternatively, upload it under Settings → Capabilities → Skills.
  3. 3Install pysam. In the environment where your code runs, install the pinned pysam release with uv. Confirm the install with a short import check.
  4. 4Inspect your file first. Ask the agent to run the inspector on your file. This shows the format, compression and index status without changing anything.
  5. 5Ask your task in plain language. Describe the format, the region and the output you want. Ask for a new output file rather than overwriting an existing one.

What the pysam skill makes the agent do

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches it. With this skill loaded, the agent knows how to read, query, filter and write common genomics formats using pysam, and it follows conventions for coordinates, indexes, headers and output files.

The skill also includes small helper scripts. They summarise a file as JSON, and by default they do not expose sample names or read names.

  • Alignment files: SAM, BAM and CRAM, including pileup and coverage
  • Variant files: VCF and BCF
  • Sequence files: indexed FASTA and sequential FASTA/FASTQ
  • Indexed tables: BGZF-compressed, tabix-indexed BED, GFF, GTF and custom tables

How to install the pysam skill

Download the ZIP for the pysam skill from this page and unzip it. You have two options for where the skill folder goes.

For a personal setup, place the unzipped folder in ~/.claude/skills/. To limit the skill to one project, place it in that project's .claude/skills/ folder.

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

  • Personal: ~/.claude/skills/
  • Single project: .claude/skills/ inside the project folder
  • Claude apps: Settings → Capabilities → Skills

Install the pysam Python package

The skill's guidance is built around the pysam Python package, so the package must be installed in the environment where your code runs. The source pins a release for reproducible work.

Prebuilt wheels are available for supported macOS and Linux platforms. A source build needs a C compiler and HTSlib build dependencies, and the official installation guide is linked from the skill's sources file.

  • Requires Python 3.9 or newer
  • Requires pysam at the pinned release
  • Optional: matching reference FASTA for CRAM decoding
uv pip install "pysam==0.24.1"

How to trigger the skill with natural requests

You do not need special syntax. Describe the file type and the task in plain language, and mention the file name if you have one. The skill is designed for reading, querying, filtering or writing SAM/BAM/CRAM, VCF/BCF, FASTA/FASTQ and tabix data, including pileup, coverage, indexing and CRAM references.

Good requests name the format and the goal. Vague requests such as "look at my data" are less likely to get the right behaviour.

  • "Summarise the read quality counts in sample.bam without printing read names."
  • "Write Python with pysam that lists variants in chr1 from cohort.vcf.gz between 1 and 2 million."
  • "Filter out secondary alignments from input.bam into a new file."
  • "What is in this unfamiliar reference.fa? Check that it has an index first."

Coordinates and indexes you need to know

Numeric coordinates passed to pysam fetch and pileup calls are 0-based and half-open. Region strings such as chr1:100-199 are samtools-style, 1-based and inclusive. Do not mix the two in one call.

Region queries need an index. The skill lists the index types it expects: BAI, CSI, CRAI and TBI. Tabix input must be coordinate-sorted and BGZF-compressed, not ordinary gzip.

CRAM decoding needs the matching reference FASTA. REF_PATH and REF_CACHE are used only if you configure them explicitly.

  • fetch("chr1", 99, 199) uses 0-based half-open coordinates
  • fetch(region="chr1:100-199") uses 1-based inclusive coordinates
  • Write to a new output path and preserve headers
bam.fetch("chr1", 99, 199) # [99, 199) bam.fetch(region="chr1:100-199") # 1-based inclusive

Run the bundled scripts safely

The skill ships four scripts in its scripts folder. The inspector reads metadata only. The QC, variant summary and filter scripts stream through the file. All scripts work on local files, and the skill does not use the network.

All scripts refuse to overwrite existing outputs. The filter also refuses stale output indexes. FASTA inspection requires an existing .fai index, which you create explicitly with pysam.faidx() first. Run any script with --help to see its coordinate, index and privacy notes. The skill's validation covers a local synthetic test suite, not remote storage or real biological datasets.

  • scripts/inspect_hts.py: metadata-only inspection
  • scripts/alignment_qc.py: streaming read and QC counts as JSON
  • scripts/variant_summary.py: variant, FILTER and genotype summary as JSON
  • scripts/filter_alignments.py: filters SAM/BAM/CRAM without changing record order
python scripts/inspect_hts.py sample.bam python scripts/alignment_qc.py sample.bam --max-records 100000 python scripts/variant_summary.py cohort.vcf.gz --region chr1:1-1000000 python scripts/filter_alignments.py input.bam output.bam --exclude-secondary

What people use it for

  • Checking whether a BAM or CRAM file has the index needed for a region query before writing code.
  • Getting a read-only JSON summary of an unfamiliar sequencing file, with sample and read names left out by default.
  • Writing pysam code that lists or filters variants in a VCF or BCF for a chosen region.
  • Filtering secondary or supplementary alignments from a BAM into a new file while keeping record order.
  • Writing pileup or coverage code with explicit mapping and base-quality thresholds.

Frequently asked questions

Is the pysam skill free to use?

The skill is published under the MIT licence, as stated in its source. The pysam library is a separate Python package that you install yourself with the command shown in this guide.

What do I need to run the pysam skill?

You need Python 3.9 or newer, the pysam package at the pinned release, and index files such as BAI, CSI, CRAI or TBI for region queries. CRAM files also need the matching reference FASTA.

How do I install the pysam agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

Can the pysam skill work with files stored in the cloud?

No, not reliably. The skill's validation excludes remote storage and it is not designed around network access, so work with local copies of your files.

Why does pysam say my region query failed?

Region queries usually need an index file next to your data, such as BAI, CSI, CRAI or TBI. Tabix input must also be coordinate-sorted and BGZF-compressed, not ordinary gzip. Check these first with the inspector script.

Does the pysam skill replace clinical variant interpretation tools?

No. The skill's outputs are generic counts and summaries, and it makes no validation claims beyond its synthetic test suite. Use it for exploration and scripting, not regulated or clinical-grade interpretation.

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

Choose the pysam skill if you write pysam code for BAM, CRAM or VCF files, or if you need a quick, read-only summary of an unfamiliar sequencing or variant file, and you work locally in Python. Pick something else if you need clinical-grade interpretation, work mainly with cloud-hosted genomic data, or use non-Python tools.

Download the skill