Guide · Agent skill
How to use the TileDB-VCF agent skill for genomic variant stores
Updated · written with AI from the project's own documentation and checked against our catalogue data
The tiledbvcf skill gives an AI agent detailed working knowledge of TileDB-VCF, a tool that stores many single-sample VCF or BCF variant files in one indexed dataset so you can query them by genomic region, sample, or attribute. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to check before trusting results. It is written for readers who have never used an agent skill before.
TileDB-VCF Genomic Variant StoreK-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 .claude/skills/ inside a project. Alternatively upload the ZIP under Settings, Capabilities, Skills in the Claude apps.
- 2Install TileDB-VCF. Create a Conda environment from the tiledb channel using the command in the install section, then confirm the import prints a version.
- 3Check your input files. Confirm each VCF or BCF holds one sample, is coordinate sorted, and has an index. Record the reference assembly and contig names before ingesting.
- 4Create the dataset and ingest. Create the dataset explicitly, then ingest samples. Add later samples incrementally to the same dataset.
- 5Run a small test query. Query a known small interval for known samples and compare the output to the source file, paying attention to 1-based versus 0-based coordinates.
- 6Export and verify. Export the subset, then check it against the source before using it in analysis.
What an agent skill is and what this one does
An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches it. Once this skill is installed, the agent has detailed guidance on TileDB-VCF rather than relying on general knowledge.
The skill covers installing the native TileDB-VCF software, checking input files (one sample per file, coordinate sorted, indexed), ingesting samples incrementally, running region and sample queries with the correct coordinate conventions, streaming large results, and exporting subsets. It also warns about common pitfalls such as mixed genome assemblies and memory limits.
Install the skill from the ZIP or the Claude apps
Download the skill ZIP from this page and unzip it into one of two locations. For a personal install, put the unzipped folder in your home directory under the skills folder for Claude. For a single project, put it in a skills folder inside that project's .claude directory.
If you use the Claude apps instead, upload the ZIP under Settings, then Capabilities, then Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ inside the project folder
- Claude apps: Settings, then Capabilities, then Skills, then upload the ZIP
Install the TileDB-VCF software the skill depends on
The skill needs the native TileDB-VCF Python package. It is not on PyPI. It comes from the official tiledb Conda channel, which provides builds for macOS (Apple Silicon and Intel) and Linux x86-64 with Python 3.9 to 3.12. The tiledb package on PyPI is a different library (TileDB-Py) and does not install TileDB-VCF.
The skill's tested macOS Apple Silicon setup pins several extra libraries to avoid import failures. Treat the block below as the verified command for that environment, not a guarantee for every platform. Preserve the resolved environment for production work.
- You need Conda or Micromamba.
- bcftools is needed to compress and index input VCF files.
- Optional: the tiledb-cloud Python client, an account token, and storage permissions if you want TileDB Cloud.
conda create -n tiledb-vcf -c tiledb -c conda-forge python=3.12 tiledbvcf-py=0.40.3 azure-core-cpp=1.16.2 azure-storage-blobs-cpp=12.16.0 azure-storage-files-datalake-cpp=12.14.0 capnproto=1.4.0 c-blosc2=2.23.1
conda activate tiledb-vcf
python -c 'import tiledbvcf; print(tiledbvcf.version)'
tiledbvcf versionPrepare inputs and build a cohort dataset
Before ingesting, record the reference assembly, contig names and lengths, variant caller, normalization rules, sample identity, and file checksums. Do not mix assemblies, and do not assume that 1 and chr1 are the same contig. Each input file must contain exactly one sample, be coordinate sorted, and have an index. The skill's guidance is to check sample identity with bcftools query rather than trusting filenames.
Create the dataset explicitly before ingesting. Opening it in write mode alone does not create the schema. Start with a small known interval and a round-trip export before scaling up. Add new samples incrementally to an existing dataset rather than calling create again.
- Use BGZF-compressed VCF or BCF with a matching .csi or .tbi index.
- Ingest incrementally; do not blindly re-ingest samples that are already present.
- Use resume only for interrupted ingestion, not for correcting duplicates.
bcftools view -Oz -o sample1.vcf.gz sample1.vcf
bcftools index -c sample1.vcf.gz
bcftools query -l sample1.vcf.gzQuery by region and sample, and read coordinates correctly
Coordinate conventions are the most common source of silent errors. Python region strings are 1-based and closed, and returned pos_start and pos_end are 1-based and inclusive. BED input is 0-based and half-open. Stats and allele-count reads return a 0-based pos column in this release, so add one before joining to VCF POS.
Queries return overlapping records, not only records that start inside the interval. The Python region parser requires the explicit contig:start-end form, so a bare contig name is rejected. For a whole-contig query, use a known contig length.
Large results should be read in batches. read() and read_arrow() may return only the first memory-limited batch, so continue until the read is complete or use read_iter(). Avoid concatenating every batch if the result will not fit in memory. Note that a read memory budget is not a cap on total process memory.
- Region strings: chr1:10-14 is 1-based and closed.
- BED files: 0-based and half-open.
- fmt_GT values: 0 is REF, positive values index ALT alleles, and -1 means missing. Integer lists do not preserve the original phased GT string.
- Selection state persists between calls in this release when bed_file is omitted, so open a fresh Dataset for an independent query.
import tiledbvcf
cfg = tiledbvcf.ReadConfig(memory_budget_mb=128)
with tiledbvcf.Dataset('cohort', cfg=cfg) as ds:
for batch in ds.read_iter(attrs=['sample_name','contig','pos_start','pos_end','alleles','fmt_GT'], regions=['chr1:1-100'], samples=['S1','S2']):
print(batch)Export subsets and check the results
The skill covers exporting subsets of samples and regions back to VCF or BCF. Python export formats are v for VCF, z for compressed VCF, u for uncompressed BCF, and b for compressed BCF. Setting merge to false writes one file per sample. Always compare an export against the source for a small interval before relying on it downstream.
- v: VCF
- z: compressed VCF
- u: uncompressed BCF
- b: compressed BCF
ds.export(samples=['S1'], regions=['chr1:1-100'], output_format='v', output_dir='exported')What people use it for
- Storing hundreds of single-sample VCF files from a sequencing project in one indexed dataset for later lookup.
- Adding newly sequenced samples to an existing cohort without rebuilding it.
- Pulling all variant records for a gene region across a set of samples for review.
- Exporting a subset of samples and regions as VCF or BCF for a downstream tool.
- Checking input files for sample identity, sort order and indexing before ingestion.
Frequently asked questions
Is the TileDB-VCF agent skill free and what licence does it use?
The skill is published under the MIT licence. The skill itself is a set of instructions and files, but it relies on the TileDB-VCF software and optionally TileDB Cloud, which have their own terms.
What do I need before I can use the tiledbvcf skill?
You need the native TileDB-VCF install from the tiledb Conda channel, with Python 3.9 to 3.12, plus Conda or Micromamba and bcftools. The TileDB Cloud client, an account token and storage permissions are optional and only needed for cloud use.
Why does pip install tiledb not give me TileDB-VCF?
The tiledb package on PyPI is TileDB-Py, a different library. TileDB-VCF is distributed through the tiledb Conda channel, so install it with Conda or Micromamba.
Why are my region query results off by one?
Python region strings are 1-based and closed, while BED input is 0-based and half-open. Stats and allele-count tables use a 0-based pos column, so add one before matching to VCF POS.
Does TileDB-VCF do joint calling or association testing?
No. The skill states that TileDB-VCF stores records and does not perform joint variant calling, association testing, normalization, or population structure adjustment. Use other tools for those steps.
Does the skill run code and access the network?
Yes. The skill runs scripts and uses the network for installation and for remote storage or TileDB Cloud. Review the commands before running them, and only use TileDB Cloud with credentials you are authorised to use.
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 bioinformatics teams and developers who need to store and query cohort-scale variant calls and want an agent to help set up and check the workflow. It is not suited to joint calling, association testing, or any clinical or patient-facing decision without expert validation, and users without bioinformatics training should have an expert review assembly, coordinate, and sample handling.
Download the skill