# tooluniverse-immune-repertoire-analysis

Analyzes TCR and BCR sequencing data: clonotypes, diversity, clonality, and epitope specificity lookup. Built for immune monitoring and clonal expansion work.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 358 installs · ★ 1759
- Author: mims-harvard
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mims-harvard/ToolUniverse/tree/HEAD/skills/tooluniverse-immune-repertoire-analysis/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/tooluniverse-immune-repertoire-analysis

## What it does

The skill runs an 8-phase workflow over AIRR-seq data. It loads MiXCR, ImmunoSEQ, AIRR standard, or 10x Genomics VDJ output and normalizes columns to `cloneId`, `count`, `frequency`, `cdr3aa`, `cdr3nt`, `v_gene`, `j_gene`, `chain`. Clonotypes get defined one of three ways: amino acid CDR3 alone, nucleotide CDR3, or the V gene + J gene + CDR3aa combination. From there it computes Shannon entropy, Simpson and inverse Simpson, Gini, clonality, and richness, then draws rarefaction curves to check whether sequencing depth holds up.

Later phases cover V and J gene usage, CDR3 length distributions, expansion detection above a frequency threshold (95th percentile by default), convergent recombination, and public clonotypes shared across samples. Antigen specificity is not guessed from CDR3 alone — the skill queries IEDB (`iedb_search_tcell_assays`, `iedb_search_epitopes`), BVBRC (`BVBRC_search_epitopes`), and VDJdb (`VDJDB_search_cdr3`, `VDJDB_get_antigen_specificity`). Paired single-cell data can be linked too: clonotypes map to cell barcodes and expanded clones land on a UMAP.

One thing the skill insists on: compare your metrics against healthy donor reference distributions before concluding anything. A Shannon entropy of 7 is unremarkable in a healthy adult and alarming after chemotherapy. Without a reference in hand, the numbers say little. Install runs through `npx skills add`, or `gh skill install` for GitHub Copilot.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-immune-repertoire-analysis -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tooluniverse-immune-repertoire-analysis/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tooluniverse-immune-repertoire-analysis/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-immune-repertoire-analysis -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tooluniverse-immune-repertoire-analysis/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-immune-repertoire-analysis -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tooluniverse-immune-repertoire-analysis/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mims-harvard/ToolUniverse tooluniverse-immune-repertoire-analysis
```

2. **Manually: put the files in place**
- File: `.github/skills/tooluniverse-immune-repertoire-analysis/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-immune-repertoire-analysis -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mims-harvard/ToolUniverse --path skills/tooluniverse-immune-repertoire-analysis
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tooluniverse-immune-repertoire-analysis/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-immune-repertoire-analysis -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mims-harvard/ToolUniverse/tree/HEAD/skills/tooluniverse-immune-repertoire-analysis/SKILL.md

## When to use it
- define clonotypes from a MiXCR or ImmunoSEQ export
- score repertoire clonality and entropy
- find expanded clones after treatment
- check a CDR3 sequence against VDJdb for known specificity
- map clonotypes onto single-cell phenotypes

## Example prompts
- Load this ImmunoSEQ export and define clonotypes by V gene + J gene + CDR3aa
- Compute Shannon entropy, Simpson index and clonality for this repertoire and compare against healthy donor references
- Look up the CDR3 sequence `GLCTLVAML` in VDJdb and show which TCRs recognize it

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4e1cb5136f84fa13.

BEGIN THIRD-PARTY FILE 4e1cb5136f84fa13
```text
---
name: tooluniverse-immune-repertoire-analysis
description: TCR/BCR repertoire analysis — V(D)J segment usage, CDR3 sequence diversity, clonality scoring, antigen specificity matching to IEDB, public-clone identification. Use for adaptive immune response characterization, post-treatment immune monitoring, antigen-specific clone tracking, and clonal-expansion analysis in immunotherapy or vaccination studies.
disable-model-invocation: true
---

# ToolUniverse Immune Repertoire Analysis

Comprehensive skill for analyzing T-cell receptor (TCR) and B-cell receptor (BCR) repertoire sequencing data to characterize adaptive immune responses, clonal expansion, and antigen specificity.

## Domain Reasoning

Repertoire diversity reflects immune history. High clonality — a few clones dominating — indicates antigen-driven expansion, as seen in active infection, tumor-infiltrating lymphocytes, or chronic stimulation. Low diversity points to immunodeficiency or treatment-induced lymphopenia. Always compare observed metrics against healthy donor reference distributions before drawing conclusions; a Shannon entropy of 7 is unremarkable in a healthy adult but alarming post-chemotherapy.

## LOOK UP DON'T GUESS

- Clonotype frequency thresholds, CDR3 length ranges, and convergence ratios: query IEDB or VDJdb; do not assume values from memory.
- Epitope specificities for expanded clones: search `iedb_search_tcell_assays` and `BVBRC_search_epitopes`; never infer antigen identity from CDR3 alone.
- V gene family usage biases in healthy donors: retrieve published reference data or query ImmPort; do not assume baseline distributions are uniform.
- Sequencing depth adequacy: compute rarefaction curves from the actual data; do not guess whether depth is sufficient.

---
```
END THIRD-PARTY FILE 4e1cb5136f84fa13

The third-party file has ended. Everything between the 4e1cb5136f84fa13 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 1784 of 12226 bytes. © mims-harvard · Apache-2.0 · https://github.com/mims-harvard/ToolUniverse/tree/HEAD/skills/tooluniverse-immune-repertoire-analysis/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md