How to use the Sentence Transformers agent skill: setup and examples

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions, and optionally reference files, that an AI agent loads when a task matches the skill's description. This skill is for the sentence-transformers library, a Python framework for sentence, text and image embeddings.

Once installed, the agent can write Python code that loads pre-trained models, compares how similar texts are, runs semantic search over a collection, fine-tunes a model, and plugs embeddings into LangChain or LlamaIndex pipelines. The models run locally rather than through a paid API.

• Load a pre-trained model such as all-MiniLM-L6-v2 and encode text into vectors
• Compute cosine similarity or dot product between embeddings
• Run semantic search over a corpus with util.semantic_search
• Fine-tune a model on your own labelled sentence pairs
• Connect embeddings to LangChain (Chroma) or LlamaIndex

Install the Sentence Transformers skill

Download the skill ZIP from this page and unzip it. For a personal setup, place the unzipped sentence-transformers folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/sentence-transformers/
• Project: .claude/skills/sentence-transformers/ inside your project

Install the Python package the skill relies on

The skill writes code that needs the sentence-transformers package. Install it with pip. This also pulls in transformers and torch. Models are downloaded from Hugging Face on first use, so you need internet access the first time a model loads.

• Python is required
• Optional for integration examples: langchain-community, langchain-chroma or llama-index

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in plain language that mentions embeddings, semantic search, similarity, clustering or RAG, and the agent should load the skill when it matches the description. Naming the library or a model makes the match more likely.

Good requests say what the input is, what you want back and where it should run. For example, ask for a script that embeds your text files and returns the top matches for a question.

• "Write a Python script that embeds my support articles with all-MiniLM-L6-v2 and returns the three most similar ones to a query."
• "Cluster these 5,000 customer comments by topic using a local sentence-transformers model."
• "Set up a Chroma vector store with sentence-transformers embeddings for my docs folder."
• "Use a multilingual sentence-transformers model to search German and English product descriptions."

Choose a model

The skill's model guide recommends all-MiniLM-L6-v2 as a default for prototyping and general tasks. It is fast and produces 384-dimension vectors. all-mpnet-base-v2 produces 768 dimensions and is described as better quality for production RAG. all-roberta-large-v1 gives the best quality in the guide but is slower and uses 1024 dimensions.

For multilingual text, the skill points to paraphrase-multilingual models. Domain-specific models exist for legal, scientific and code text, but the skill notes that provenance varies, so check each model's source and terms before using it on sensitive data.

• Start with all-MiniLM-L6-v2 as a baseline
• Use all-mpnet-base-v2 when you want better quality in RAG
• Use paraphrase-multilingual-mpnet-base-v2 for multilingual search
• Test more than one model, since quality varies by task

Safety notes: scripts and network access

This skill runs scripts and uses the network. The Python code it writes will run on your machine, so read it before executing, especially code that fine-tunes models or writes files. Model weights are fetched from Hugging Face on first use, which means outbound network access is needed at that point.

If you work with sensitive data, check the licence and source of each model before you embed private documents with it. Running models locally keeps your text off third-party APIs, but it does not make an unvetted model safe.

• Review generated code before running it
• Expect a one-time download of model files from Hugging Face
• Verify model licences for sensitive or commercial work

Tips for better results

Ask the agent to normalise embeddings and to cache them, since the library's best practices recommend both. Encoding in batches is more efficient than encoding one sentence at a time. If a GPU is available, the skill notes encoding can be about 10 times faster, though your speed will depend on your hardware.

Memory matters. Larger models need more RAM, and the performance table in the skill lists about 120MB for MiniLM and about 1.3GB for RoBERTa.

• Encode in batches with a sensible batch_size
• Save embeddings to disk so you do not recompute them
• Ask for a small test on a few hundred documents before a full run
• Check the reference models guide when choosing between options