# tooluniverse-protein-structural-annotation-pdb

tooluniverse-protein-structural-annotation-pdb annotates PDB protein residues by binding interface, ligand pocket presence, and solvent accessibility.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 145 installs · ★ 1798 repo stars
- 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-protein-structural-annotation-pdb/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/tooluniverse-protein-structural-annotation-pdb

## What it does

The skill generates a residue-level structural map for a chosen protein chain directly from PDB data. Residues are categorized into discrete regions: partner chain contacts (`interface`), heavy-atom proximity to small molecules (`ligand`), both, or unclassified (`other`). It also computes relative solvent accessibility (RSA) using a default core cutoff of 0.25 to flag buried core positions.

The underlying workflow includes structure discovery via PDBe SIFTS or RCSB search, per-residue classification via `Structure_annotate_per_residue`, landmark verification against UniProt sequences, and optional secondary structure retrieval from PDBe REST endpoints. The default distance boundary sits at 5.0 Å. Custom or predicted models can be supplied directly using `pdb_content`.

Crystal structures frequently introduce numbering shifts due to purification tags or missing termini, making landmark checks mandatory before merging data.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mims-harvard/ToolUniverse skills/tooluniverse-protein-structural-annotation-pdb
```

2. **Manually: put the files in place**
- File: `.github/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mims-harvard/ToolUniverse --path skills/tooluniverse-protein-structural-annotation-pdb
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -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-protein-structural-annotation-pdb/SKILL.md

## When to use it
- Generate an annotation track for DMS heatmaps
- Verify whether a specific variant sits in a core, pocket, or binding interface
- Interpret SAE feature drops against physical structural context
- Separate buried residues from solvent-exposed ones using RSA calculations

## Example prompts
- Annotate chain A of PDB 6VJJ with partner B and ligands GNP and MG
- Fetch the best PDB entry for UniProt P01116 and classify binding residues
- Check if residue position 12 is located inside a ligand pocket in 6VJJ

## 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: 3ef02330e0d8a4ef.

BEGIN THIRD-PARTY FILE 3ef02330e0d8a4ef
```text
---
name: tooluniverse-protein-structural-annotation-pdb
description: "Given a PDB structure, produce a per-residue annotation table: which residues sit at a binding interface (vs a partner chain), which line a ligand pocket, which are buried (core) vs solvent-exposed (surface), and optionally secondary structure. This is the structural track drawn under a DMS heatmap and the structural prior SAE feature drops are read against. Use when you need to anchor a variant-interpretation or DMS analysis to the protein's actual physical context."
disable-model-invocation: true
---

# Protein structural annotation from a PDB

For each residue of a target protein chain, classify whether it sits at a
binding interface, in a ligand pocket, is buried vs solvent-exposed, and
(optionally) which secondary-structure element it belongs to. This is the
annotation track that anchors any DMS heatmap or per-residue interpretation
to the protein's actual physical context.

---

## When to use this skill

- Building a per-residue annotation track for a DMS heatmap
- Deciding whether a variant of interest is **in an interface, in a pocket, or
  in the core** — context that often distinguishes plausible mechanisms
- Reading SAE feature drops at a position against the protein's known biology
  (a feature drop at a ligand-pocket residue means something different from a
  drop at a surface residue)

**Not for**:
- Multi-conformer ensembles or NMR structure comparisons → use
  `tooluniverse-computational-biophysics`
- Whole-structure pocket detection without a known ligand → use a docking
  tool (e.g. SwissDock) or PDBe's pre-computed pockets

---

## Required inputs

| Input | Format | Example |
|---|---|---|
| PDB ID | 4 characters | `6VJJ` (KRAS-RAF1-GTP analogue) |
| Target chain | single character | `A` |
| Partner chain(s) | list of chain IDs | `["B"]` |
| Ligand resnames | 3-letter PDB names | `["GNP", "MG"]` |

Optional:
- `distance_cutoff` (default 5.0 Å)
- `core_rsa_cutoff` (default 0.25)
```
END THIRD-PARTY FILE 3ef02330e0d8a4ef

The third-party file has ended. Everything between the 3ef02330e0d8a4ef 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 2009 of 7875 bytes. © mims-harvard · Apache-2.0 · https://github.com/mims-harvard/ToolUniverse/tree/HEAD/skills/tooluniverse-protein-structural-annotation-pdb/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
