Guide · Agent skill
How to use the Chroma Embedding Database agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Chroma skill teaches your AI agent how to set up Chroma, an open-source embedding database. Chroma stores text along with its numerical embeddings, so you can search documents by meaning instead of exact keywords. This guide explains what the skill does, how to install it, how to ask for help with natural requests, and what to check before you run the code it writes.
Chroma Embedding DatabaseOrchestra-Research/AI-Research-SKILLs · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the chroma skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder.
- 2Install the packages. Run pip install chromadb and sentence-transformers for Python. For JavaScript, run npm install chromadb @chroma-core/default-embed.
- 3Ask for a Chroma task. Describe what you want in plain language, for example indexing a folder of Markdown files for semantic search.
- 4Review the generated code. Check the code for file paths, package installs, network calls and any API keys before you run it.
- 5Test a query. Run a sample query with query_texts and n_results to confirm the results match what you expect, then add a metadata filter if needed.
What does the Chroma skill make the agent do?
Once the skill is installed, the agent knows how to set up Chroma and write code for common tasks. It can add documents with metadata, run similarity searches with metadata filters, get, update or delete entries, and save data to disk so it persists between runs.
The skill also covers wiring Chroma into frameworks. It includes examples for LangChain and LlamaIndex, which are used for retrieval-augmented generation (RAG): finding relevant documents and passing them to an AI model so its answers are grounded in your own material.
- Create, get and delete collections
- Add documents with metadata and custom or auto-generated IDs
- Similarity search with metadata filters such as $and, $or, $gt and $in
- Update and delete entries by ID or by filter
- Persistent local storage with PersistentClient
- LangChain and LlamaIndex integration
Install the Chroma skill from the ZIP download
Download the skill ZIP from this page and unzip it. To make the skill available to Claude Code for all your projects, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal (all projects): ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Install the Python and JavaScript packages
The skill expects the Python chromadb package. It also needs sentence-transformers for the default embedding function. For JavaScript, install chromadb and @chroma-core/default-embed.
The OpenAI and HuggingFace embedding options are optional. They need an API key and an account with that provider, and the examples send your text to those services.
- Required (Python): chromadb and sentence-transformers
- Optional (JavaScript): chromadb and @chroma-core/default-embed
- Optional: OpenAI or HuggingFace API key, if you use those embedding functions
- Optional: langchain_chroma and langchain_openai for LangChain
# Python
pip install chromadb
# JavaScript/TypeScript
npm install chromadb @chroma-core/default-embedHow do you trigger the skill with a natural request?
You do not need special syntax. Describe the task in plain language and mention Chroma, a vector store or semantic search so the agent knows which tool you mean. Name your files or data so the agent can locate them. The examples below show the kind of request that works.
The skill's own example workflow is a good model: create a collection, add documents with metadata, query with a filter, then read the results.
- 'Use Chroma to index the Markdown files in ./docs and make a search function that returns the top 5 matches.'
- 'Store these support tickets in a Chroma collection with their product name as metadata, then find tickets about login failures for product X.'
- 'Set up a persistent Chroma database in ./chroma_db and load my PDF notes into it.'
- 'Connect my LangChain retriever to a Chroma store so my chatbot answers from my own documents.'
collection.query(
query_texts=["login failures"],
n_results=5,
where={"product": "X"}
)Save data to disk and reuse it
By default, the basic client does not show a saved database in these examples. To keep your data, use PersistentClient with a path. The skill shows that data is saved automatically and can be reopened later using the same path.
If you want the vector store to be used by LangChain, the skill's LangChain example passes a persist_directory to Chroma.from_documents. The LlamaIndex example uses the same path-based client.
- Use the same path each time to reopen the same data
- Use get_or_create_collection in LlamaIndex setups to avoid errors on repeat runs
import chromadb
client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_collection("my_docs")Choose an embedding function carefully
If you do not set an embedding function, Chroma uses Sentence Transformers by default, with the model all-MiniLM-L6-v2. This runs with the sentence-transformers package and does not need an API key. Use OpenAI or HuggingFace embeddings only if you accept that your text is sent to those services.
The examples use the placeholder api_key="your-key". Replace it with your own key from a secure source, never paste a real key into a file you might share.
- Default: Sentence Transformers, model all-MiniLM-L6-v2
- OpenAI: text-embedding-3-small in the example, sends data externally
- HuggingFace: sentence-transformers/all-mpnet-base-v2 in the example, sends data externally
- Custom: subclass EmbeddingFunction and return your own vectors
Safety notes before you run the code
This skill runs scripts and uses the network. The code it writes may install packages, write files to disk such as ./chroma_db, and call external embedding APIs. Read generated code before you run it, especially any line that sends text to a third-party service.
Keep API keys out of source files and version control. If your content is private or confidential, prefer the default local embedding function or a self-hosted model rather than OpenAI or HuggingFace.
- Review commands and scripts the agent produces before running them
- Do not send confidential text to OpenAI or HuggingFace unless you have approved it
- Store real API keys in environment variables or a secrets manager, not in code
- Check the folder paths the code writes to
What people use it for
- Prototyping a semantic search box over your own documentation or notes
- Building a RAG chatbot that answers from a folder of PDFs or text files using LangChain or LlamaIndex
- Storing support tickets or articles with metadata and filtering them by product, category or source
- Keeping a small, self-hosted vector database on your laptop for an open-source project
Frequently asked questions
How do I install the Chroma agent skill?
Download the skill ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.
What do I need to use Chroma with this skill?
You need Python with the chromadb package and sentence-transformers for the default embedding function. JavaScript users need chromadb and @chroma-core/default-embed. An OpenAI or HuggingFace API key is optional and only needed if you use those embedding functions.
Is Chroma free to use?
The skill is listed under the MIT licence. The SKILL.md file also states that Chroma itself is Apache 2.0 licensed. The OpenAI and HuggingFace embedding options are paid or account-based services from those providers, so check their terms if you use them.
Does Chroma send my data to the cloud?
Not by default. The default embedding function uses Sentence Transformers. The OpenAI and HuggingFace examples send your text to those external services, so avoid them for private content unless you accept that.
Chroma vs Pinecone, Qdrant or FAISS: which should I pick?
The skill says Chroma is best for local development and open-source projects. It names Pinecone as the managed cloud option with auto-scaling, Qdrant as a high-performance Rust-based database, Weaviate for production ML-native use, and FAISS for pure similarity search without metadata.
Why is my Chroma data gone after I restart my script?
The basic client in the examples does not show saved storage. Use chromadb.PersistentClient with a path such as ./chroma_db so the data is saved to disk and can be reopened later with the same path.
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 prototyping semantic search or RAG in Python or JavaScript, want a self-hosted open-source store, or are building a document search tool over your own files. Pick a managed service such as Pinecone for large production systems that need auto-scaling, and avoid the OpenAI or HuggingFace paths if your text must stay off third-party services.
Download the skill