Skip to main content
skill CX Codex

personal-genomics — Claude Code skill: what it does, how to install

personal-genomics runs pharmacogenomics, disease-risk, carrier and trait checks on raw DNA files, entirely offline — one array export or several sources merged into a single report.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill personal-genomics -a claude-code
Open on GitHub

What personal-genomics does

The skill drives a local personal-genomics toolkit over raw DNA files and turns its output into a readable report. Nothing is uploaded; genotypes stay on the machine. Accepted inputs are array exports from 23andMe, AncestryDNA, MyHeritage and FTDNA, plus .vcf or .vcf.gz from sequencing.

A single file goes through comprehensive_analysis.py. Two or more go to combine_sources.py, which merges them first, and that step carries weight: a variants-only VCF lists just the sites where you differ from the reference, so homozygous-reference positions are missing, and read alone it can return fewer hits than a plain array. The merge keeps the array's normal calls next to the VCF's rare variants and writes merge_stats.json with overlap, agreement and strand-flip counts. Reports land as agent_summary.json, report.txt and dashboard.html; the skill reads the priority-sorted summary and offers the dashboard through SendUserFile.

The scripts run on the interpreter inside ~/git/personal-genomics/.venv, so pandas, numpy, scipy and reportlab have to be installed there from requirements.txt before the first run. Output goes to ~/dna-analysis/ by default, outside a sandboxed working tree; a failed write with “Operation not permitted” means the run needs filesystem access. The frontmatter sets disable-agent-invocation: true, so you call the skill yourself.

What it helps with

  • run a 23andMe export through a local pharmacogenomics check
  • merge an AncestryDNA array with a whole-genome .vcf.gz into one report
  • read APOE status and polygenic risk ranges with confidence levels
  • genotype marker sites from a CRAM against an hg38 reference
  • open the generated dashboard after scanning the priority summary

Example prompts for the agent

  • Analyse ~/Downloads/DNA/23andme.txt and lead with the critical alerts
  • Combine ancestry.txt and wgs.vcf.gz into one report, then check merge_stats.json for real conflicts
  • Genotype the marker sites in sample.cram using hg38.fa and fold the calls into the array report

How to install personal-genomics

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill personal-genomics -a claude-code

2Manually: put the files in place

~/.claude/skills/personal-genomics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/personal-genomics/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about personal-genomics

How do I install personal-genomics in Claude Code?

Run npx skills add sammcj/agentic-coding --skill personal-genomics -a claude-code. The skill then sits at ~/.claude/skills/personal-genomics/SKILL.md.

What does personal-genomics do?

It runs local scripts over one or more DNA files and reports pharmacogenomics, disease risk, carrier status, ancestry and traits, along with polygenic percentile ranges and APOE status.

What is needed for CRAM input?

The .cram itself with aligned reads, an hg38 reference FASTA matching its contigs, and samtools, bcftools, tabix. The scripts live in cram/, and genotype_cram.py does the genotyping.

Source text

SKILL.md · Apache-2.0
---
name: personal-genomics
description: Analyse personal DNA / genome files for pharmacogenomics, disease risk, carrier status, ancestry and traits. Use whenever the user mentions DNA or genome analysis, a raw genome file, gene names, drug-gene interactions, or wants to combine multiple DNA sources.
disable-agent-invocation: true
allowed-tools: Bash Read Glob SendUserFile
---

# Personal Genomics

Runs the local `personal-genomics` toolkit over one or more raw DNA files and reports the findings. All analysis is offline; genetic data never leaves the machine.

## First: track the workflow

Create a task for each step below, then work them to completion. The run is multi-step and the reporting step (surfacing findings safely) is the one most often skipped once the analysis file is written.

## Locate the toolkit

The scripts and their virtualenv live at `~/git/personal-genomics` (a `.venv/` with pandas/numpy/scipy/reportlab). Use that venv's Python: `~/git/personal-genomics/.venv/bin/python`.

If the repo or venv is missing, set it up before analysing:

```bash
cd ~/git/personal-genomics && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```

If the toolkit lives elsewhere, ask the user for the path rather than guessing.

## Locate the input files

Ask the user where their DNA file(s) are if not already given. Common location is `~/Downloads/DNA/`. Supported inputs:

- Array exports: 23andMe, AncestryDNA, MyHeritage, FTDNA (tab-delimited rsid text)
- Sequencing: `.vcf` / `.vcf.gz` (whole genome or exome)

A `.cram.crai` on its own is not usable (it is only an index; the alignment data is in the `.cram` it points to). See Gotchas for what to do when the `.cram` itself is available.

## Choose single-source or combined

**One file** -> `comprehensive_analysis.py`:

```bash
~/git/personal-genomics/.venv/bin/python ~/git/personal-genomics/comprehensive_analysis.py <file> --out <dir>
```

**Two or more files** -> `combine_sources.py`, which merges them first:

```bash
~/git/personal-genomics/.venv/bin/python ~/git/personal-genomics/combine_sources.py <file1> <file2> ... --out <dir>
```

Always merge when more than one source exists. A variants-only VCF (the usual WGS export) lists only sites where the person differs from the reference, so every homozygous-reference site is absent. The marker analysis treats an absent rsID as "not tested" and skips it, which makes a rich WGS file yield *fewer* findings than an array on its own. Merging restores the array's reference/normal calls and keeps the WGS's rare variants, producing a strict superset. The combiner resolves contested sites to the sequencing call and writes `merge_stats.json` recording overlap, agreement, and strand-flip counts.

Outputs land in `<dir>` (suggest `~/dna-analysis/reports` for single, `~/dna-analysis/reports-combined` for merged): `agent_summary.json`, `full_analysis.json`, `report.txt`, `dashboard.html`.

