Skip to main content
skill CX Codex

tooluniverse-hla-immunogenomics — Claude Code skill guide

tooluniverse-hla-immunogenomics queries IMGT and IEDB for HLA allele polymorphism and peptide-MHC binding. Useful for evaluating vaccine targets and transplant compatibility.

Apache-2.0 234 installs ★ 1,798 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-hla-immunogenomics -a claude-code
Open on GitHub

What tooluniverse-hla-immunogenomics does

The skill handles immunogenomics workflows focused on human leukocyte antigens. It pulls official nomenclature and sequence data from IMGT, while retrieving experimental peptide-MHC assay results from IEDB. UniProt supplies structural protein domain details, and DGIdb links pathway genes to target compounds.

It relies on local computation rather than textual estimates. When data requires filtering or statistical testing, the agent runs Python scripts via Bash with pandas and scipy. It explicitly separates MHC Class I from Class II binding mechanisms.

For complete neoantigen prediction pipelines, this skill delegates work to tooluniverse-immunotherapy-response-prediction.

What it helps with

  • retrieve official HLA allele sequences and nomenclature from IMGT
  • extract experimental peptide binding profiles for specific alleles from IEDB
  • inspect MHC class I and class II restrictions for pathogen antigens
  • check druggability of HLA-related pathway genes through DGIdb

Example prompts for the agent

  • Look up HLA-A*02:01 binding peptides in IEDB
  • Find epitopes presented by MHC class I for influenza HA
  • Retrieve gene sequences and known alleles for HLA-DRB1 from IMGT

How to install tooluniverse-hla-immunogenomics

1Skills CLI (Vercel)

npx skills add mims-harvard/ToolUniverse --skill tooluniverse-hla-immunogenomics -a claude-code

2Manually: put the files in place

~/.claude/skills/tooluniverse-hla-immunogenomics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tooluniverse-hla-immunogenomics/

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

Questions about tooluniverse-hla-immunogenomics

How to install tooluniverse-hla-immunogenomics in Claude Code?

Run npx skills add mims-harvard/ToolUniverse --skill tooluniverse-hla-immunogenomics -a claude-code. The configuration file is saved to ~/.claude/skills/tooluniverse-hla-immunogenomics/SKILL.md.

Which data sources does this skill query?

It connects to IMGT for alleles, IEDB for peptide-MHC binding assays, UniProt for structural protein annotation, and DGIdb for gene druggability.

When should you use a different ToolUniverse skill instead?

If you need end-to-end neoantigen prediction pipelines, use tooluniverse-immunotherapy-response-prediction. For generic gene function checks, use tooluniverse-drug-target-validation.

Source text

SKILL.md · Apache-2.0
---
name: tooluniverse-hla-immunogenomics
description: HLA gene-family analysis and MHC-peptide binding for transplant compatibility, vaccine epitope coverage, and cancer immunotherapy. Uses IMGT (HLA polymorphism), IEDB (epitope-MHC binding), UniProt (annotation), DGIdb (druggability). Use for HLA typing/imputation review, vaccine HLA coverage, and immunotherapy prediction biomarkers (HLA-LOH, neoantigen presentation).
disable-model-invocation: true
---

# HLA & Immunogenomics Analysis

Pipeline for exploring HLA gene families, MHC-peptide binding, epitope associations, and their clinical implications in transplantation, vaccine development, and cancer immunotherapy. Bridges immunogenetic databases (IMGT, IEDB) with functional annotation (UniProt) and druggability data (DGIdb).

## Reasoning Strategy

