Sentence Transformers Training Assistant
Train retrieval, similarity, reranking, and sparse-search models with Sentence Transformers.
The skill makes HF_TOKEN use, write-scoped authentication, and default public Hub publishing visible, so its external data and publication flow is not concealed. It does not require confirmation before publication, define least-privilege handling, address sensitive training data, or provide rollback and pre-publication checks, so points are deducted.
The routing, loss/data-shape mappings, evaluator key conventions, smoke-test requirement, logging, and troubleshooting guidance are fairly consistent and document several incompatibilities. However, the referenced production templates and scripts are not included in the supplied evidence, and there is no statically verifiable key-path test coverage, so the score is limited and deductions apply.
The skill covers three model types and gives trigger phrases, task mappings, and non-English model-selection hints. Its claim to cover any sentence-transformers training task is broad, while non-fit boundaries, Chinese-language quality, and mainland-China network reachability are not sufficiently established, especially for Hub and Jobs dependencies.
The router-plus-references/scripts structure is readable and provides prerequisites, examples, defaults, limitations, and troubleshooting. The selected skill does not clearly state maintenance ownership, versioning policy, changelog, or update path, and its core templates are absent from the supplied evidence, so points are deducted.
The guidance addresses loss selection, evaluation, hard-negative mining, smoke tests, logging, and Hub publication and could reduce manual trial and error. Still, usable execution depends on production templates, scripts, and additional references not supplied here, with no verifiable representative outputs; direct usability and comparative benefit therefore remain limited.
The material contains concrete commands, parameters, metric keys, and failure modes, providing limited auditability. This review is static only, with no execution results, committed key-path test suite, or third-party reproduction evidence, and several critical referenced files are missing, so a higher score is not justified.
- The default workflow publicly pushes the model to the Hugging Face Hub and requires a write-capable token; manually confirm the destination, token scope, and publication policy for private or sensitive data.
- The skill depends on Hugging Face Hub, remote model and dataset downloads, and optionally HF Jobs; mainland-China connectivity, proxy, rate-limit, or credential failures may prevent the core workflow from completing.
- Do not generate a training script from this SKILL.md alone; verify the referenced production template, complete reference set, and installed sentence-transformers version.
- No code or tests were executed; reliability, effectiveness, and evidence scores are conservative static estimates.
What does this skill do, and when should you use it?
This skill guides agents through training or fine-tuning SentenceTransformer, CrossEncoder, and SparseEncoder models. It covers loss selection, dataset formats, evaluators, hard-negative mining, distillation, LoRA, Matryoshka training, and Hugging Face Hub publishing. The SKILL.md acts primarily as a router; the detailed procedures live in the referenced files and scripts. It is a good fit for structured, repeatable embedding and reranker training, but the file should not be used alone to synthesize a training script.
It identifies the appropriate bi-encoder, cross-encoder, or SPLADE sparse-encoder path; requires the relevant loss, evaluator, architecture, training-argument, dataset, model-selection, and troubleshooting references; starts from scripts/train_<type>_example.py; substitutes the model, dataset, loss, and evaluator; runs a max_steps=1 smoke test before a longer run; records logs and baseline-versus-final metrics; and attempts to publish the trained model to the Hugging Face Hub.
- A retrieval team fine-tuning a SentenceTransformer for vector search or semantic similarity.
- A search engineer adding a CrossEncoder reranker after bi-encoder retrieval.
- A team training SPLADE-style sparse embeddings for inverted-index retrieval.
- A researcher improving an embedding model with hard-negative mining, distillation, LoRA, or Matryoshka training.
- An ML engineering team that needs smoke tests, baseline metrics, verdict logging, and reproducible training scaffolding.
What are this skill's strengths and limitations?
- Covers dense bi-encoders, CrossEncoder rerankers, and SPLADE sparse encoders.
- Provides a structured reading path for losses, evaluators, datasets, hardware, and troubleshooting.
- Requires production templates, smoke tests, baseline metrics, and a machine-readable verdict line.
- Includes workflows for LoRA, distillation, Matryoshka training, hard-negative mining, and Hub publishing.
- The SKILL.md is a router, so the complete training guidance is distributed across references and scripts.
- A GPU is strongly recommended; CPU use is limited to demos and StaticEmbedding scenarios.
- The source provides no test-suite results, platform-specific validation, or concrete hardware benchmarks.
- Hub publishing requires write authentication, and HF Jobs runs require additional configuration guidance.
How do you install this skill?
Copy or symlink the skills/train-sentence-transformers/ folder into a standard Codex .agents/skills location, such as $REPO_ROOT/.agents/skills or $HOME/.agents/skills. Install the training dependency with: pip install "sentence-transformers[train]>=5.0". To publish models, run hf auth login or set an HF_TOKEN with write scope.
How do you use this skill?
After installation, give the coding agent a specific request such as: "Use SentenceTransformer to train a semantic retrieval model on my question-answer dataset, and run a max_steps=1 smoke test first." If the model type is unclear, identify whether the task needs a bi-encoder, cross-encoder, or sparse encoder. The detailed parameters and template behavior are defined in the referenced files under references/ and scripts/.