How to use the ESM protein models agent skill

What the ESM skill makes the agent do

An agent skill is a folder with a SKILL.md instruction file and optional helper scripts and reference notes. When a task matches the skill's description, the agent reads these instructions and follows them while it works. This skill covers the Biohub esm Python package, which the source describes as covering ESM3 protein generation, ESMC embeddings and ESMFold2 all-atom folding.

It also explains how to choose between local model weights and Biohub hosted services, and it warns against mixing the package with the older fair-esm distribution. A bundled helper script, scripts/esm_embeddings.py, pools per-residue embeddings into one vector per sequence.

• ESM3: masked multimodal generation, for example filling in missing positions of a sequence
• ESMC: sequence representations (embeddings) returned as numerical vectors
• ESMFold2: all-atom structure prediction returned as a molecular complex, saved as mmCIF
• Helper: embed_sequences, which returns one vector per input sequence in input order

What you need before you start

The skill's source lists these requirements. Check them before you ask the agent to run anything, because local model inference is the most demanding part.

• Python 3.12 or newer, with the esm Python package installed in an isolated environment
• Local model weights downloaded for local inference, or network access for hosted inference
• An ESM_API_KEY environment variable and a Biohub account for hosted inference
• Substantial RAM or GPU memory for local models; the source notes that ESMC 6B is large
• Keep this environment separate from any fair-esm installation

Install the skill from ZIP or the Claude apps

Option one is a personal install. Download the ZIP for this skill from this page and unzip it into ~/.claude/skills/ so the skill folder sits there. Option two is a project install: unzip it into the .claude/skills/ folder inside your project so only that project uses it.

Option three is the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the skill there. Whichever route you use, start a new session afterwards so the agent can see the skill.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Set up the Python environment

The skill's setup instructions create a dedicated virtual environment with uv and install the esm package into it. Ask the agent to follow these steps, or run them yourself in a terminal from the folder you want to work in.

The source notes that Linux x86_64 installs include GPU-specific dependencies, and that Flash Attention is optional. Do not install this stack into a shared environment that has conflicting Torch or Transformers pins.

Choose local models or hosted Biohub services

Local inference loads model weights onto your machine. Hosted inference sends your input to Biohub and needs an account and an API key. The skill's table maps each task to both options.

For ESM3, the local checkpoint is esm3-sm-open-v1 and the hosted client uses an ID such as esm3-medium-2024-08. For ESMC, local checkpoints include biohub/ESMC-300M, biohub/ESMC-600M and biohub/ESMC-6B. For ESMFold2, the local model is biohub/ESMFold2 and the hosted client is esmfold2-fast-2026-05.

For hosted calls, create a key in the Biohub developer console at biohub.ai and store it in the ESM_API_KEY environment variable. The skill reads that variable explicitly when it creates the client, so you should set it before starting the agent.

• Use local weights when you need to run offline or control the hardware
• Use hosted clients when you lack the memory for large models and have an account
• A larger model does not guarantee better results on your particular assay

How to trigger the skill with natural requests

You do not need special syntax. Describe the protein task in plain language and name the thing you want back: a completed sequence, an embedding vector, or a predicted structure file. The agent should match the request to this skill when the task involves the esm package, ESM3, ESMC or ESMFold2.

Include the sequence or a file path, say whether it is a single chain, and say whether you want local or hosted inference. If you are migrating older code, say so, because the skill has specific guidance on the difference from fair-esm.

• Example: Fill in the masked positions of this sequence with ESM3 and tell me the result.
• Example: Compute ESMC embeddings for these sequences and give me one vector per sequence.
• Example: Predict the structure of this chain with ESMFold2 and save it as an mmCIF file.
• Example: Move this old fair-esm ESM2 script to the Biohub esm package.

Example workflows and code

The skill's examples are illustrative. The source says the ESM3 example was not run against weights or hosted jobs in its refresh, and the toy sequence is for API mechanics only, not a functional design. The embedding example pools per-residue outputs and excludes special and padding tokens, so the result has one row per sequence.

Note that the ESMC output includes start, end and padding positions, so the number of positions is not the raw residue count. The helper script handles this for you.

• ESM3 completion: masked positions use the underscore character; the agent checks that the length and fixed residues are preserved
• ESMC embeddings: the helper returns a CPU feature array in input order and does not download weights or contact a service
• ESMFold2 folding: hosted calls return a complex that you can write with to_mmcif

Safety notes: scripts and network use

This skill runs scripts and uses the network. The bundled helper script runs Python code on your machine when the agent executes it. Read the script before you let an agent run it in an environment with sensitive files.

Hosted inference sends your sequences to Biohub. Do not send unpublished or confidential sequences to a hosted service unless your organisation allows it. The skill also says to reject accidental gaps, FASTA headers or stray characters in plain sequences instead of silently deleting them, and to check every SDK result for errors.

• Runs scripts: yes, including scripts/esm_embeddings.py
• Uses network: yes, for hosted clients and the Biohub developer console
• Keep API keys in environment variables, not in files you share
• Treat outputs as model predictions, not lab results

Tips for better results

Keep the ESM environment separate from fair-esm, because both packages import as esm. Record the model name, settings, random seed and input identifiers with every output, so you can reproduce the run later. Use finite request timeouts and limit concurrency when calling hosted services.

Validate outputs before you rely on them. Check sequence length, fixed residues, embedding shape and, for structures, chain mapping and confidence. Keep predictions separate from experimental validation.

• Pass the ESM_API_KEY explicitly and set it before starting the agent
• Batch embeddings by sequence length and available memory
• Ask the agent to name the model checkpoint it used in its answer
• Do not reuse cached results across different model or generation settings