Skip to main content
skill CX Codex

ml-peptide-generation — Claude Code skill for peptide design

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.

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 ml-peptide-generation -a claude-code
Open on GitHub

What ml-peptide-generation does

The skill uses the PepMLM-650M language model to generate peptide candidates: it appends mask tokens to a target protein sequence, then samples an amino acid at each masked position. Outputs include pseudo-perplexity and a validity flag. An explicit seed makes a run reproducible, and X, B, and Z are excluded from sampling.

Targets can come from a FASTA file, a CSV with id and seq columns, or a single sequence. Generation requires Python 3.9+, torch, and transformers. A separate script filters candidates and summarizes parameter sweeps; it uses only the Python standard library and does not need a GPU.

Pseudo-perplexity reflects the model’s own score, not binding affinity. Binding claims need experimental or independent computational validation. The skill rejects target sequences longer than 552 tokens.

What it helps with

  • generate a ranked peptide candidate pool for a target protein
  • compare candidate sets across peptide lengths and top-k values
  • filter results by pseudo-perplexity and peptide length
  • rerun generation with a fixed random seed

Example prompts for the agent

  • Generate peptide candidates from targets.fasta and save the results in results/.
  • Compare candidates for peptide lengths 10, 12, and 15 across top-k settings.
  • Filter results/peptides.csv by pseudo-perplexity and summarize the parameter results.

How to install ml-peptide-generation

1Skills CLI (Vercel)

npx skills add ssinder/bioinformatics-agent-skills --skill ml-peptide-generation -a claude-code

2Manually: put the files in place

~/.claude/skills/ml-peptide-generation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ml-peptide-generation/

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

Questions about ml-peptide-generation

How do I install ml-peptide-generation in Claude Code?

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

What does ml-peptide-generation do?

It uses PepMLM-650M to generate peptide candidates for a target protein, score them by pseudo-perplexity, and filter the results. That score does not establish that a peptide binds the target.

What does ml-peptide-generation need to run?

Generation requires Python 3.9+, torch, and transformers. The analysis script uses Python’s standard library and does not need a GPU.

Source text

SKILL.md · MIT
---
name: ml-peptide-generation
description: >-
  Generates candidate binder peptides for a target protein using the PepMLM-650M
  masked language model — appends <mask> tokens to the target sequence and
  samples amino acids at each position, with illegal residues (X, B, Z)
  excluded from the sampling candidates. Reports pseudo-perplexity for each
  candidate, supports reproducible generation via an explicit random seed,
  and provides offline filtering and parameter-sweep analysis that needs no GPU.
  This skill should be used when designing peptides or protein fragments that
  should bind a target, generating a ranked candidate pool for a target
  sequence, or comparing how peptide length and top-k sampling settings affect
  candidate quality.
license: MIT
compatibility: Python 3.9+; generation needs torch + transformers; analysis needs only the standard library
metadata:
  version: "1.0"
  last-reviewed: "2026-10-26"
  skill-author: sinder
---

# ML Peptide Generation

## Overview

This skill generates candidate binder peptides for a target protein with
**PepMLM-650M**, a masked language model trained on protein sequences.

The mechanism is straightforward: append N `<mask>` tokens to the target
sequence, ask the model for its amino-acid distribution at each masked
position, and sample from it. Repeating that for N positions produces an
N-residue peptide.

Two things this skill does that a naive implementation does not:

- **Reproducible by construction.** Every run takes an explicit `--seed`.
  The same seed and the same input always produce the same peptides, so a
  parameter sweep is a controlled experiment rather than a lottery.
- **Illegal residues are excluded at sampling time, not afterwards.** The
  model's vocabulary contains `X` (unknown), `B` and `Z` (ambiguous amino
  acids). Sampling from the raw vocabulary produces peptides that are not
  chemically meaningful. Here those candidates are removed *before* the
  draw, so the sampling budget is not wasted on rejects.

## When to Use This Skill

- Designing a peptide or protein fragment intended to bind a target protein
- Producing a ranked candidate pool for a set of targets
- Comparing peptide lengths (10 / 12 / 15 aa) or top-k settings
- Screening candidates before committing to synthesis or wet-lab validation

## Quick Start

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

