# Train Sentence Transformers

> Guardrail for training sentence-transformers bi-encoders, cross-encoders, and sparse encoders with correct loss, evaluator, hard-negative, and publishing choices.

- Skill: `tim-osterhus/train-sentence-transformers` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tim-osterhus/train-sentence-transformers`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tim-osterhus/train-sentence-transformers/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tim-osterhus (https://skillmd.com/u/tim-osterhus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tim-osterhus/train-sentence-transformers

---


# Train Sentence Transformers

## Purpose
Help agents train or fine-tune sentence-transformers models for retrieval, similarity, reranking, learned sparse retrieval, clustering, classification, paraphrase mining, or deduplication.

## Quick Start
1. Identify model type: bi-encoder `SentenceTransformer`, `CrossEncoder` reranker, or `SparseEncoder`.
2. Match loss function to data shape.
3. Choose the evaluator that matches the task and primary metric.
4. Smoke-test with a tiny slice before long training.
5. Capture baseline score before training and emit an end-of-run verdict.
6. Push or publish only after validation.

## Operating Constraints
- Do not synthesize a training script from memory when production templates or examples exist.
- Do not train without baseline evaluation.
- Do not use cached losses with incompatible gradient-checkpointing settings.
- Do not use a reranker when first-pass recall is too weak.
- Do not publish models or cards containing private data.
- Keep run logs, seeds, model names, data versions, and primary metrics reproducible.

## Inputs This Skill Expects
- Task type and model class.
- Dataset shape: pairs, triplets, query-positive-negative, labels, rankings, or sparse targets.
- Base model, language/domain, hardware, and Hub policy.
- Evaluator and baseline metric.
- Hard-negative mining plan when relevant.

## Output Contract
- State model type, loss, evaluator, data shape, metric, and training command.
- Include smoke-test command and baseline evaluation.
- Report verdict: win, marginal, or regression.
- State publish, iterate, or reject decision with metric evidence.

## Procedure
1. Classify the model type from task wording.
2. Inspect dataset columns and labels.
3. Choose loss and evaluator from data shape and task.
4. Prepare training script/config from a known-good template.
5. Run smoke test.
6. Run training and log baseline plus final metrics.
7. Publish or archive artifacts only after the verdict is acceptable.

## Pitfalls And Gotchas
- Choosing a loss that silently mismatches columns or labels.
- Evaluating rerankers with first-pass retrieval metrics.
- Forgetting named-evaluator metric keys.
- Skipping hard-negative quality checks.
- Reporting high scores despite sparse dimension collapse.

## Progressive Disclosure
Start with model type and data shape. Expand into hard-negative mining, LoRA, Matryoshka, distillation, multilingual transfer, sparse regularization, or cloud execution only when the training objective needs it.

## Verification Pattern
- Confirm model type, loss, evaluator, and metric align.
- Confirm baseline evaluation ran before training.
- Confirm smoke test passed.
- Confirm final verdict compares baseline and trained model.
- Confirm publication respects privacy and artifact policy.