Skip to main content
skill CX Codex

protein-docking-lightdock — Claude Code skill: how to install

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.

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

What protein-docking-lightdock does

The skill drives lightdock3_setup.py and lightdock3.py locally to run glowworm swarm docking. It parses swarm outputs, selects the highest numeric step instead of sorting alphabetically, and builds lightdock_.pdb conformations from origin-shifted coordinates.

Execution relies on run_docking.py, generate_conformations.py, and extract_scores.py. The workflow supports resuming interrupted runs, multi-core CPU execution, and incremental logging to docking_scores.csv.

Running it requires Python 3.9+ and the lightdock package. LightDock is not available on Windows.

What it helps with

  • run local protein-protein docking using LightDock
  • execute batch docking for receptor-ligand grids
  • extract top docked complex conformations into PDB files
  • resume interrupted docking runs without losing progress

Example prompts for the agent

  • Run local docking for receptor rec.pdb against ligands in ligands/ using run_docking.py
  • Generate the best complex PDB structure from results/rec__lig/
  • Summarise DFIRE scores across all completed runs in results/

How to install protein-docking-lightdock

1Skills CLI (Vercel)

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

2Manually: put the files in place

~/.claude/skills/protein-docking-lightdock/SKILL.md

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

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

Questions about protein-docking-lightdock

How to install protein-docking-lightdock in Claude Code?

Run npx skills add ssinder/bioinformatics-agent-skills --skill protein-docking-lightdock -a claude-code.

What does protein-docking-lightdock do?

It coordinates local LightDock runs, evaluates swarm steps, ranks complexes by DFIRE score, and exports docked PDB files.

What is required to run protein-docking-lightdock?

It requires Python 3.9+ and the lightdock package. The package does not work on Windows.

Source text

SKILL.md · MIT
---
name: protein-docking-lightdock
description: >-
  Runs LightDock protein-protein docking locally by driving the lightdock3_setup.py
  and lightdock3.py executables, then extracts the best docked complex. Parses the
  GSO swarm output files with the correct field semantics (glowworm id is the line
  number, not the LigID column), selects the latest gso_<step>.out by numeric step
  rather than dictionary order, and generates conformations from the
  origin-shifted structures that the setup stage produced so the receptor and
  ligand stay in a consistent coordinate frame. Supports batch receptor-ligand
  grids, resumable execution, incremental score logging, and DFIRE-based ranking.
  This skill should be used when protein-protein docking must be performed on the
  local machine, when a swarm-level score ranking is needed, or when the best
  docked complex model must be generated as a PDB file.
license: MIT
compatibility: Python 3.9+; requires the lightdock package (not available on Windows); no third-party Python package required for parsing and scoring
metadata:
  version: "1.0"
  last-reviewed: "2026-10-25"
  skill-author: sinder
---

# LightDock Local Protein Docking

## Overview

This skill runs [LightDock](https://lightdock.org/), a glowworm-swarm-optimization
protein-protein docking engine, **on the local machine** and turns its raw swarm
output into a ranked score table and a set of docked complex structures.

LightDock works differently from the HDOCK skill in this same repository. HDOCK
is a **web service**: you submit a job and the server computes. LightDock is a
**local program**: `pip install lightdock`, and the search runs on your own CPUs.
A single job with 50 swarms × 50 steps takes minutes to hours depending on core
count and protein size. A batch of 100 pairs takes days. This skill is therefore
built around **long-running, resumable, interrupt-safe** batch execution rather
than around request/response handling.

The hard part of driving LightDock from a script is not the subprocess calls —
it is the **output semantics**. The `gso_<step>.out` files and the
`lightdock_<i>.pdb` conformations have three separate traps that all produce
plausible-looking but wrong results, and this skill fixes all three.

## When to Use This Skill

- Running protein-protein docking locally with full control over swarm/step counts
- Ranking a batch of receptor-ligand pairs by DFIRE score
- Recovering the best complex model from an existing LightDock run
- Producing docked complex structures for downstream MD, interaction analysis, or figure preparation
- Comparing against the `protein-docking-hdock` skill when a **local** (no data
  leaves the machine) prediction is required

## Quick Start

```bash
export PYTHONPATH="$PWD/packages"

# 一个受体 vs 一组配体
python scripts/run_docking.py --receptor rec.pdb --ligands ligands/*.pdb \
    --output-dir results/

# 多个受体 vs 多个配体(笛卡尔积)
python scripts/run_docking.py --receptors recs/*.pdb --ligands ligands/*.pdb \
    --output-dir results/

# 快速试跑(先验证流程再上规模)
python scripts/run_docking.py --receptor rec.pdb --ligands a.pdb b.pdb \
    --swarms 5 --glowworms 10 --steps 20 --cores 4 --output-dir test/

# 从已有结果生成最优复合物
python scripts/generate_conformations.py --job-dir results/rec__lig/

# 汇总分数排名
python scripts/extract_scores.py --jobs-root results/ --output-dir scores/
```

## Workflow

1. **Locate the executables** — `resolve_executables()` finds `lightdock3_setup.py`
   and `lightdock3.py` by checking, in order: an explicit `--setup-exe` /
   `--run-exe` path, the current interpreter's `<prefix>/bin` (where conda and
   venv installs put them — **these are not on `PATH`**, which is why the old
   scripts hard-coded an absolute path), and finally the system `PATH`.
