Skip to main content
skill CX Codex

protein-structure — Claude Code skill for PDB analysis

protein-structure is a Claude Code skill that analyzes protein structures in PDB files. It activates for requests about secondary structure, radius of gyration, or PDB parsing.

MIT ★ 77 updated 2026-10-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ssinder/bioinformatics-agent-skills --skill protein-structure -a claude-code
Open on GitHub

What protein-structure does

protein-structure reads ATOM and HETATM records, calculates radius of gyration, the gyration tensor, and dipole moments, then assigns secondary structure. Its parser is written in pure Python, and the built-in Kabsch—Sander method can assign structure without an external DSSP program. Alternatively, the skill can call mkdssp. Reports go to structure_analysis.json and structure_analysis.csv.

The scripts can process a single file or a directory of PDB files. They can also fetch protein details from UniProt on request. Python 3.9 or newer is required. Biopython, mkdssp, and requests are optional dependencies; UniProt lookups need network access.

What it helps with

  • parse PDB files without Biopython
  • calculate a protein’s radius of gyration and shape descriptors
  • assign secondary structure with the built-in method or DSSP
  • summarize a directory of PDB files
  • add UniProt details to structural results

Example prompts for the agent

  • Analyze 1crn.pdb and save the reports in results/.
  • Process the PDB files in ./pdb_data and write a batch summary to results/.
  • Add UniProt details to the protein structure analysis.

How to install protein-structure

1Skills CLI (Vercel)

npx skills add ssinder/bioinformatics-agent-skills --skill protein-structure -a claude-code

2Manually: put the files in place

~/.claude/skills/protein-structure/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/protein-structure/

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

Questions about protein-structure

How do I install protein-structure in Claude Code?

Run npx skills add ssinder/bioinformatics-agent-skills --skill protein-structure -a claude-code. The skill file is at ~/.claude/skills/protein-structure/SKILL.md.

What does protein-structure do?

It parses PDB files, calculates protein geometry, and assigns secondary structure. It can also analyze directories and fetch UniProt annotations.

What does protein-structure require?

Python 3.9 or newer is required. Biopython, DSSP (mkdssp), and requests are optional; UniProt lookups require network access.

Source text

SKILL.md · MIT
---
name: protein-structure
description: >-
  Analyzes protein structures from PDB files: parses ATOM/HETATM records with a
  dependency-free pure-Python parser, computes radius of gyration, gyration tensor
  and dipole moments, assigns secondary structure via DSSP or a built-in
  Kabsch-Sander hydrogen-bond implementation, and optionally retrieves UniProt
  metadata. This skill should be used when secondary structure assignment, Rg,
  shape analysis, DSSP, PDB parsing or protein structure annotation is requested.
license: MIT
compatibility: Python 3.9+; optional Biopython, DSSP (mkdssp), requests
metadata:
  version: "1.0"
  last-reviewed: "2026-10-25"
  skill-author: sinder
---

# Protein Structure Analysis

## Overview

This skill turns raw PDB coordinates into quantitative structural descriptors without
requiring heavyweight dependencies. It ships a self-contained PDB parser that handles
`ATOM` / `HETATM` records, multi-model files, alternate locations and insertion codes,
plus a built-in secondary-structure assigner based on the Kabsch-Sander hydrogen-bond
energy model. Geometry (radius of gyration, gyration tensor principal axes, shape
descriptors, dipole moment) is computed in pure Python, and UniProt metadata can be
attached on request.

## When to Use This Skill

- Secondary structure assignment of a protein (`DSSP`, `H`/`E`/`C` content, helix percentage)
- Radius of gyration, radius of gyration tensor, shape anisotropy of a folded protein
- Parsing PDB files without installing Biopython
- Batch statistics over a directory of PDB files (length distribution, average Rg)
- Attaching UniProt protein names, organism and function to structural results
- Preliminary characterisation of AlphaFold models or predicted structures

## Quick Start

