001tmf/blatant-why/by-epitope-analysis

Skill: BY Epitope Analysis

You are an expert structural biologist performing epitope analysis and hotspot residue selection for protein and antibody binder design. This skill covers interface identification, residue classification, hotspot scoring, druggability assessment, and producing residue selections for PXDesign or BoltzGen input.

When to Use This Skill

Use this skill when you need to:

• ✅ Convert a co-crystal structure into a hotspot residue list for PXDesign / BoltzGen
• ✅ Classify and score interface residues from a target+binder PDB entry
• ✅ Decide whether an epitope is concave/convex/flat and pick a design tool accordingly
• ✅ Assess druggability of an epitope for biologics
• ✅ Refine an epitope selection produced by by-research before committing to design

Don't use this skill for:

• ❌ Sequence-only target analysis with no structure → use by-research to find a structure first
• ❌ Picking PDB entries from a target name → use mcp__by-pdb__pdb_search directly
• ❌ Predicting structures from sequence → use Protenix (see protenix skill)
• ❌ Liability scanning (CDR loops, developability) → use by-screening

Quick Start

Run the hotspot selection script on a downloaded PDB with chain assignments:

python scripts/select_hotspots.py \
  --pdb /tmp/5JXE.cif \
  --target-chain A \
  --binder-chains H,L \
  --cutoff 5.0 \
  --top-n 6 \
  --out /tmp/hotspots.json

Expected output:

✓ Loaded structure 5JXE
✓ Interface residues detected: 18 (cutoff 5.0 A)
✓ Ranked 18 candidates; selected 6 hotspots
✓ Wrote /tmp/hotspots.json

The JSON contains a ranked list of {chain, resseq, resname, score, classification, rationale} plus a range_notation string ready to paste into BoltzGen entity YAML.

Installation

License Compliance: All packages permit commercial use in AI applications.

System requirements: No GPU. ~50 MB RAM per structure. Network only required if downloading PDB entries (the script accepts a local CIF/PDB path).

Inputs

Required:

• Structure file (CIF or PDB): co-crystal of target + binder
• Resolution < 3.0 A strongly preferred; flag entries > 3.5 A
• Single biological assembly (run pdb_get_chains to confirm chain labels)
• Target chain ID (e.g., A): the antigen
• Binder chain ID(s) (e.g., H,L for Fab, H for VHH): the existing binder

Alternative inputs:

• PDB ID (e.g., 5JXE): fetched via mcp__by-pdb__pdb_download before analysis
• Pre-computed interface JSON from mcp__by-pdb__pdb_interface_residues: skips

the structural pass and goes straight to scoring

Optional:

• Distance cutoff (default 5.0 A): see Decision Points
• Top-N (default 6): how many hotspots to return
• Exclude residues: glycosylation sites, mutation-sensitive positions

See references/hotspot-scoring.md for the full scoring rubric and threshold guidance.

Outputs

Primary results (written to --out path):

• hotspots.json:

``json { "pdb_id": "5JXE", "target_chain": "A", "binder_chains": ["H", "L"], "cutoff_a": 5.0, "interface_size_a2": 1080.0, "topology": "flat", "druggability": "moderate", "hotspots": [ {"chain": "A", "resseq": 56, "resname": "TYR", "score": 0.91, "classification": "polar_anchor", "rationale": "Aromatic + H-bond, buried at 4.0 A"} ], "range_notation": "A54,A56,A58,A61,A63,A68", "boltzgen_binding": "54,56,58,61,63,68", "pxdesign_hotspots": [54, 56, 58, 61, 63, 68] } ``

Reports:

• Console summary table (residue, score, classification, rationale)
• Topology + druggability classification with recommended design tool

Downstream-ready formats:

• boltzgen_binding string ready to drop into entity YAML binding: field
• pxdesign_hotspots int list ready for PXDesign target YAML

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST. Always confirm the user has a co-crystal structure or a justified single-chain target before proceeding.

1. Structure available? (ASK THIS FIRST)

• Do you have a co-crystal PDB ID, a local CIF/PDB file, or only a sequence?
• If sequence-only: route to by-research to find a structure first.

1. Target identity: Which chain is the antigen vs the binder? (We need both

labels — pdb_get_chains returns chain composition.)

1. Resolution check: Is the structure < 3.0 A? Cryo-EM acceptable above 3.0 A

only if the interface region is well-resolved. See references/interface-classification.md.

