tooluniverse-protein-structural-annotation-pdb — Claude Code skill
tooluniverse-protein-structural-annotation-pdb annotates PDB protein residues by binding interface, ligand pocket presence, and solvent accessibility.
Apache-2.0 145 installs ★ 1,798 updated 2026-10-24
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a claude-codeWhat tooluniverse-protein-structural-annotation-pdb 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.
What it helps with
- 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 for the agent
- 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
How to install tooluniverse-protein-structural-annotation-pdb
1Skills CLI (Vercel)
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a claude-code2Manually: put the files in place
~/.claude/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tooluniverse-protein-structural-annotation-pdb/
1Skills CLI (Vercel)
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a codex2Manually: put the files in place
.agents/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a cursor2Manually: put the files in place
.cursor/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mims-harvard/ToolUniverse skills/tooluniverse-protein-structural-annotation-pdb2Manually: put the files in place
.github/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.md1Skills CLI (Vercel)
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a gemini-cli2Platform CLI
gemini skills install https://github.com/mims-harvard/ToolUniverse --path skills/tooluniverse-protein-structural-annotation-pdbManually: put the files in place
.devin/skills/tooluniverse-protein-structural-annotation-pdb/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tooluniverse-protein-structural-annotation-pdb
How to install tooluniverse-protein-structural-annotation-pdb in Claude Code?
Run npx skills add mims-harvard/ToolUniverse --skill tooluniverse-protein-structural-annotation-pdb -a claude-code in your terminal.
What does tooluniverse-protein-structural-annotation-pdb do?
It processes a 3D coordinate file to map every residue to functional structural classes, including binding interfaces, ligand contacts, and buried core states.
Can it detect binding pockets without an existing ligand?
No, it classifies known HETATM ligand coordinates; de novo pocket discovery requires external docking suites or PDBe pocket databases.
Source text
SKILL.md · Apache-2.0
---
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)
- `include_secondary_structure` (default false; uses PDBe REST if true)
- `pdb_content` instead of `pdb_id` for local / predicted structures
---
## Workflow
### Step 1 (optional): Find the relevant PDB
If you only have a UniProt accession or gene symbol, pick a structure first:
```python
# PDBe's curated UniProt→PDB mapping (recommended; ranks by coverage + resolution)
PDBeSIFTS_get_best_structures(uniprot_accession="P01116")
# Returns a ranked list of PDB IDs for KRAS with chain mapping
# Or full list (unranked)
PDBeSIFTS_get_all_structures(uniprot_accession="P01116")
# RCSB advanced search (free-text, when you don't have a UniProt yet)
RCSBAdvSearch_search_structures(query="KRAS GTP complex")
```
Pick the structure that contains the **right complex**: include the binding
partner chain you care about, the relevant ligand, and a resolution adequate
for distance-based classification (≤ 3 Å is a safe default).
### Step 2: Run the annotation
```python
Structure_annotate_per_residue(
pdb_id="6VJJ",
target_chain="A",
partner_chains=["B"],
ligand_resnames=["GNP", "MG"],
distance_cutoff=5.0,
core_rsa_cutoff=0.25,
include_secondary_structure=False,
)
```
Returns `annotations: List[{position, aa, dist_partner, dist_ligand, rsa,
region, is_core, ss_element?}]` for every residue of the target chain. For
KRAS in 6VJJ, this yields 168 rows.
### Step 3: Verify the numbering before joining
PDB residue numbers carry **silent offsets** — crystal constructs add
N-terminal cloning residues, and published figures sometimes shift the track
relative to the panel sequence. Always verify with a landmark:
```python
# Get the canonical reference sequence
UniProt_get_sequence_by_accession(accession="P01116")
# Then spot-check: KRAS canonical position 12 should be glycine
assert annotations[11]["aa"] == "G" # 1-indexed position 12, 0-indexed index 11
```
If the landmark mismatches, record the offset explicitly (e.g. `pdb_pos =
uniprot_pos + offset`) before any downstream join. **Do not silently rebase
positions.**
### Step 4: Combine with secondary structure (optional)
If you set `include_secondary_structure=True`, the tool fetches per-residue
helix/strand/coil from PDBe REST. Alternatively, use the dedicated PDBe
secondary-structure tool separately:
```python
pdbe_get_entry_secondary_structure(pdb_id="6VJJ")
# Returns per-chain helix + strand ranges
```
### Step 5: Use the annotation
The returned table is keyed by 1-based canonical residue number. Typical
downstream uses:
| Use case | Field to read |
|---|---|
| Is variant X in a pocket? | `by_pos = {a["position"]: a for a in annotations}; by_pos[X]["region"] in ("ligand", "both")` — index by position field, NOT list index (PDB residue numbers may not start at 1 or be contiguous) |
| Build a DMS heatmap annotation track | `[(r["position"], r["region"], r["is_core"], r.get("ss_element"))]` |
| Filter SAE hotspot features to ligand-binding residues | filter clusters by `region == "ligand"` |
| Compare buried vs surface signal | group statistics by `is_core` |
---
## Interpretation table
| Region label | Biological meaning | Common functional role |
|---|---|---|
| `interface` | Within `distance_cutoff` of a partner chain | Protein-protein binding residue; variants often disrupt complex formation |
| `ligand` | Within `distance_cutoff` of a ligand heavy atom | Pocket residue; variants often disrupt substrate / cofactor / drug binding |
| `both` | Both | Allosteric or shared-surface residue |
| `other` | Neither | Surface (if not `is_core`) or core (if `is_core`) — variants impact through stability or distal effects |
| `is_core=true` | RSA < `core_rsa_cutoff` (0.25 by default) | Buried residue; variants often destabilize the fold |
---
## Honest limitations
1. **One conformer only**. A static crystal structure does not capture
alternative conformations or induced-fit binding. A residue may be at the
pocket in one conformer and away in another. Pick the structure whose
bound state matches your question.
2. **Numbering is fragile**. Crystal constructs add N-terminal tags or skip
disordered N/C termini. **Always verify** with a landmark before joining
to a sequence or to another annotation source. The skill cannot detect
silent offsets for you.
3. **Distance cutoff is a convention, not a truth**. 5.0 Å is the literature
default. Tighten to 4.0 Å for stricter pocket
calls; loosen to 6.0 Å to include 2nd-shell residues.
4. **freesasa RSA can exceed 1.0** for small / unusual structures because the
max-ASA reference is calibrated for a typical protein context. For real
well-folded proteins values cluster in [0, 1.2]; reading them as a
fraction is fine, but treat extreme values as a flag to inspect.
5. **`partner_chains=[]` is permitted** but then all `dist_partner` values
are `null` — interface analysis is skipped entirely.
6. **HETATM ligands only**. Modified residues (e.g. phosphoresidues already
in the chain) are not detected as ligands — they are part of the chain.
---
## Cross-references
| Tool | Role | Use it for |
|---|---|---|
| `Structure_annotate_per_residue` | This skill's atomic tool | The annotation itself |
| `PDBeSIFTS_get_best_structures` | UniProt → ranked PDB list | Step 1 |
| `PDBeSIFTS_get_all_structures` | UniProt → full PDB list | Step 1 |
| `RCSBAdvSearch_search_structures` | Free-text RCSB search | Step 1 |
| `UniProt_get_sequence_by_accession` | Canonical sequence | Step 3 (numbering verification) |
| `pdbe_get_entry_secondary_structure` | SS alone | Step 4 alternative |
| `tooluniverse-residue-functional-mechanism-interpretation` | Downstream consumer | Use this annotation as the structural evidence layer when interpreting DMS hotspots; the skill also plots an annotated DMS heatmap in its Step 7 |
© mims-harvard · Apache-2.0 · mims-harvard/ToolUniverse