Skip to content
Get packs

Guide · Agent skill

How to use the Pinecone Vector Database agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Pinecone skill is an instruction file that teaches an AI agent how to use Pinecone, a hosted vector database that stores embeddings so an app can find content by meaning instead of exact keywords. This guide explains what the skill does, how to install it from the ZIP or the Claude apps, how to ask for things in plain language, and what you need before the code will run. By the end you will know how to get the agent to write Pinecone code for indexes, queries, filters and namespaces.

Pinecone Vector DatabaseOrchestra-Research/AI-Research-SKILLs · MIT

Quick start

  1. 1Download and unzip. Download the pinecone skill ZIP from this page and unzip it. The folder should include SKILL.md and references/deployment.md.
  2. 2Place the skill. Move the unzipped folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. Claude apps users can upload it under Settings → Capabilities → Skills.
  3. 3Prepare accounts and packages. Install pinecone-client with pip, then get a Pinecone API key and an embedding provider key.
  4. 4Ask in plain language. Describe the task, such as creating an index or running a filtered query, and mention Pinecone.
  5. 5Review the generated code. Read the code the agent writes, check the dimension matches your embeddings, and replace placeholder keys with environment variables.
  6. 6Run and check results. Run the code yourself, then check the matches and metadata returned by your query.

What the Pinecone skill makes the agent do

Agent skills are folders of instructions and examples that an AI agent loads when a task matches them. This one gives the agent working knowledge of the Pinecone API, so it can write code that creates an index, loads vectors with metadata, runs similarity and filtered searches, separates data with namespaces, and connects Pinecone to LangChain or LlamaIndex.

The skill is instructional text and code examples. It does not run anything on its own. Your own code, run by you, is what talks to Pinecone.

  • Create a serverless or pod-based index with a chosen dimension and metric (cosine, euclidean or dotproduct).
  • Upsert vectors with metadata, in batches.
  • Query for the nearest matches, with optional metadata filters ($eq, $gte, $in, $and, $or and others).
  • Use namespaces to isolate users or tenants.
  • Run hybrid queries that combine dense and sparse vectors.
  • Wire Pinecone into LangChain (langchain-pinecone) or LlamaIndex.

Install the Pinecone skill

Download the skill ZIP from this page and unzip it. You can install it for yourself across projects or for a single project.

For a personal install, unzip into ~/.claude/skills/. For a project-only install, unzip into the project's .claude/skills/ folder. Claude apps users can instead upload the skill under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Single project: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills, then upload

Set up what the skill needs

The skill writes code, but the code needs Python, the Pinecone client and accounts for the services it calls. Set these up before asking for working code.

You need a Pinecone account and an API key, and an embedding model provider with its own API key (the examples use OpenAIEmbeddings). If you use a framework, install its Pinecone package too.

  • Python with the pinecone-client package
  • A Pinecone account and API key
  • An embedding model provider and its API key
  • Optional: langchain-pinecone or llama-index vector store packages
pip install pinecone-client

Trigger the skill with natural requests

You do not need to name the skill. Describe the task in plain language that mentions Pinecone, a vector index, semantic search or RAG, and the agent should load the instructions when they match.

Good requests say what you are building and what the data looks like. Mention the embedding size if you know it, because the index dimension must match the embedding model.

  • "Write a Python script that creates a Pinecone serverless index for 1536-dimension embeddings using cosine similarity."
  • "Upsert these product descriptions into my Pinecone index with category and price metadata, in batches of 100."
  • "Query Pinecone for the top 5 matches, but only where category is tutorial and difficulty is 3 or lower."
  • "Keep each customer's vectors separate using a namespace per user ID."
  • "Add a Pinecone retriever to my LangChain RAG chain."

Example: create an index and run a filtered query

A typical first task is creating an index, loading a few vectors and querying with a filter. The skill's basic pattern looks like this. Replace the placeholder API key and make sure the vector length matches your embedding model.

Serverless is the recommended spec in the source. The source also shows a pod-based option with PodSpec for consistent performance.

  • Filter syntax: {"category": {"$eq": "tutorial"}} for an exact match, or {"price": {"$gte": 100}} for a comparison.
from pinecone import Pinecone, ServerlessSpec pc = Pinecone(api_key="your-api-key") pc.create_index(name="my-index", dimension=1536, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1")) index = pc.Index("my-index") results = index.query(vector=[0.1, 0.2], top_k=5, include_metadata=True, filter={"category": {"$eq": "tutorial"}})

Safety notes: network use and your data

The skill is marked as using the network, and it is built around a cloud service. Using Pinecone means sending your vectors, metadata and any text stored in metadata to Pinecone's servers. Check that this fits your data rules before loading anything sensitive.

The skill is listed as not running scripts. The code it writes will run only when you run it, so read generated code before you execute it and keep API keys out of shared files. The examples place keys directly in code for illustration; use environment variables or a secrets manager in real projects.

  • Uses network: yes. Vectors and metadata are sent to Pinecone.
  • Runs scripts: no. The skill itself does not execute code.
  • Keep API keys out of version control.
  • Deleting an index or vectors is permanent; the source shows delete_all and delete_index, so review those calls carefully.

Tips for better results

The source's best-practice list is short and practical. Batch your upserts, since the source suggests 100 to 200 per batch. Add metadata to any field you plan to filter on. Use namespaces when you need to isolate users or tenants. Set the dimension to match your embedding model, because a mismatch will fail.

The source notes a free tier of one serverless index and 100K vectors at 1536 dimensions, and it links to the pricing page for current terms. Check the live pricing page rather than relying on figures in the skill text.

  • Start with serverless unless you have a specific reason for pods.
  • Batch upserts at 100 to 200 vectors.
  • Use namespaces to separate users or tenants.
  • Use hybrid search (dense plus sparse) when keyword matches matter.
  • Check the Pinecone console for usage.

What people use it for

  • Building a retrieval step for a production RAG chatbot that answers from your own documents.
  • Adding semantic search to a product catalogue with category and price filters.
  • Keeping each customer's embeddings separate with one namespace per tenant.
  • Connecting a LangChain or LlamaIndex pipeline to a hosted vector store.

Frequently asked questions

Is the Pinecone agent skill free?

The skill is listed under the MIT licence. Pinecone itself is a paid hosted service with a free tier that the source describes as one serverless index and 100K vectors at 1536 dimensions; check the Pinecone pricing page for current terms.

What do I need before using the Pinecone skill?

You need Python with the pinecone-client package, a Pinecone account and API key, and an embedding model provider with its own API key. The examples use OpenAIEmbeddings. Framework packages such as langchain-pinecone are optional.

Where do I install the skill?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills.

Does the skill run code or send my data anywhere?

The skill is instructional text and code examples, and it is listed as not running scripts. It does use the network, because the code it helps you write sends vectors and metadata to Pinecone's cloud service.

What are the alternatives to Pinecone?

The source's own list names Chroma as self-hosted and open-source, FAISS as offline pure similarity search, and Weaviate as self-hosted with more features. These suit projects that must keep data on their own infrastructure.

Why does my Pinecone query fail with a dimension error?

The index dimension must match your embedding model's output length. The source warns that dimension must match the embedding model, so recreate the index with the correct value (the examples use 1536).

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 a Python developer building production RAG or semantic search and want a managed vector database your agent can write code for. Pick a self-hosted or local option such as Chroma or FAISS if your data must stay on your own infrastructure, or if you only need a small prototype without an account.

Download the skill