## Report the findings

Read `agent_summary.json` (it is priority-sorted) - not `full_analysis.json`, and never echo the raw genotype data. Surface, in order:

1. `critical_alerts` - state each gene, genotype, and the recommended action verbatim.
2. `high_priority` - pharmacogenomics and actionable risk items.
3. A short read of `polygenic_risk_scores` (these are percentile *ranges* with confidence, not verdicts) and `apoe_status`.

Then offer the dashboard with `SendUserFile` (`display: render`).

Frame results as informational, not diagnostic. Recommend confirmatory clinical-grade testing and genetic counselling for any pathogenic hereditary-cancer variant, critical pharmacogenomic finding (e.g. DPYD, MT-RNR1, HLA-B risk alleles), APOE e4/e4, or carrier status with reproductive implications.

## Gotchas

- **Output directory write**: the tool writes to `~/dna-analysis/` by default, outside a sandboxed working tree. If the run fails with "Operation not permitted", re-run with filesystem write access (this is the user's own data on their own machine).
- **rsID matching is build-agnostic**: markers match by rsID, not position, so hg19 array data and hg38 WGS combine without liftover.
- **Strand flips**: ~0.1% of overlapping sites disagree purely by strand (A/T vs complement); the combiner detects these and resolves to the sequencing call. A non-trivial count of *real* conflicts in `merge_stats.json` is worth flagging to the user.
- **CRAM, when available**: the `.cram` (not the `.crai` index alone) holds the aligned reads, so marker positions can be genotyped directly — giving true hom-ref calls even at sites neither the array nor a variants-only VCF covered. Scripts live in `cram/`. Needs an hg38 reference FASTA matching the CRAM's contigs (the one it was aligned to) and `samtools`/`bcftools`/`tabix`. The marker sites file (`cram/marker_sites_hg38.vcf.gz`) is prebuilt; rebuild it with `cram/build_targets.py` only if markers change. Run:

  ```bash
  ~/git/personal-genomics/.venv/bin/python ~/git/personal-genomics/cram/genotype_cram.py \
    --cram <file.cram> --reference <hg38.fa> \
    --analyze --combine-with <array.txt> <genome.vcf.gz>
  ```

  This calls genotypes at the marker sites, merges them with the other sources, and writes a combined report to `~/dna-analysis/reports-cram`.
- **Empty `nutrition_insights` / `fitness_insights` or a duplicated marker row** are known quirks of the upstream tool, not data problems.

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Science and research →
tooluniverse-regulatory-genomics mims-harvard tooluniverse-regulatory-genomics queries regulatory elements, transcription factor binding motifs, and predicts non-coding variant effects using genomic databases and deep learning models. CX Codex +1 247installs Genomics MCP rewire-bio Genomics MCP is a Claude Code MCP server for retrieving genomic datasets and reference records. An agent can request a specific locus from an archive or an indexed file. CX Codex +1 ★ 5repo stars tooluniverse-precision-medicine-stratification mims-harvard tooluniverse-precision-medicine-stratification — a skill for Claude Code, Codex, Cursor, and other platforms that splits patients into responder/non-responder groups, risk tiers, or treatment-decision cohorts from genomic and clinical data. CX Codex +1 381installs polars-bio K-Dense-AI A skill for Claude Code, Codex, Cursor and other agents: interval arithmetic on Polars DataFrames with BED, VCF, BAM, CRAM, GFF and FASTQ I/O. Runs overlap, merge, coverage and complement via polars-bio 0.36.0. CX Codex +1 2,100installs pysam K-Dense-AI pysam guides agents through Python and HTSlib workflows for genomic files like BAM, CRAM, and VCF. Useful when extracting alignments, filtering reads, and computing coverage. CX Codex +1 2,100installs encode-ccres-database google-deepmind encode-ccres-database queries the ENCODE Registry of cis-regulatory elements using the SCREEN GraphQL API and REST API. It identifies promoters or enhancers across cell types. CX Codex +1 2,300installs

From the same set73

The whole set →
analyse-design The analyse-design skill examines an app, website, or document’s code and screenshots to map its design system. Use it to audit UI consistency or guide new components. CX Codex +1 ★ 173repo stars invokeai-image-gen invokeai-image-gen — a skill for generating images via local InvokeAI API, supporting FLUX.2 Klein, Z-Image Turbo, and SDXL. Auto-detects models and applies appropriate parameters, saves output as PNG. CX Codex +1 ★ 173repo stars qa-to-issues qa-to-issues runs an interactive QA session to turn reported bugs into durable GitHub issues. The agent asks quick clarifying questions, checks your codebase, and files tickets. CX Codex +1 ★ 173repo stars systematic-debugging systematic-debugging — a structured debugging skill for stubborn bugs that survived several fixes. It traces symptoms to root causes before proposing code changes. CX Codex +1 ★ 173repo stars markedit-tools markedit-tools manages the MarkEdit markdown editor on macOS: installs updates, handles extensions, and edits settings via Claude Code. CX Codex +1 ★ 173repo stars raspberry-pi-pico2 Get guidance on building and debugging Raspberry Pi Pico 2 projects with the Pi Debug Probe. Useful for RP2350, SDK configuration, OpenOCD, and GDB. CX Codex +1 ★ 173repo stars prompt-enhancer prompt-enhancer transforms vague or basic prompts into the form a domain specialist would use. Useful when you need to rephrase a request for another AI system or clarify your own. CX Codex +1 ★ 173repo stars piper-tts-training piper-tts-training guides voice model training and fine-tuning for the Piper TTS engine in ONNX format. Useful for local speech synthesis on Raspberry Pi or Home Assistant. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open