How to use the OneKGPd 1000 Genomes Queries agent skill

What the OneKGPd skill makes the agent do

Once installed, the agent can query the 1000 Genomes cohort at the level of individual participants. It can list variants carried in a region, find which individuals carry variants matching your criteria, count those individuals, and check whether two named individuals are related. It can also report dataset totals such as sample count, sex split and variant count.

Variant results come with 1000 Genomes allele frequencies, gnomAD exome and genome allele frequencies, AlphaMissense scores and HGVSp annotations. Results are returned as variants or sample names, not as raw genotypes.

• Variants carried in a region, across the whole cohort or within named individuals
• Individuals carrying matching variants, and counts of them
• Individuals who are homozygous reference at a single position
• Kinship: degree of relatedness (twin, 1st, 2nd, 3rd, unrelated) and the KING kinship coefficient
• Population and pedigree details from a bundled offline data file

Install the skill in Claude

Download the ZIP for the skill from the directory page and unzip it. For a personal install, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Install the prerequisites

The skill needs Python 3.11 or newer and the uv package runner. The API script is run with uv run, which reads the script's inline dependency metadata and installs the dnaerys Python package automatically, so you do not install dnaerys yourself.

You need outbound network access over TLS to db.dnaerys.org on port 443 for variant, sample and kinship queries. There is no API key, no .env file and no rate-limit token to configure.

• Python 3.11 or newer
• uv package runner (https://docs.astral.sh/uv/)
• Outbound TLS access to db.dnaerys.org:443

Ask for what you need in plain language

The agent loads the skill when your request is about individuals or variants in the 1000 Genomes cohort. Name the cohort, the gene or region and the criteria you care about. Give sample names such as HG00096 when you ask about specific people.

Good requests state the question, not the command. The agent chooses the matching subcommand, such as select-variants, select-samples, count-samples, select-samples-hom-ref or kinship.

• Which 1000 Genomes individuals carry rare missense variants in this region on GRCh38?
• How many individuals carry variants with AlphaMissense class likely pathogenic in this interval?
• Are HG00096 and NA21130 related, and at what degree?
• Which individuals are homozygous reference at this position?
• What are the dataset totals for the 1000 Genomes cohort?

Run a query the safe way

Resolve your gene or feature to GRCh38 coordinates first, using an authoritative source such as Ensembl or NCBI. The skill does not convert gene symbols, rsIDs or transcripts to coordinates, and it does not fetch reference sequence. Coordinates are 1-based and inclusive, so a BED interval [start0, end0) becomes start=start0+1 and end=end0.

Count before you select. Run the paired count command first to size the result, then select only if the count is manageable. Selections include both heterozygous and homozygous carriage by default; add --het-only or --hom-only only when your question is about one state.

Filters combine as follows: values within one flag are combined with OR, and different flags combine with AND. Values are case-insensitive. For example, the following accepts missense or stop-gained consequences:

• Take coordinates from an authoritative source and record the source, release and retrieval date
• Run the count command before the select command
• Write output to a file and extract fields with jq rather than reading large JSON into context

Safety notes: scripts and network

The skill runs Python scripts and makes network calls. Variant, sample and kinship queries contact the public service at db.dnaerys.org:443 over TLS. The sample and population metadata commands run offline over a data file bundled in the skill. The skill uses no credentials or environment variables.

Network commands use a 30-second timeout per RPC by default. Retries can extend the total run time beyond that. Scripts write full results to a file, which defaults to a temporary location, so check the printed path.

• Network: TLS to db.dnaerys.org:443 only for variant, sample and kinship queries
• Offline: metadata commands use the bundled data file
• No API keys, .env files or environment variables are used
• Data use: the 1000 Genomes Project and IGSR data-use terms apply (https://www.internationalgenome.org/data)

Tips and limits

Use the skill only for the 1000 Genomes Project. It does not serve other cohorts. Results are research data and are not clinically validated, so do not use them for clinical or diagnostic decisions about a real person.

If the output says result_incomplete=true, the results cannot support a definitive zero or absence claim, so re-run the query after service recovers. If truncated=true on a capped variant selection, more records may exist than were returned.

• Keep coordinates on GRCh38 throughout
• Treat result_incomplete=true as 'unknown', not 'none found'
• Use --page-size only when you need every page, since it accumulates all variants in memory
• Record the annotation releases the service reports when you interpret results