1. Design modality: PXDesign (de novo binder) vs BoltzGen (antibody/nanobody)?

This affects how many hotspots to recommend and whether to prefer concave epitopes.

1. Constraints: Any residues to exclude (e.g., known glycosylation sites,

essential function residues, prior mutational dead spots)?

1. Interface scope: Strict contacts only (4.0 A) or extended packing (6.0 A)?

Default 5.0 A balances both. See Decision Points.

1. Primary objective: Maximum specificity (more polar anchors) or maximum

binding energy (more hydrophobic core)? Defaults to 60% buried / 40% polar.

Standard Workflow

🚨 MANDATORY: USE THE PROVIDED SCRIPT — DO NOT WRITE INLINE BIOPYTHON CODE 🚨

This skill uses low-freedom script execution. You must:

• ✅ Run scripts/select_hotspots.py for the scoring + selection
• ✅ Use mcp__by-pdb__* for structure fetching and chain identification
• ❌ NOT write inline BioPython parsers — they will diverge from the scoring rubric

Step 1: Find and validate the structure

mcp__by-pdb__pdb_search(query="PD-L1 pembrolizumab complex", max_results=5)

Pick the entry with best resolution. Verify with:

mcp__by-pdb__pdb_get_chains(pdb_id="5JXE")

✅ VERIFICATION: Expected message lists target chain and binder chain(s) with sequence lengths matching the expected protein.

Step 2: Download the structure

mcp__by-pdb__pdb_download(pdb_id="5JXE", format="cif", output_dir="/tmp")

✅ VERIFICATION: Expect /tmp/5JXE.cif exists.

Step 3: Detect the interface (two cutoffs)

mcp__by-pdb__pdb_interface_residues(pdb_id="5JXE", chain1="A", chain2="H", distance_cutoff=5.0)
mcp__by-pdb__pdb_interface_residues(pdb_id="5JXE", chain1="A", chain2="H", distance_cutoff=4.0)

Residues present at both cutoffs are the buried core.

Step 4: Run hotspot selection

python scripts/select_hotspots.py \
  --pdb /tmp/5JXE.cif \
  --target-chain A \
  --binder-chains H,L \
  --cutoff 5.0 \
  --top-n 6 \
  --out /tmp/5JXE_hotspots.json

✅ VERIFICATION: Console prints ✓ Wrote /tmp/5JXE_hotspots.json with the selected residues and topology.

Step 5: Feed hotspots into the design tool

For PXDesign (see pxdesign skill for full YAML):

target:
  file: /tmp/5JXE.cif
  chains:
    A:
      hotspots: [54, 56, 58, 61, 63, 68]

For BoltzGen (see boltzgen skill for full entities spec):

entities:
- file:
    path: /tmp/5JXE.cif
    include:
    - chain: {id: A}
    binding_types:
    - chain: {id: A, binding: "54,56,58,61,63,68"}

⚠️ CRITICAL — DO NOT:

• ❌ Pass author_seq_id (sometimes called auth_seq_id) when the design tool

expects label_seq_id. The script outputs label_seq_id — match this.

• ❌ Skip the dual-cutoff step. Single-cutoff selection picks rim residues.
• ❌ Use cryo-EM entries > 4.0 A for hotspot selection without manual review.

When Scripts Fail

Follow the Script Failure Hierarchy when something breaks:

1. Fix and Retry (90%) — Install BioPython: pip install biopython. Confirm

the CIF path exists. Confirm chain IDs are present in the file.

1. Modify Script (5%) — If the structure has unusual chain naming

(e.g., AAA instead of A), edit scripts/select_hotspots.py to relax the chain-label assertion.

1. Use as Reference (4%) — Read the script logic, replicate the scoring in

a notebook for one-off non-standard structures (NMR ensembles, multi-model).

1. Write from Scratch (1%) — Only for genuinely novel formats (e.g.,

AlphaFold Multimer JSON with no PDB output). Document why in a comment.

Decision tree: Missing package? → Step 1. Script raises KeyError on chain? → Step 2. Unusual structure format? → Step 3. No PDB-like file at all? → Step 4.

Decision Points

Distance cutoff

Start at 5.0 A. If contact count < 20, widen to 6.0 A. If > 200, tighten to 4.0 A. Always run at both 5.0 A and 4.0 A — residues present at both are the buried core.

Hotspot count by interface size

Design tool by topology

See references/interface-classification.md for the full topology decision tree.

Common Issues