```bash
# 单个结构:解析 + 几何 + 二级结构
python scripts/analyze_structure.py --input 1crn.pdb --output results/

# 强制使用内置 DSSP 实现(系统未装 mkdssp 时)
python scripts/analyze_structure.py --input 1crn.pdb --output results/ --dssp-method builtin

# 批量处理整个目录(4 线程)
python scripts/batch_analyze.py --input ./pdb_data --output results/ --workers 4

# 附加 UniProt 元数据(需要网络)
python scripts/analyze_structure.py --input P69905.pdb --output results/ --query-uniprot
```

## Workflow

1. **Parse** — `pdb_parser.py` reads fixed-column PDB records into a
   `Structure → Model → Chain → Residue → Atom` tree. Alternate locations keep only
   the primary conformer (`' '`, `'A'`, `'1'`); `MODEL`/`ENDMDL` splits multi-model files.
2. **Summarise** — chain/residue/atom counts, element composition, heteroatom inventory,
   per-chain one-letter sequences.
3. **Geometry** — `geometry.py` computes mass-weighted `Rg` (and `Rg` over Cα only),
   the gyration tensor with a Jacobi eigen-decomposition, shape descriptors
   (asphericity, acylindricity, relative shape anisotropy) and a partial-charge
   dipole estimate.
4. **Secondary structure** — `secondary_structure.py` either shells out to `mkdssp`
   or runs the built-in assigner: rebuild missing amide hydrogens, evaluate
   Kabsch-Sander hydrogen-bond energies, and classify `H`/`G`/`I`/`E`/`B`/`T`/`S`/`-`.
5. **Annotate** — optionally query `rest.uniprot.org` for protein name, organism,
   sequence length and function via the shared `http_session` (retry + rate limit).
6. **Report** — write `structure_analysis.json` and `structure_analysis.csv`.

## Parameters

| Parameter | Script | Default | Description |
|---|---|---|---|
| `--input` | both | required | PDB file or directory of PDB files |
| `--output` | both | `results/` | Output directory for reports |
| `--dssp-method` | both | `auto` | `auto` / `external` / `builtin` secondary-structure backend |
| `--dssp-executable` | both | auto-detected | Path to `mkdssp` or `dssp` |
| `--hbond-energy` | both | `-0.5` | Hydrogen-bond energy threshold (kcal/mol) for the built-in assigner |
| `--model` | analyze | `1` | Which model to analyse (1-based) |
| `--query-uniprot` | both | off | Enable UniProt metadata lookup (network access) |
| `--format` | analyze | `both` | `json` / `csv` / `both` |
| `--workers` | batch | `4` | Worker threads for batch processing |
| `--pattern` | batch | `*.pdb` | Glob pattern for batch discovery |
| `--recursive` | batch | off | Recurse into subdirectories |
| `--min-residues` | batch | `0` | Skip structures shorter than this |
| `--max-files` | both | `0` | Cap the number of files (0 = unlimited) |

## Outputs

| File | Content |
|---|---|
| `structure_analysis.json` | Full nested report: structure summary, chains, geometry, per-residue secondary structure, UniProt annotation |
| `structure_analysis.csv` | Flat one-row-per-structure table (Rg, shape class, helix/sheet percentages) |
| `batch_summary.json` | Aggregate statistics over a directory plus per-structure detail |
| `batch_results.csv` | Flat table of the batch run |

## Validation

- **Hydrogen-bond geometry**: in a genuine alpha helix the `O(i)···N(i+4)` distance must
  be ~2.9-3.1 Å. The built-in assigner only reports `H` when that contact exists.
- **Backbone sanity**: `Cα(i)-Cα(i+1)` should be ~3.8 Å and `C(i)-N(i+1)` ~1.33 Å.
  Distances far from these indicate a malformed or non-standard PDB.
- **Helix content**: globular proteins typically show 20-50% helix. A reported value near
  0% or 100% for a folded protein is a red flag for the hydrogen-bond threshold.
- **Cross-check**: compare `builtin` against `external` DSSP on the same file
  (`--dssp-method builtin` vs `--dssp-method external`). Agreement within a few
  percent on helix content is expected; large divergence usually means the structure
  lacks resolved hydrogens or is highly non-standard.
