Guide · Agent skill
How to use the Genomic Coordinates Converter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The genomic-coordinates skill gives an AI agent a set of coordinate rules and small Python scripts for checking positions when data moves between file formats, tools or genome assemblies. It is for bioinformaticians and researchers who suspect an off-by-one error or a wrong genome build. After this guide you will know how to install the skill, ask for the right checks in plain language, and read the output tables the scripts produce.
Genomic Coordinates ConverterK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the genomic-coordinates ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. Alternatively, open Settings, go to Capabilities, and upload the skill under Skills.
- 4Prepare your reference. Have an uncompressed reference FASTA with exact contig names ready, and a .fai index if you have one.
- 5Ask a coordinate question. Describe the files, genome build and problem in plain language, for example an off-by-one suspicion or an indel that fails to match.
- 6Read the diagnostic table. Check the status and exit code in the output table before trusting any joined or converted result.
What the skill makes the agent do
A genomic coordinate is three facts: the number, the convention it is written in (0-based half-open or 1-based inclusive), and the assembly it was measured against. Errors in any of these usually produce no error message, only wrong results. The skill teaches the agent to convert with a table rather than from memory and to verify positions against a reference FASTA when one is available.
In practice the skill covers four jobs: converting intervals between conventions and formats such as BED, GFF/GTF, VCF, SAM/BAM, WIG, PSL, genePred and Picard interval_list; normalising and comparing indel representations; checking whether files use compatible assembly and contig names; and mapping genomic positions to transcript, CDS or protein positions.
- Convert between 0-based half-open and 1-based inclusive coordinates.
- Left-align or trim indels against a reference and compare variant records.
- Detect GRCh37, hg19, GRCh38 or T2T mismatches and chr-prefix naming conflicts.
- Audit a BED, GTF or VCF for convention violations.
Install the skill from the ZIP or the Claude apps
Option one: download the ZIP from this page and unzip it into your personal skills folder, ~/.claude/skills/, so the skill is available in all your projects. To limit it to one project, unzip it into that project's .claude/skills/ folder instead.
Option two: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills. Use whichever method matches how you run your agent. The skill folder should contain SKILL.md, the scripts/ folder and the references/ folder.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- App install: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need to name the skill. The agent loads it when your request matches its description. Requests that mention a coordinate problem tend to work well, for example asking whether a BED file is 0-based, or why a variant from one caller does not match ClinVar.
Useful trigger terms from the skill include off by one, 0-based, 1-based, half-open, coordinate system, left-align, normalize variant, bcftools norm, chr prefix, wrong genome build, liftover, REF mismatch and HGVS. Give the agent the file names and, where you have it, the reference FASTA path.
- Check whether my BED file and my GTF use the same coordinate convention.
- Left-align these indels against ref.fa and tell me which ones are the same change.
- My VCF is GRCh37 but my annotation looks like GRCh38. Check the contigs.
- Convert chr7:5,530,601-5,530,625 from UCSC style to BED.
Run a conversion or a normalisation
The conversion script takes a source and target format and prints a diagnostic table. The first command lists the convention table. The second converts one BED interval to GFF. The third converts a UCSC region string to BED.
Variant normalisation needs a reference FASTA with exact contig names. The helper checks literal alleles against the reference and reports a MISMATCH when they do not agree, which can point to an assembly, strand or coordinate error. Use --split for multi-allelic VCF rows, since unsplit ALT lists are rejected.
cd skills/genomic-coordinates/scripts
python3 convert_coords.py --list
python3 convert_coords.py --from bed --to gff chr1 999 1000
python3 normalize_variant.py --fasta ref.fa chr1 7 CAC CCheck the assembly before you join files
Run the contig checker before merging files from different sources. It reads .fai indexes, .chrom.sizes files, VCF and SAM headers, FASTA, BED and GTF/GFF, identifies the assembly from primary chromosome lengths, and reports naming mismatches, length conflicts, coordinates past a contig end and contigs present in only one file.
A result of unknown or ambiguous with exit code 0 does not prove the files are compatible, because lengths cannot detect same-length sequence changes or masking. Exit code 1 means the checker found a conflict.
- Exit code 1 signals a detected conflict.
- Reference contig supersets are expected and are not treated as errors.
cd skills/genomic-coordinates/scripts
python3 check_contigs.py variants.vcf annotation.gtf --genome GRCh38.fa.faiSafety notes, requirements and limits
The skill runs local Python scripts. The scripts use only the Python standard library, need Python 3.11 or later, and make no network calls. Because the skill runs scripts, review the code before you install it in a shared environment.
The helpers are diagnostic tools, not production VCF rewriters. Their TSV output discards genotypes and annotations. For production VCF normalisation use bcftools norm. Do not use this skill alone to make clinical decisions about patient variants; that requires a validated pipeline and expert review. Bundled text readers expect uncompressed files.
- Requires Python 3.11+ and an uncompressed reference FASTA with exact contig names.
- An optional .fai index makes access more efficient; without it the whole FASTA is loaded into memory.
- Symbolic, breakend, missing and spanning-deletion alleles are passed through as skipped.
- Zero-length BED features cannot be represented for an inclusive target and are reported as unrepresentable.
What people use it for
- Checking whether a BED file from one source is 0-based before intersecting it with a 1-based GTF.
- Left-aligning indels from two callers so that the same deletion is recognised as one variant.
- Diagnosing why a VCF from GRCh37 returns no rows when joined to a GRCh38 annotation.
- Converting UCSC region strings into BED or GFF intervals for a collaborator's tool.
Frequently asked questions
How do I install the genomic coordinates 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 for one project. In the Claude apps you can instead upload it under Settings, then Capabilities, then Skills.
What do I need to run the genomic-coordinates skill?
You need Python 3.11 or later. For variant normalisation you also need an uncompressed reference FASTA with exact contig names, and a .fai index is optional for efficiency. The scripts use only the standard library and make no network calls.
Is the genomic coordinates skill free to use?
The skill is released under the MIT licence, as stated on this page. Check the licence file in the download for the full terms before redistributing it.
What is the alternative to this skill for normalising variants?
For production VCF rewriting, the source recommends bcftools norm. This skill's normalisation helper is a diagnostic tool that outputs a TSV and discards genotypes and annotations.
Why does my variant show a REF MISMATCH?
A MISMATCH can indicate an assembly, sequence, strand or coordinate error. Check the contig names and genome build with check_contigs.py and confirm where your sequence came from before trusting the result.
Can the skill tell GRCh37 from GRCh38 files?
Yes, it identifies the assembly from primary chromosome lengths, which differ between builds, for example chr1 is 249,250,621 in GRCh37 and 248,956,422 in GRCh38. Files whose lengths are not conclusive return unknown or ambiguous, which is not proof of compatibility.
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
This skill suits bioinformaticians merging BED, GTF, VCF or SAM files from different sources, and researchers checking for off-by-one or genome build errors. It is not suited to general coding tasks, and it should not be used alone for clinical decisions on patient variants, where bcftools norm and validated pipelines with expert review are the appropriate tools.
Download the skill