esmc
Skill2 starsChanged 7 months agoMITView on GitHub
Skill for efficient protein embeddings using ESM-C (ESM Cambrian) from EvolutionaryScale. Use this skill whenever a user wants to generate protein embeddings or representations, compute sequence similarities, run protein classification or regression from embeddings, cluster proteins, build a sequence similarity index, or use embeddings as features for downstream ML tasks. ESM-C is ~3× faster than ESM2 with better embedding quality — prefer it over ESM2 when embeddings are the main goal and the esm package is available. Also trigger when the user mentions ESM-C, ESM Cambrian, esmc-300m, esmc-600m, esmc-6b, or wants fast protein representations.
- Installs packages
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Use ESM-C when embeddings are the primary goal — it's faster and produces better representations
- Very specific: line 20
Use ESM2 when you also need variant effect scoring (EsmForMaskedLM), contact prediction, or ESMFold structure prediction — those …
- Very specific: line 38
Start with esmc-600m; drop to esmc-300m for real-time or CPU applications.
- Distinctive: line 103
Use embeddings as features with sklearn (no fine-tuning needed):
- Distinctive: line 163
L2-normalize: before computing cosine similarity or building a FAISS index
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ESM-C: Efficient Protein Embeddings
Overview
ESM-C (Cambrian) is EvolutionaryScale's embedding-focused protein language model family, designed as a drop-in upgrade to ESM2 with ~3× faster inference and improved embedding quality across all model sizes.
Choosing between ESM-C and ESM2:
- Use ESM-C when embeddings are the primary goal — it's faster and produces better representations
- Use ESM2 when you also need variant effect scoring (
EsmForMaskedLM), contact prediction, or ESMFold structure prediction — those capabilities are not available in ESM-C
Installation
pip install esmESM-C models are also available on HuggingFace (evolutionaryscale/esmc-300m-2024-12, esmc-600m-2024-12) if you prefer the transformers ecosystem.
Model Selection
| Model | Params | Layers | Hidden dim | Use case |
esmc-300m | 300M | 30 | 960 | Fast inference, large batches, CPU-friendly |
esmc-600m | 600M | 36 | 1152 | Default — good quality/speed balance |
esmc-6b | 6B | 80 | 2560 | Maximum quality for downstream tasks |
Start with esmc-600m; drop to esmc-300m for real-time or CPU applications.
Core Usage
Basic Embeddings
from esm.models.esmc import ESMC
from esm.sdk.api import ESMProtein
import torch
import torch.nn.functional as F
model = ESMC.from_pretrained("esmc-600m").to("cuda")
model.eval()
sequence = "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGD"
protein = ESMProtein(sequence=sequence)
output = model.forward(model.encode(protein))
# output.embeddings: (1, seq_len, hidden_dim) — residues only, no special tokens to strip
per_residue = output.embeddings[0] # (L, 1152)
per_sequence = per_residue.mean(dim=0) # (1152,)
per_sequence_norm = F.normalize(per_sequence.unsqueeze(0), dim=-1) # L2 normalizedKey difference from ESM2: there are no [CLS]/[EOS] special tokens to strip. output.embeddings[0] is already residue-only.
Batch Processing
ESM-C processes sequences individually via encode → forward. Wrap in a helper for batches:
def get_embeddings(model, sequences):
"""Mean-pooled per-sequence embeddings for a list of sequences."""
embeddings = []
for seq in sequences:
protein = ESMProtein(sequence=seq)
output = model.forward(model.encode(protein))
emb = output.embeddings[0].mean(dim=0).detach().float()
embeddings.append(emb)
return torch.stack(embeddings) # (N, hidden_dim)For large datasets, see scripts/embed.py for an optimized batching loop with GPU cache management.
Common Tasks
Similarity Search
import torch.nn.functional as F
# Build a normalized embedding matrix for a database
db_embeddings = F.normalize(get_embeddings(model, db_sequences), dim=-1) # (N, D)
# Query
query_emb = F.normalize(get_embeddings(model, [query_seq]), dim=-1) # (1, D)
scores = (query_emb @ db_embeddings.T)[0] # cosine similarities
top_hits = scores.topk(10)For large-scale search (>10k sequences), use FAISS — see references/esmc-api.md.
Classification / Regression
Use embeddings as features with sklearn (no fine-tuning needed):
from sklearn.linear_model import LogisticRegression
X = get_embeddings(model, train_sequences).numpy()
clf = LogisticRegression(max_iter=1000)
clf.fit(X, train_labels)Or fine-tune ESM-C end-to-end with a task-specific head:
import torch.nn as nn
class ProteinClassifier(nn.Module):
def __init__(self, esm_model, hidden_dim, num_labels):
super().__init__()
self.esm = esm_model
self.head = nn.Linear(hidden_dim, num_labels)
def forward(self, sequences):
embs = []
for seq in sequences:
protein = ESMProtein(sequence=seq)
out = self.esm.forward(self.esm.encode(protein))
embs.append(out.embeddings[0].mean(0))
return self.head(torch.stack(embs))Comparison with ESM2
| ESM2-650M | ESM-C 600M | |
| Package | transformers | esm SDK |
| Inference speed | 1× | ~3× faster |
| Hidden dim | 1280 | 1152 |
| Special tokens | strip [CLS] and [EOS] | none to strip |
| Variant scoring | yes (EsmForMaskedLM) | no |
| Contact prediction | yes (via fair-esm) | no |
| ESMFold | yes | no |
| Embedding quality | good | better |
Scripts
scripts/embed.py — CLI for batch embedding from FASTA:
# Embed a FASTA file, save as numpy
python scripts/embed.py proteins.fasta --output embeddings.npy
# Save as HDF5 (one dataset per sequence ID), L2-normalized
python scripts/embed.py proteins.fasta --output embeddings.h5 --normalize
# Use a different model
python scripts/embed.py proteins.fasta --output embeddings.npy --model esmc-300mBest Practices
- L2-normalize before computing cosine similarity or building a FAISS index
- Cache embeddings for datasets you'll query repeatedly
- Half precision (
model.half()) reduces GPU memory by ~50% with minimal quality loss - Sequences > 1024 residues must be truncated or chunked
- For very large batches, clear GPU cache periodically:
torch.cuda.empty_cache()
Resources
- Blog: https://www.evolutionaryscale.ai/blog/esm-cambrian
- GitHub: https://github.com/evolutionaryscale/esm
- HuggingFace:
evolutionaryscale/esmc-300m-2024-12,evolutionaryscale/esmc-600m-2024-12
References
references/esmc-api.md— batch processing patterns, FAISS integration, fine-tuning, embedding caching, per-residue analysis, attention visualization
In this repository14 other files it gives its agents.
- alphafold3Skill
- alphafoldSkill
- boltzSkill
- chai1Skill
- diffdockSkill
- esm2Skill
- esm3Skill
- evo2Skill
- prostt5Skill
- proteinmpnnSkill
- prott5Skill
- rfdiffusionSkill
- rnafmSkill
- scgptSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

