Skip to main content
skill CX Codex

protein-interactions — Claude Code skill: what it does, how to install

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.

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-interactions -a claude-code
Open on GitHub

What protein-interactions does

The skill converts PLIP interaction files into clean tabular records, Mermaid network diagrams and PyMOL commands. Core XML parsing relies strictly on Python's built-in xml.etree.ElementTree without requiring lxml, Biopython or internet connectivity.

It processes multi-model AlphaFold *.zip archives by scoring structures with pTM + 0.5 × ipTM and extracting pLDDT metrics. Output files include interaction_analysis.json alongside interactions_residue_level.csv detailing residue pairs, contact types and atomic distances.

Running the parser requires Python 3.9+. The underlying plip binary is mandatory only when computing interactions straight from PDB structures via --run-plip.

What it helps with

  • Parse PLIP report.xml into structured JSON and CSV datasets
  • Rank binding hotspot residues by interaction count
  • Pick the top AlphaFold prediction from a multi-model archive
  • Generate Mermaid flowcharts for contact networks
  • Create ready-to-run PyMOL selection and labeling scripts

Example prompts for the agent

  • Parse report.xml and generate a Mermaid interaction diagram
  • Analyze interactions and rank hotspots from AF-P69905-F1-model_v4.zip
  • Generate a PyMOL script for interacting residues in report.xml

How to install protein-interactions

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

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

Questions about protein-interactions

How to install protein-interactions in Claude Code?

Run npx skills add ssinder/bioinformatics-agent-skills --skill protein-interactions -a claude-code in your terminal.

What does protein-interactions do?

It parses PLIP XML outputs and AlphaFold model packages, tallies contact types, identifies hotspot residues and exports visualizations for PyMOL or Mermaid.

What is required to run protein-interactions?

A Python 3.9+ runtime is necessary. The external plip executable is only needed when analyzing raw PDB structures with --run-plip.

Source text

SKILL.md · MIT
---
name: protein-interactions
description: >-
  Analyzes protein-ligand and protein-protein interactions from PLIP XML reports
  and AlphaFold model packages using a self-contained standard-library XML
  parser: extracts residue-level salt bridges, hydrogen bonds, hydrophobic,
  pi-stacking, water bridges, halogen bonds and metal complexes, ranks hotspot
  residues, and emits Mermaid network graphs plus PyMOL annotation scripts. This
  skill should be used when interaction detection, hotspot ranking, PLIP report
  parsing, interaction network visualisation or AlphaFold confidence analysis
  is requested.
license: MIT
compatibility: Python 3.9+; optional PLIP, MDAnalysis, requests
metadata:
  version: "1.0"
  last-reviewed: "2026-10-25"
  skill-author: sinder
---

# Protein Interaction Analysis

## Overview

This skill turns PLIP (Protein-Ligand Interaction Profiler) reports into structured,
residue-level interaction records and visualisations. The XML parsing is implemented
with the Python standard library (`xml.etree.ElementTree`) only — no `lxml`, no
Biopython, no network access — so a report produced on a workstation can be analysed
anywhere. On top of the parsed records the skill computes per-type and per-residue
statistics, renders an interaction network as a Mermaid flowchart with
per-interaction-type colouring, and generates a ready-to-run PyMOL script that
selects and labels the interacting residues in the 3D structure.

AlphaFold model packages (`*.zip` from the AlphaFold Protein Structure Database) can
be fed in directly: the best model is picked by predicted TM-score confidence
(`pTM + 0.5 × ipTM`) and the per-model confidence JSON is summarised.

## When to Use This Skill

- Parsing a PLIP `report.xml` into machine-readable residue-level interactions
- Ranking hotspot residues by interaction count on receptor and ligand sides
- Detecting salt bridges / hydrogen bonds / π-stacking / water bridges without PLIP
- Selecting the best AlphaFold model from a multi-model package and reporting pLDDT
- Generating a Mermaid interaction graph for reports, slides or documentation
- Generating PyMOL commands that visualise and label the interacting residues

## Quick Start

```bash
# 解析已有 PLIP 报告
python scripts/analyze_interactions.py --input report.xml --output results/

# 同时生成 Mermaid 网络图与 PyMOL 标注脚本
python scripts/analyze_interactions.py --input report.xml \
    --output results/ --make-mermaid --make-pymol

# 直接运行 PLIP 分析结构(需已安装 plip)
python scripts/analyze_interactions.py --input 1crn.pdb --run-plip \
    --plip-structure 1crn.pdb --output results/

# 分析 AlphaFold 模型包(自动挑选置信度最高的模型)
python scripts/analyze_interactions.py --input AF-P69905-F1-model_v4.zip \
    --output results/ --make-mermaid
```

## Workflow

1. **Collect** — `--input` accepts a PLIP `report.xml`, a directory containing
   `report.xml` files, or an AlphaFold `*.zip` package. Directories are scanned
   recursively for `report.xml`.
