Guide · Agent skill
How to use the Train Sentence-Transformers Models agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The train-sentence-transformers skill is a set of instructions and reference files that lets an AI agent train or fine-tune sentence-transformers models for search, similarity and retrieval. It is aimed at machine learning engineers who want an embedding model tuned on their own data, and at developers who want to publish the result to the Hugging Face Hub. After this guide you will know what the skill changes, how to install it, how to phrase a request so it triggers, and what hardware and accounts you need before a run.
Train Sentence-Transformers Modelshuggingface/skills · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. You should end up with a train-sentence-transformers folder containing SKILL.md and a references folder.
- 2Place it where your agent looks. Copy the folder into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder. In the Claude apps, upload it under Settings, Capabilities, Skills instead.
- 3Prepare Python and PyTorch. Install Python with the sentence-transformers library and PyTorch. Check that a GPU is available for training if you have one.
- 4Describe your training task. State your goal, the model type if known, your data and the output you want, such as a score before and after training.
- 5Review the generated script. The agent writes a Python training script from the maintainers' template. Read it for the dataset path, base model and any Hub push before running.
- 6Run and read the VERDICT line. Run the script. When it finishes, check the final VERDICT line for WIN, MARGINAL or REGRESSION along with the score, baseline and delta.
What an agent skill is and what this one does
An agent skill is a folder of instructions and supporting files that an AI agent loads when a task matches it. This skill covers training for four model types from the sentence-transformers library: SentenceTransformer (bi-encoder embedding models), CrossEncoder (rerankers that score query and passage pairs together), SparseEncoder (SPLADE learned-sparse models) and MultiVectorEncoder (ColBERT-style per-token models scored with MaxSim).
The skill works as a router. Its SKILL.md tells the agent which model type fits the task and which reference files to read on losses, evaluators, datasets and hardware. It also points the agent at an example training script to copy. The skill tells the agent not to write training code from memory, so the generated scripts follow the maintainers' patterns. The output is Python code that you must run and check yourself.
Install the skill (ZIP download or Claude apps)
Download the ZIP of the skill from this page and unzip it. Then place the folder in one of these locations, depending on how you want it available:
For all of your projects, put it in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder.
Alternatively, in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal use across projects: ~/.claude/skills/
- One project only: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Check what you need before you start
The skill itself is only instructions. The actual training needs a working environment. The skill expects Python with the sentence-transformers library and PyTorch installed. A GPU is strongly recommended for training. If you want to push models to the Hugging Face Hub or run jobs on HF Jobs, you need a Hugging Face account and a token.
Smaller experiments may run on local hardware. The skill's default is to train locally and only suggest HF Jobs when your local hardware cannot fit the job. HF Jobs usage and large GPUs cost money.
- Python with sentence-transformers and PyTorch
- A GPU, strongly recommended for training
- Hugging Face account and token for Hub publishing or HF Jobs
Trigger the skill with a natural request
You do not need a special command. Describe the training task in plain language and mention the model type if you know it. The skill's tie-break rules map common words to model types: embedding model, vector search or similarity point to a bi-encoder; rerank, ranker or two-stage points to a cross-encoder; SPLADE, sparse or inverted index points to a sparse encoder; ColBERT, late interaction or MaxSim points to a multi-vector encoder. If the request is still unclear, the agent is told to ask.
Good requests name the goal, the data and the output you want. For example, say what pairs or triplets you have and whether you want the model published to the Hub.
- "Fine-tune an embedding model on my support tickets for semantic search and tell me the score before and after training."
- "Train a reranker that rescores the top 100 results from my bi-encoder."
- "Train a SPLADE model for Elasticsearch on my product catalogue."
- "Fine-tune a ColBERT model on my legal documents with MaxSim scoring."
What the agent does during a training run
The skill asks the agent to read the relevant reference files in full before writing code. These cover loss selection, evaluators, model architectures, dataset column rules, base model selection, troubleshooting and hardware. The agent then copies the matching production template script and adapts it.
Every produced script must capture a baseline evaluator score before training starts, and must print one final line in the form VERDICT: WIN, MARGINAL or REGRESSION with the score, baseline and delta. The default is a single run. The agent may propose further experiments afterwards if the result is weak or you ask for more.
- Reads the per-type references and the cross-cutting references such as training arguments and dataset formats
- Copies the matching example script rather than inventing one
- Records a baseline score before trainer.train() runs
- Ends with a VERDICT line you can check
Safety notes: scripts and network access
This skill runs scripts and uses the network. The generated training code will download base models and datasets, and it can push models to the Hugging Face Hub when you ask for that. HF Jobs runs use your account and cost money. Read the generated script before you run it, check which Hub account and token it will use, and confirm that the destination repository is the one you intend.
Use a token with only the permissions you need. Do not paste credentials into a request if you can avoid it.
- Review every generated script before running it
- Confirm the Hub repository name before any push
- Watch HF Jobs usage and costs
- Keep tokens out of shared prompts and logs
What people use it for
- Fine-tune a bi-encoder on your own domain data so semantic search finds the right internal documents.
- Train a cross-encoder reranker to reorder the top results from an existing retriever in a two-stage pipeline.
- Build a SPLADE sparse model for an inverted-index backend such as Elasticsearch or OpenSearch.
- Train a ColBERT-style multi-vector model for late-interaction retrieval where per-token matching matters.
- Publish a finished model to the Hugging Face Hub with a model card.
Frequently asked questions
Is the train-sentence-transformers skill free?
The skill's source is licensed under Apache-2.0, so you can use and modify it under those terms. Running training can still cost money, because a GPU or HF Jobs run may be billed. The skill itself does not state a price.
What do I need to use this skill?
You need Python with the sentence-transformers library and PyTorch, and a GPU is strongly recommended for training. A Hugging Face account and token are needed only if you push models to the Hub or run HF Jobs. Non-technical users should know the output is Python code that must be run and checked.
Where do I put the skill so Claude can use it?
Unzip the downloaded folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings, Capabilities, Skills.
Can I use this skill without training a model?
No. If you only want to use an existing embedding model for search, you do not need a training skill. The skill is for training or fine-tuning, and its reference files are long and mostly irrelevant to plain inference.
What is the difference between a bi-encoder and a cross-encoder in this skill?
A bi-encoder, the SentenceTransformer class, maps each text to a fixed-size vector so you can compare many texts quickly. A cross-encoder, the CrossEncoder class, scores a query and passage together, which is more accurate but slower, so it is usually used to rerank a shortlist.
My training run fails or the metrics do not improve. What should I check?
The skill includes a troubleshooting reference and asks the agent to skim its failure headings before each run. Check that your dataset columns match the loss, that the evaluator is set up correctly, and that any Hub token is valid. Share the error message and the VERDICT line with the agent so it can diagnose the problem.
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 an ML engineer or developer who wants an agent to set up a real sentence-transformers training run for bi-encoders, rerankers, SPLADE or ColBERT models, and who can run and review Python code. Pick something else if you only need to use an existing embedding model for search, or if you need a finished model without any code or GPU access.
Download the skill