2. **Setup stage** — `lightdock3_setup.py` copies both structures into the job
   directory, strips waters/oxygens/hydrogens per the flags, computes the
   minimum-volume ellipsoid of the receptor, places the swarms on its surface,
   and writes `setup.json`. Critically, it **translates both structures to the
   origin** and saves them as `lightdock_receptor.pdb` / `lightdock_ligand.pdb`.
3. **Simulation** — `lightdock3.py setup.json <steps> -c <cores>` runs the glowworm
   swarm optimisation. Each swarm writes `gso_<step>.out` every 10 steps.
4. **Score extraction** — `collect_swarm_results()` picks the **highest-step**
   `gso_*.out` per swarm by numeric step, parses every glowworm line, and finds
   the minimum-scoring entry. **Lower DFIRE score is better.**
5. **Conformation generation** — `lgd_generate_conformations.py` writes
   `lightdock_<i>.pdb` files from the GSO coordinates, using the
   origin-shifted structures so receptor and ligand stay aligned.
6. **Reporting** — scores go to `docking_scores.csv` / `.json`, incrementally
   after every job.

## Parameters

### `run_docking.py`

| Parameter | Default | Description |
|---|---|---|
| `--receptor` | — | Single receptor PDB path |
| `--receptors` | — | Multiple receptor PDB paths (forms a grid with `--ligands`) |
| `--ligands` | required | Ligand PDB paths, glob patterns, or directories |
| `--output-dir` | `lightdock_results` | Output root |
| `--swarms` | `50` | Number of swarms (search space breadth) |
| `--glowworms` | `50` | Glowworms per swarm (sampling density) |
| `--steps` | `50` | Simulation steps |
| `--cores` | `4` | Parallel CPU cores |
| `--resume` | off | Skip jobs that already have a valid result |
| `--keep-hydrogens` / `--keep-oxt` / `--keep-water` | off | Keep stripped atoms |
| `--setup-timeout` | `600` | Setup stage timeout (seconds) |
| `--run-timeout` | `86400` | Simulation timeout (seconds) |
| `--setup-exe` / `--run-exe` | auto | Explicit paths to the LightDock scripts |

### `generate_conformations.py`

| Parameter | Default | Description |
|---|---|---|
| `--job-dir` | — | A single docking job directory |
| `--jobs-root` | — | Root whose subdirectories are treated as jobs |
| `--output-dir` | in-place | Where to copy the generated conformations |
| `--top` | `1` | How many conformations to generate (cost scales linearly) |
| `--ligand-chain` | — | Rewrite the ligand chain ID in a **copy** (original untouched) |
| `--conformations-exe` | auto | Explicit path to `lgd_generate_conformations.py` |

### `extract_scores.py`

| Parameter | Default | Description |
|---|---|---|
| `--job-dir` / `--jobs-root` | — | Which jobs to summarise |
| `--output-dir` | next to jobs | Where the score tables are written |
| `--per-swarm` | off | One row per swarm instead of one row per job |

## Outputs

| File | Content |
|---|---|
| `docking_scores.csv` | One row per job: job id, receptor, ligand, status, best score, best swarm, best glowworm |
| `docking_scores.json` | Same content as nested JSON |
| `conformations.csv` | Per job: chosen swarm, glowworm, score, generated PDB file names |
| `{job}/swarm_<n>/gso_<step>.out` | Raw glowworm swarm output |
| `{job}/swarm_<n>/lightdock_<i>.pdb` | Generated docked complex (receptor + ligand merged) |

## Validation

- **Score sign** — DFIRE scores are **negative and lower is better**. A positive
  "best score" usually means the parser picked the wrong column.
- **Score magnitude** — a converged small-complex DFIRE score typically lands
  around `-30` to `-60`. A score near `0` means the search barely moved from
  the random start.
- **glowworm index vs LigID** — the glowworm id is the **line number** in the
  GSO file. In single-structure docking, `RecID` and `LigID` are both `0`. If
  your report says "best glowworm = 0" for every job, the parser is reading the
  wrong field.
- **GSO step selection** — the file to use is the one with the **largest numeric
  step** (`gso_100.out` over `gso_20.out`), not the last one alphabetically.
- **Conformation count** — `lgd_generate_conformations.py` clips the requested
  count to the number of coordinate lines actually found, and says so in its log.
- **Complex sanity** — open the generated PDB and confirm the two parts touch
  but do not interpenetrate. A ligand flying off to the origin means the
  origin-shifted structures were not used.
- **RMSD** — LightDock does not report RMSD by default; run `lgd_rank.py` if you
  need it, or compare against a known holo structure.

## References

- `references/methodology.md` — GSO format semantics, coordinate-frame handling, score extraction, official command reference
- `references/troubleshooting.md` — common failures and how to diagnose them

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

Similar skills

All skills for Science and research →

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 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 molecular-dynamics molecular-dynamics is a Claude Code skill that analyses molecular dynamics trajectories and extracts structural descriptors. Runs when computing RMSD, RMSF, PCA, contacts, or clustering. CX Codex +1 ★ 77repo stars

Project sponsors

Companies that keep this analytics open