# 生成(需要 torch + transformers)
python scripts/generate_peptides.py \
    --input-fasta targets.fasta \
    --output-dir results/ \
    --peptide-lengths 10,12,15 \
    --num-binders 20 \
    --seed 42

# 分析(只用标准库,无需 GPU)
python scripts/analyze_peptides.py \
    --input results/peptides.csv \
    --output-dir analysis/ \
    --max-ppl 5.0
```

## Workflow

1. **Collect targets** — `--input-fasta` (FASTA), `--input-csv` (needs `id`
   and `seq` columns) or `--input-seq` (a single sequence).
2. **Set the seed** — `--seed` fixes `random`, `numpy` and `torch`. The seed
   is written into every output row so a run can be reproduced later.
3. **Generate** — for each target × peptide length × top-k combination,
   sample `--num-binders` peptides and score each by pseudo-perplexity.
4. **Analyse** — `analyze_peptides.py` filters invalid peptides, applies
   optional PPL/length thresholds, and reports per-configuration statistics.
5. **Select** — rank by pseudo-perplexity and carry the top candidates into
   downstream validation.

## Parameters

### `generate_peptides.py`

| Parameter | Default | Description |
|---|---|---|
| `--input-fasta` | — | Target protein FASTA file |
| `--input-csv` | — | Target CSV file (needs `id` and `seq` columns) |
| `--input-seq` | — | A single target sequence |
| `--output-dir` | `peptide_results` | Output directory |
| `--per-target-dir` | off | Also write one CSV per target |
| `--peptide-lengths` | `10,12,15` | Peptide lengths to generate |
| `--top-ks` | `3` | Top-k values to sweep |
| `--num-binders` | `10` | Peptides per (target × length × top-k) |
| `--seed` | `42` | Random seed — same seed, same results |
| `--model` | `TianlaiChen/PepMLM-650M` | Pretrained model |
| `--device` | auto | Force `cuda` or `cpu` |
| `--allow-invalid-amino-acids` | off | Allow sampling `X`/`B`/`Z` |

### `analyze_peptides.py`

| Parameter | Default | Description |
|---|---|---|
| `--input` | required | One or more result CSV files |
| `--output-dir` | `peptide_analysis` | Output directory |
| `--max-ppl` | none | Keep only peptides with PPL ≤ this value |
| `--min-length` / `--max-length` | none | Peptide length bounds |
| `--keep-invalid` | off | Keep peptides containing non-standard residues |
| `--top-n` | `20` | How many to print |

## Outputs

| File | Content |
|---|---|
| `peptides.csv` | All candidates: rank, target, length, top-k, binder, pseudo-perplexity, validity flag, seed |
| `peptides.json` | Same content as JSON |
| `filtered_peptides.csv` | Candidates passing the filters, sorted by PPL |
| `parameter_analysis.csv` / `.json` | Per-configuration totals, mean/median/min/max PPL |

## Validation

- **Pseudo-perplexity measures the model's own belief, not binding affinity.**
  A low PPL means "this looks like a peptide the model would have generated",
  not "this binds the target". It is a triage filter for wet-lab follow-up,
  nothing more. Any claim about affinity needs an experimental or
  orthogonal computational check.
- **PPL is only comparable within one (target, length) pair.** The scale
  depends on the target sequence; do not compare PPL across different
  targets and conclude one target is "easier".
- **Check the validity flag.** `has_unknown_aa=True` means the peptide
  contains a residue the model could not decide on — such a peptide is not
  a real design. The skill excludes these at sampling time, but the flag
  stays in the output so the filter can be audited.
- **Verify reproducibility.** Re-run with the same `--seed` and diff
  `peptides.csv`; the files must be byte-identical apart from the
  `generated_at` timestamp.
- **Peptides shorter than about 8 residues rarely bind meaningfully.** Use
  `--min-length` to exclude them from a synthesis list.
- **The model truncates at 552 tokens.** Target sequences longer than that
  are rejected by the skill rather than silently truncated — a truncated
  target produces peptides for the wrong protein.

## References

- `references/methodology.md` — PepMLM mechanism, pseudo-perplexity derivation, sampling strategy
- `references/troubleshooting.md` — common failures and how to diagnose them
- Model card: <https://huggingface.co/TianlaiChen/PepMLM-650M>
- E-utilities context for target discovery: the `bioproject-search` skill

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

Similar skills

All skills for AI and ML →

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 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 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