Skip to content
Get packs

Guide · Agent skill

How to use the DiffDock molecular docking agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The DiffDock skill teaches an AI agent to run DiffDock, a protein-small-molecule docking tool, so it can generate candidate ligand poses for a target and rank them by model confidence. It is aimed at computational chemists, structural biologists and students who need pose generation, not binding-affinity prediction. After this guide you will know how to install the skill, what the upstream DiffDock setup requires, how to phrase a request so the agent uses the skill, and how to read the outputs cautiously.

DiffDock Molecular DockingK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Install the skill. Download the ZIP and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
  2. 2Set up upstream DiffDock. Clone DiffDock at v1.1.3 and create the conda environment, or use its Docker image. Check that you have a CUDA GPU if you plan to use sequence inputs.
  3. 3Run the setup checker. From the DiffDock checkout, run the bundled setup_check.py using its absolute path to confirm imports and files are present.
  4. 4Prepare inputs. Provide a PDB receptor or complete sequence, and a SMILES or ligand file. Record identifiers and preparation choices.
  5. 5Run a single pair or batch. Run inference with a fresh output directory, using a CSV for batches after validating it with prepare_batch_csv.py.
  6. 6Analyse the poses. Use analyze_results.py to list top poses and export a summary, then interpret confidence cautiously.

What the DiffDock skill makes the agent do

Once installed, the agent knows how to set up the upstream DiffDock docking tool, prepare protein and ligand inputs, run single or batch predictions, and read the ranked poses and confidence scores. It also warns about common pitfalls, such as treating confidence as binding affinity or reusing output folders.

The skill itself does not run docking. It relies on a separate DiffDock installation (or Docker image) that must be set up first.

  • Predicts protein-small-molecule binding poses with DiffDock and DiffDock-L from a PDB file or a sequence, plus SMILES, SDF or MOL2 ligands.
  • Covers batch docking, pose triage, confidence interpretation and validation.
  • Intended for molecular docking and virtual-screening pose generation, not binding-affinity prediction.

Install the DiffDock skill

Download the ZIP from the skill page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to share it with one project. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The skill is MIT licensed. Its folder includes SKILL.md, scripts/ (analyze_results.py, prepare_batch_csv.py, setup_check.py), references/ and assets/ (batch_template.csv, custom_inference_config.yaml).

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/
  • Claude apps: Settings → Capabilities → Skills → upload

Set up the upstream DiffDock environment

The skill needs the upstream DiffDock v1.1.3 repository and its conda environment (Python 3.9.18, PyTorch 1.13.1, fair-esm 2.0.0, RDKit/PyG), or its Docker image. The upstream environment is heavy and pinned, and the published CUDA environment is not a macOS-native recipe. Do not substitute current torch or the unrelated PyPI esm package for fair-esm.

Network access and substantial disk space are needed for model weights (DiffDock, ESM2, and ESMFold for sequence inputs). PDB-based inference has a CPU path, but sequence folding requires a CUDA GPU. Record the Docker image digest, since the unversioned tag may not match the checked source.

  • Clone the repository at the v1.1.3 tag and create the conda environment from environment.yml.
  • Or pull the rbgcsail/diffdock Docker image and activate the diffdock environment inside it.
  • Run the bundled checker from the DiffDock checkout: python /path/to/diffdock-skill/scripts/setup_check.py. It checks imports and files, not whether models load successfully.
git clone --branch v1.1.3 --depth 1 https://github.com/gcorso/DiffDock.git cd DiffDock conda env create --file environment.yml conda activate diffdock

Ask the agent for docking in plain language

You do not need special syntax. Describe the target, the ligand and what you want back, and mention that you want candidate poses. The skill's description covers requests about molecular docking and virtual-screening pose generation.

Give the agent real prepared inputs where you can: a PDB file for the receptor or a complete amino-acid sequence, and a SMILES string or ligand file. The agent will then follow the skill's workflow for setup, input checks and running inference.

  • "Dock this ligand SMILES into my receptor PDB and show me the top 5 poses with confidence scores."
  • "Set up a batch docking run for these 20 ligands against protein.pdb and keep each run in its own output folder."
  • "Explain what the DiffDock confidence scores mean for these results before I rank anything."

Run a single pair

Run from the upstream repository root with prepared inputs. Use --ligand_description, the registered name, not the abbreviation --ligand. Use a fresh output directory for each run.

Output appears in a complex folder with ranked SDF files. rank1.sdf duplicates the top pose, and filename confidence is rounded to two decimals. Scores in the example are illustrative.

  • For sequence input, replace --protein_path with --protein_sequence and a full sequence. This adds ESMFold and CUDA requirements.