HLA analysis is fundamentally about peptide presentation: the polymorphism of HLA molecules determines which peptides are displayed to T cells, which in turn governs disease susceptibility, transplant rejection, drug hypersensitivity, and vaccine immunogenicity. HLA type affects disease susceptibility for autoimmune conditions (HLA-B27 and ankylosing spondylitis), transplant rejection (HLA mismatch drives alloresponse), drug hypersensitivity (abacavir causes severe hypersensitivity reactions only in HLA-B*57:01 carriers), and vaccine design (epitopes must be presented by the recipient's HLA alleles to elicit a T-cell response). Class I and Class II HLA molecules have fundamentally different binding grooves, peptide lengths, and T-cell partners — never conflate them. The absence of an epitope from IEDB means it has not been tested, not that it cannot bind.

**LOOK UP DON'T GUESS**: Never assume an allele's binding properties or population frequency — query IEDB for experimental binding data and IMGT for allele annotation. Do not guess which HLA alleles are common in a population; look up published frequency data via PubMed.

**Guiding principles**:
1. **HLA nomenclature precision** -- HLA allele names follow strict conventions (e.g., HLA-A*02:01); get the resolution level right
2. **MHC class awareness** -- Class I (A, B, C) and Class II (DR, DQ, DP) have different binding properties and clinical roles
3. **Species context** -- most queries target human HLA, but MHC exists across vertebrates; confirm species early
4. **Evidence layering** -- combine binding data (IEDB) with gene annotation (IMGT) and structural context (UniProt)
5. **Clinical translation** -- connect molecular findings to transplant matching, vaccine targets, or immunotherapy response
6. **English-first queries** -- use English terms in all tool calls; respond in the user's language

---

## COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

## When to Use

Typical triggers:
- "Look up HLA-A*02:01 binding peptides"
- "What epitopes are presented by MHC class I for [pathogen]?"
- "Find HLA gene information for [allele]"
- "What MHC molecules bind [peptide/antigen]?"
- "Assess HLA associations for [disease]"
- "Find immunogenic epitopes for [virus/protein]"
- "What drugs target HLA-related pathways?"

**Not this skill**: For full neoantigen prediction pipelines, use `tooluniverse-immunotherapy-response-prediction`. For general gene function lookup, use `tooluniverse-drug-target-validation`.

---

## Core Databases

| Database | Scope | Best For |
|----------|-------|----------|
| **IMGT** | International ImMunoGeneTics; HLA/MHC gene nomenclature and sequences | Authoritative HLA gene info, allele nomenclature, sequence data |
| **IPD-IMGT/HLA** | IPD-IMGT/HLA allele database (via `IPD_*` tools); allele-accession-level records and reference cell lines | Full allele-history detail for a specific accession, HLA-typed reference cell lines |
| **IEDB** | Immune Epitope Database; experimentally validated epitope-MHC data | Epitope binding, MHC restriction, T-cell assay results |
| **HLA Ligand Atlas / MHC Motif Atlas** | Mass-spectrometry-eluted, naturally-presented HLA ligands | Direct evidence of presentation (not just predicted/assayed binding) |
| **BVBRC** | BV-BRC (formerly PATRIC/IRD); pathogen epitopes | Pathogen-derived epitopes with host MHC context |
| **UniProt** | Protein function and structure annotations | HLA protein features, domains, variants |
| **DGIdb** | Drug-Gene Interaction Database | Druggability of HLA-pathway genes |
| **PubMed** | Biomedical literature | Clinical HLA studies, transplant outcomes |

---

## Workflow Overview

```
Phase 0: Query Parsing & HLA Disambiguation
  Resolve allele names, identify MHC class, confirm species
    |
Phase 1: HLA Gene Lookup
  IMGT gene info, allele details, sequence data
    |
Phase 2: MHC Binding & Restriction
  IEDB MHC binding data, allele-specific peptide repertoire
    |
Phase 3: Epitope-MHC Associations
  IEDB/BVBRC epitope search, pathogen-specific epitopes
    |
Phase 4: Functional Annotation
  UniProt protein features, structural domains
    |
Phase 5: Clinical & Therapeutic Context
  DGIdb druggability, PubMed clinical evidence
    |
Phase 6: Report Synthesis
  Integrated immunogenomics report
```

---

## Phase Details

### Phase 0: Query Parsing & HLA Disambiguation

Parse the user's input to identify:
- **HLA allele** (e.g., HLA-A*02:01, HLA-DRB1*04:01) -- note resolution level (2-digit vs 4-digit)
- **MHC class** (I or II) -- determines binding groove structure and peptide length
- **Pathogen or antigen** (e.g., SARS-CoV-2 spike, influenza HA)
- **Clinical context** (transplant, vaccine, autoimmunity, cancer)

HLA nomenclature quick reference:
- `HLA-A*02:01` = gene A, allele group 02, specific protein 01
- Class I: HLA-A, HLA-B, HLA-C (present to CD8+ T cells, peptides 8-11 aa)
- Class II: HLA-DR, HLA-DQ, HLA-DP (present to CD4+ T cells, peptides 13-25 aa)

### Phase 1: HLA Gene Lookup

**Objective**: Get authoritative gene and allele information from IMGT.

**Tools**:
- `IMGT_search_genes` -- search for HLA/MHC genes
  - Input: `query` (gene name or keyword), optional `species`, `locus`
  - Output: gene list with nomenclature, locus, species
- `IMGT_get_gene_info` -- get detailed gene/allele information
  - Input: `gene_name` (IMGT gene name)
  - Output: allele sequences, functional status, reference sequences

**Workflow**:
1. Search IMGT for the target HLA gene or allele
2. Retrieve full gene details including functional status and sequence
3. Note the number of known alleles (HLA-A has >7,000; HLA-B has >8,000)
4. Identify whether the allele is commonly studied or rare

**If allele not found**: Check nomenclature -- older names may have been reassigned. Try searching by the gene name alone (e.g., "HLA-A") and filtering results.

**Allele-level detail via IPD-IMGT/HLA**: For the authoritative allele-nomenclature record itself (not just gene-level info), use the IPD-IMGT/HLA tools:
- `IPD_search_hla_alleles` -- search by allele name prefix/substring
  - Input: `name` (e.g. `"A*02:01"` -- NOT `query`, a common mistake)
  - Output: list of `{accession, name}` pairs; a 4-field allele name like `A*02:01` typically matches several full-resolution accessions (e.g. `A*02:01:01:01`, `A*02:01:01:02`)
- `IPD_get_hla_allele` -- fetch the full record for one accession (e.g. `HLA00005`)
  - Output: `allele_history` across IPD-IMGT/HLA release versions -- useful for confirming a name hasn't been reassigned since an older paper was published
- `IPD_search_cells` -- search HLA-typed reference cell lines by field value (e.g. donor lab, cell ID) -- useful for finding a well-characterized homozygous cell line for a given allele

**Verified live example**: `IPD_search_hla_alleles({"name": "A*02:01"})` returns accessions `HLA00005`/`HLA00006`/... for the `A*02:01:01:01`/`A*02:01:01:02`/... sub-lineages; `IPD_get_hla_allele({"accession": "HLA00005"})` returns the full allele-history record.

### Phase 2: MHC Binding & Restriction

**Objective**: Find what peptides bind to a specific MHC molecule, or what MHC molecules present a given peptide.

**Tools**:
- `iedb_search_mhc` -- search for MHC molecules in IEDB
  - Input: `mhc_restriction` (allele name), optional `mhc_class`
  - Output: MHC molecules with binding data counts
- `iedb_get_epitope_mhc` -- get MHC binding details for an epitope
  - Input: `epitope_id` (IEDB epitope ID)
  - Output: MHC restriction data, binding assay results, IC50 values

**Workflow**:
1. Search IEDB for the target MHC allele to see available binding data
2. For specific epitope-MHC pairs, retrieve binding assay details
3. Note binding affinity (IC50 < 500 nM is typically considered a binder for class I)
4. Distinguish between binding assays (in vitro) and T-cell assays (functional)

**Binding affinity interpretation** (Class I):
- Strong binder: IC50 < 50 nM
- Moderate binder: IC50 50-500 nM
- Weak binder: IC50 500-5000 nM
- Non-binder: IC50 > 5000 nM

**Naturally-presented ligands (immunopeptidomics)**: IEDB's binding assays test whether a peptide *can* bind; the HLA Ligand Atlas and MHC Motif Atlas instead report peptides *actually eluted* from HLA molecules by mass spectrometry -- direct evidence of presentation, not just affinity.
- `MHCMotifAtlas_get_allele_ligands` -- curated naturally-presented ligands for one allele
  - Input: `allele` in compact form, e.g. `"A0201"` (Class I) or `"DRB1_01_01"` (Class II) -- no asterisks/colons
  - Output: `{allele, mhc_class, peptides: [{peptide}, ...]}`
- `HLALigandAtlas_get_benign_peptides` -- benign-tissue immunopeptidome from the HLA Ligand Atlas (hla-ligand-atlas.org)
  - Input: `hla_class` must be the literal string `"HLA-I"` or `"HLA-II"` (not `"I"`/`"II"`), optional `limit`
  - Output: peptides with `donor_alleles` (the donor's full typed HLA set, prefixed `s/` for the allele the peptide was specifically assigned to vs. `n/` for the donor's other alleles) and source `tissues`
- `HLALigandAtlas_get_donors` -- donor-to-HLA-allele mapping table
  - Input: optional `donor` / `allele` substring filters
  - **Always filter this call.** The unfiltered (all-donors) query processes the full mapping table and can take 60+ seconds or time out; a scoped query (e.g. `{"donor": "AUT01-DN13"}`) returns in under a second. Never call it with no arguments in an interactive workflow.

**Verified live example**: `MHCMotifAtlas_get_allele_ligands({"allele": "A0201"})` returns real eluted peptides (e.g. `ALFTKVLENV`); `HLALigandAtlas_get_benign_peptides({"hla_class": "HLA-I", "limit": 3})` returns real thymus-tissue peptides with full donor-allele context.

### Phase 3: Epitope-MHC Associations

**Objective**: Find epitopes from specific pathogens or antigens and their MHC restriction.

**Tools**:
- `iedb_search_epitopes` -- search for experimentally validated epitopes
  - Input: `organism_name` (source organism), `source_antigen_name` (protein name)
  - Output: epitope list with sequence, MHC restriction, assay results
- `BVBRC_search_epitopes` -- search pathogen-derived epitopes
  - Input: `query` (pathogen or antigen keyword), optional `host`, `limit`
  - Output: epitopes with host MHC context, assay type

**Workflow**:
1. Search IEDB for epitopes from the target pathogen/antigen
2. Supplement with BVBRC for additional pathogen-specific epitopes
3. Filter by the MHC allele of interest if specified
4. Categorize by assay type: binding assay, T-cell assay (IFN-gamma, cytotoxicity), MHC multimer

**Important**: IEDB epitopes are experimentally validated, not predicted. The absence of an epitope does not mean it won't bind -- it may simply be untested.

**Population coverage for vaccine design**: When selecting epitopes for a vaccine, check how common the restricting HLA allele is in the target population. An epitope restricted to HLA-A*02:01 covers ~50% of Europeans but <15% of some African populations. For broad population coverage, select epitopes across multiple HLA supertypes (A2, A3, B7, B44 cover >95% of most populations).

### Phase 4: Functional Annotation

**Objective**: Get protein-level features for HLA molecules and related proteins.

**Tools**:
- `UniProt_search` -- search for HLA protein entries
  - Input: `query` (protein/gene name), optional `organism`, `limit`
  - Output: protein entries with accession, function, features

**Workflow**:
1. Search UniProt for the HLA protein (e.g., "HLA-A human")
2. Extract functional domains: signal peptide, alpha chains, transmembrane region
3. Note polymorphic positions that define allele specificity
4. Check for structural data (PDB cross-references)

### Phase 5: Clinical & Therapeutic Context

**Objective**: Connect HLA findings to drug interactions and clinical evidence.

**Tools**:
- `DGIdb_get_drug_gene_interactions` -- find drugs targeting HLA-pathway genes
  - Input: `genes` (list of gene names, e.g., ["HLA-A", "B2M"])
  - Output: drug-gene interactions, interaction types, sources
- `PubMed_search_articles` -- find clinical HLA studies
  - Input: `query` (search term), optional `limit`
  - Output: articles with title, abstract, PMID

**Workflow**:
1. Query DGIdb for drug interactions with relevant HLA genes
2. Search PubMed for clinical studies (transplant outcomes, pharmacogenomics, disease associations)
3. For transplant queries, look for HLA matching guidelines and outcomes data
4. For pharmacogenomics, note HLA alleles linked to drug hypersensitivity (e.g., HLA-B*57:01 and abacavir)

**Well-known HLA-drug associations** (for context, always verify with current data):
- HLA-B*57:01: abacavir hypersensitivity
- HLA-B*15:02: carbamazepine SJS/TEN (Southeast Asian populations)
- HLA-B*58:01: allopurinol hypersensitivity
- HLA-A*31:01: carbamazepine drug reaction (European populations)

### Phase 6: Report Synthesis

Structure the report as:

1. **HLA Context** -- gene/allele identification, MHC class, population frequency if available
2. **Binding Profile** -- peptide repertoire, binding affinity distribution
3. **Epitope Landscape** -- pathogen-specific epitopes, assay evidence
4. **Protein Features** -- structural domains, polymorphic sites
5. **Clinical Relevance** -- transplant implications, drug associations, disease links
6. **Evidence Summary** -- graded by source (IEDB experimental > computational prediction > literature mention)

---

## Edge Cases & Fallbacks

- **Ambiguous allele name**: Ask user for resolution level. "HLA-A2" could mean HLA-A*02:01 or the broader A*02 group
- **No IEDB data for allele**: Common for rare alleles. Note the gap; suggest computational prediction tools
- **Cross-species MHC**: IMGT covers multiple species. Confirm species context for non-human queries (e.g., H-2 for mouse)
- **BVBRC empty results**: Try broader organism name or use IEDB as primary source

---

## Limitations

- **No binding prediction**: This skill queries experimental databases, not prediction algorithms (NetMHCpan, MHCflurry). It tells you what has been measured, not what might bind
- **Population frequency gaps**: HLA allele frequencies vary dramatically by ethnicity; databases may not cover all populations equally
- **Class II complexity**: Class II molecules are heterodimers (alpha + beta chains); binding prediction and data are less mature than for Class I
- **Epitope completeness**: IEDB coverage is biased toward well-studied pathogens (HIV, influenza, SARS-CoV-2) and common HLA alleles

© mims-harvard · Apache-2.0 · mims-harvard/ToolUniverse

Similar skills

All skills for Science and research →

From the same set136

The whole set →
tooluniverse-model-organism-genetics tooluniverse-model-organism-genetics is a Claude Code skill for comparing human genes with model organisms, mapping orthologs and retrieving phenotype and expression data. CX Codex +1 235installs tooluniverse-kegg-disease-drug tooluniverse-kegg-disease-drug is a Claude Code skill that links diseases to genes, drugs to targets and variants to pathways via KEGG. It activates on keywords like KEGG disease, drug targets or variant networks. CX Codex +1 235installs tooluniverse-population-genetics-1000genomes tooluniverse-population-genetics-1000genomes is a Claude Code skill for analyzing genetic diversity through 1000 Genomes and comparing variant frequencies across ancestry groups. CX Codex +1 235installs tooluniverse-cancer-classification tooluniverse-cancer-classification maps free-text tumor descriptions to OncoTree codes, links NCI and UMLS IDs, and feeds verified tumor types into OncoKB variant annotations. CX Codex +1 234installs tooluniverse-variant-to-mechanism tooluniverse-variant-to-mechanism — a skill for end-to-end analysis of the genetic-variant-to-disease-mechanism chain. CX Codex +1 233installs tooluniverse-acmg-variant-classification tooluniverse-acmg-variant-classification is a Claude Code skill that classifies germline variants against all 28 ACMG/AMP criteria and cites evidence from gnomAD and ClinVar. CX Codex +1 232installs tooluniverse-regulatory-variant-analysis tooluniverse-regulatory-variant-analysis interprets non-coding and regulatory genomic variants using GWAS Catalog, GTEx eQTLs, ENCODE chromatin data, and AlphaGenome predictions. CX Codex +1 232installs tooluniverse-computational-biophysics tooluniverse-computational-biophysics works through quantitative biology and biophysics problems, from drug clearance calculations to population-genetics comparisons. CX Codex +1 232installs

Project sponsors

Companies that keep this analytics open