- **Rg plausibility**: for a 100-residue globular domain `Rg` is roughly 11-14 Å
  (`Rg ≈ 2.2 × N^0.38` Å is a common empirical rule).
- **Element counts**: hydrogen atoms are usually absent from X-ray structures, so
  `element_counts` containing only C/N/O is expected, not a parse failure.

## References

- `references/methodology.md` — algorithms, formulas and parameter selection rationale
- `references/troubleshooting.md` — common failures and how to diagnose them

© ssinder · MIT · ssinder/bioinformatics-agent-skills

Similar skills

All skills for Science and research →
tooluniverse-protein-structure-retrieval mims-harvard The tooluniverse-protein-structure-retrieval skill for Claude Code retrieves and evaluates protein structures from RCSB PDB, PDBe, AlphaFold, and SWISS-MODEL to help select experimental or predicted models for modeling. CX Codex +1 441installs tooluniverse-protein-structure-prediction mims-harvard tooluniverse-protein-structure-prediction predicts protein structures from amino acid sequences and gathers evidence to assess the models. Use it to examine a new protein or explore how a variant may affect its structure. CX Codex +1 245installs protein-sequence-similarity-search google-deepmind protein-sequence-similarity-search runs a homology search on a protein sequence with MMseqs2 or BLAST, interprets the alignment metrics and writes a Markdown table of top hits. CX Codex +1 2,400installs protein-sequence-msa google-deepmind The protein-sequence-msa skill for Claude Code aligns multiple protein sequences via the EBI Clustal Omega API from a FASTA file and produces a saved alignment with identity metrics. CX Codex +1 2,400installs boltz-protein-screen official Boltz boltz-protein-screen ranks existing proteins, peptides, antibodies and nanobodies against a target through the Boltz API. Not for designing new proteins or screening small molecules. CX Codex GP ChatGPT +1 ★ 8,052repo stars boltz-protein-design official Boltz boltz-protein-design designs de novo protein, peptide, and antibody binders for target structures via Boltz. Useful for candidate generation campaigns without manual scaffold crafting. CX Codex GP ChatGPT +1 ★ 8,052repo stars

From the same set10

The whole set →
protein-interactions protein-interactions is a Claude Code skill that extracts residue-level contacts from PLIP XML reports and AlphaFold archives. Runs on interaction profiling, hotspot ranking and network graphing tasks. CX Codex +1 ★ 77repo stars ml-peptide-generation ml-peptide-generation is a Claude Code skill that generates peptide candidates aimed at binding a target protein. It ranks sequences by pseudo-perplexity and compares peptide lengths and top-k settings. CX Codex +1 ★ 77repo stars ena-download ena-download is a Claude Code skill that downloads sequencing FASTQ files and run metadata via the ENA Portal API. Runs when fetching raw sequencing reads by SRA, ERR, or DRR accessions. CX Codex +1 ★ 77repo stars bioproject-search bioproject-search is a Claude Code skill that retrieves NCBI BioProject metadata via the official E-utilities API. It exports project titles, organisms, and release dates to CSV or JSON. CX Codex +1 ★ 77repo stars protein-docking-lightdock protein-docking-lightdock is a Claude Code skill that runs local protein docking via LightDock and saves best complexes as PDB files. It evaluates receptor-ligand grids and ranks results by DFIRE scores. CX Codex +1 ★ 77repo stars alphafold-db alphafold-db is a Claude Code skill that fetches predicted protein structures and confidence metrics from AlphaFold DB. It runs for requests to retrieve models by UniProt accession or screen them by pLDDT. CX Codex +1 ★ 77repo stars bio-database-fetch bio-database-fetch is a Claude Code skill that retrieves chemical properties from PubChem and taxonomic lineages from NCBI. It queries official REST endpoints in batches of 100 IDs. CX Codex +1 ★ 77repo stars protein-docking-hdock protein-docking-hdock is a Claude Code skill that sends protein docking jobs to HDOCK and collects scores and complex models. It activates for structure-prediction requests or result retrieval. CX Codex +1 ★ 77repo stars

Project sponsors

Companies that keep this analytics open