python -m inference \ --config default_inference_args.yaml \ --protein_path protein.pdb \ --ligand_description "CC(=O)Oc1ccccc1C(=O)O" \ --out_dir results/run_001/ \ --loglevel INFO

Run batch and ensemble jobs

Batch input is a CSV with the columns complex_name, protein_path, ligand_description and protein_sequence. Use unique explicit names. Paths resolve relative to the inference working directory, not the CSV's folder. If both are given, the protein path takes precedence over the sequence. Generate a template with the helper, replace the example rows, then validate before inference.

For an ensemble, give one row per receptor conformation with distinct names. Confidence across structures is not calibrated, so it cannot pick a preferred state.

  • Validation checks paths and SMILES, not PDB or file chemistry.
  • batch_size groups candidate poses within a complex; complexes are processed one after another.
  • Arbitrary user-complex inference has no --esm_embeddings_path or --chain_cutoff option.
python /path/to/diffdock-skill/scripts/prepare_batch_csv.py --create --output batch.csv python /path/to/diffdock-skill/scripts/prepare_batch_csv.py batch.csv --validate python -m inference --config default_inference_args.yaml \ --protein_ligand_csv batch.csv --out_dir results/batch_001/ --batch_size 10

Change sampling settings safely

In the upstream configuration, YAML values overwrite matching command-line values. Appending --samples_per_complex 20 to the default command still uses 10. Copy the bundled configuration and edit the existing values in the copy, then run with that file.

More steps or a higher torsion temperature do not guarantee better accuracy, so keep the released schedule unless you are testing a justified alternative.

  • Copy assets/custom_inference_config.yaml to a run folder and change samples_per_complex there.
  • Run with --config pointing to your edited copy.
cp /path/to/diffdock-skill/assets/custom_inference_config.yaml run_config.yaml

Inspect results and read confidence scores

The analysis helper deduplicates the rank1.sdf copy and flags runs where several scored files share one rank, which can indicate stale output. It inventories filenames but does not validate SDF chemistry.

Confidence is not a measured probability of correctness and not binding affinity. The upstream FAQ gives rough bands for top poses: above 0 is the highest, between -1.5 and 0 is moderate, and below -1.5 is low. These are not guarantees of pose correctness.

  • Summarise the top poses: python /path/to/diffdock-skill/scripts/analyze_results.py results/batch_001/ --top 5
  • Export a table: python /path/to/diffdock-skill/scripts/analyze_results.py results/batch_001/ --export poses.csv

Use good input hygiene

Record receptor and ligand identifiers, file hashes, preparation choices, software versions and intended stereochemistry. Decide explicitly how to handle missing atoms, waters, cofactors and metal coordination.

Do not silently trim a biological target to make a run pass. Upstream ESM2 truncates each chain at 1022 residues, and longer chains can cause mismatches.

  • Use a fresh output directory for every run.
  • Inputting an existing pose does not restrain docking; ligand coordinates are discarded and regenerated.
  • Supported ligand readers include .sdf, .mol2, .pdb and .pdbqt; SDF input uses its first record.

What people use it for

  • Generating candidate ligand poses for one protein target before manual inspection.
  • Running batch docking of a ligand library against a single prepared receptor, with traceable names.
  • Comparing poses across separate receptor conformations as an ensemble, while noting that confidence is not calibrated across structures.
  • Teaching how docking workflows and confidence scores work, using the skill's references.

Frequently asked questions

Is the DiffDock skill free to use?

The skill is released under the MIT licence. The upstream DiffDock tool and its model weights are separate components, and the skill's source does not state their prices, so check those projects' own terms.

Do I need a GPU to use DiffDock?

PDB-based inference has a CPU path in the upstream code. Sequence folding calls .cuda() unconditionally, so sequence inputs need a CUDA-capable GPU.

How do I install the DiffDock skill?

Download the ZIP from the skill page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.

Does the skill run docking by itself?

No. The skill guides the agent, but you must first install upstream DiffDock v1.1.3 with its conda environment or Docker image.

Can DiffDock predict binding affinity or rank drugs by potency?

No. The skill states that DiffDock confidence is not binding affinity and should not be used for hit identification on its own. Use it for pose generation and triage.

Why does my config change not take effect?

In the upstream setup, YAML values overwrite matching command-line arguments. Copy the configuration file, edit the existing key there, and run with that copy.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a computational chemist, structural biologist or student who needs candidate ligand poses for a protein target and can install a heavy, pinned DiffDock environment with a CUDA GPU. Pick another approach if you need binding-affinity estimates, potency ranking, or results for clinical or safety decisions, since docking output is an unvalidated computational guess.

Download the skill