2. **Parse** — `plip_parser.py` walks the XML with `xml.etree.ElementTree`,
   handling both the modern attribute-style schema (`<site ... onf="A:ARG+102:NE">`
   with child `<salt_bridge>` elements) and the legacy element-style schema
   (`<resnr>`, `<restype>`, `<reschain>` with `_lig` suffixed variants).
   Residue labels are decoded into `chain / resname / resnr / atom` fields,
   distinguishing protein residues (`A:ARG+102:NE`) from ligand atoms
   (`LIG:1:CL1`).
3. **Summarise** — `summarize_interactions` counts interactions per type; the
   entry script additionally ranks receptor and ligand residues by participation
   count to identify hotspots.
4. **Visualise** — `interaction_network.py` renders the Mermaid flowchart
   (nodes = residues grouped into receptor / ligand subgraphs, edges = individual
   interactions coloured by type via `linkStyle`) and the PyMOL script
   (`select` / `show sticks` / `color` / `label` / `distance` commands).
5. **Report** — writes `interaction_analysis.json` and
   `interactions_residue_level.csv`, one row per interaction.

## Parameters

| Parameter | Default | Description |
|---|---|---|
| `--input` | required | `report.xml`、包含报告的目录,或 AlphaFold `*.zip` |
| `--output` | `results/` | 输出目录 |
| `--run-plip` | off | 对输入结构运行 PLIP |
| `--plip-structure` | — | 传给 PLIP 的结构文件(PDB) |
| `--plip-executable` | 自动查找 `plip` | PLIP 可执行文件路径 |
| `--plip-timeout` | `600` | PLIP 超时秒数 |
| `--make-mermaid` | off | 生成 Mermaid 相互作用网络图 |
| `--make-pymol` | off | 生成 PyMOL 标注脚本 |
| `--format` | `both` | `json` / `csv` / `both` |
| `--top-residues` | `10` | 统计中展示的热门残基数量 |

## Outputs

| File | Content |
|---|---|
| `interaction_analysis.json` | 每个报告的完整结果:相互作用记录、按类型统计、热门残基 |
| `interactions_residue_level.csv` | 残基级扁平表(受体残基、配体残基、类型、原子、距离) |
| `*_interaction_network.md` | Mermaid `flowchart` 网络图(启用 `--make-mermaid`) |
| `*_annotation.pml` | PyMOL 标注脚本(启用 `--make-pymol`) |

## Validation

- **Record count sanity**: a PLIP report on a ligand with a buried binding site
  normally yields tens to a few hundred interactions; `0` records for a
  non-empty `report.xml` means the schema was not recognised — inspect the file.
- **Residue label integrity**: decoded labels must keep `resnr` as an integer and
  `resname` as a three-letter code; protein labels contain a `+` separator
  (`A:ARG+102`), ligand labels do not.
- **Hotspot plausibility**: a binding hotspot usually shows ≥ 3 interactions
  (e.g. `ARG102` engaging the ligand in 3 distinct contacts). A flat histogram
  of one interaction per residue usually means the receptor/ligand roles were
  swapped or hydrogens were stripped from the input structure.
- **Type cross-check**: salt bridges require oppositely charged side chains
  (ARG/LYS versus ASP/GLU); a salt bridge between two ARG residues is a parsing
  error, not a result.
- **AlphaFold confidence**: `pLDDT > 90` is high confidence, `70-90` is
  acceptable, `< 70` marks a disordered or unreliable region; a mean pLDDT below
  70 means the model should not be used for interaction analysis at all.
- **Network graph integrity**: the Mermaid file must contain one `linkStyle`
  line per edge; a mismatch means edges were dropped during rendering.

## References

- `references/methodology.md` — PLIP XML schema, interaction definitions, statistics and rendering
- `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-interactions mims-harvard The tooluniverse-protein-interactions skill analyzes protein interaction networks through STRING, BioGRID, SASBDB, and Complex Portal. It distinguishes physical binding from functional associations such as co-expression and co-regulation. CX Codex +1 155installs protein-mcp-server cyanheads Connects AI assistants to experimental and predicted protein databases like RCSB PDB, AlphaFold DB, and UniProt without requiring API tokens. CX Codex +1 ★ 6repo stars pymol google-deepmind A PyMOL skill that renders protein and molecular structures, runs alignments, and measures distances or contacts. Useful when you already have a structure file and need an image or a number. CX Codex +1 2,400installs alphafold-skill official OpenAI Sends compact API requests to the AlphaFold database for predictions and UniProt summaries. Useful when querying protein structure metadata. CX Codex GP ChatGPT +1 14installs alphafold-database-fetch-and-analyze google-deepmind alphafold-database-fetch-and-analyze pulls AlphaFold predicted structures by UniProt ID and works out what they mean: pLDDT confidence, disordered regions, rigid domain boundaries. CX Codex +1 2,400installs

From the same set10

The whole set →
protein-structure 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. 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