Pinecone:Quickstart

Name: Pinecone:Quickstart
Author: pinecone-io

pinecone-io/pinecone-claude-code-plugin

4 installs
67 repo stars
Updated July 17, 2026
pinecone-io/pinecone-claude-code-plugin

pinecone:quickstart is a Claude Code skill for ai & agent building.

About

Walks a first-time user through semantic search over example data via a Database path (integrated index plus Python) or an Assistant path. A developer uses it for a guided introduction to Pinecone's tools.

Guided first Pinecone experience with Database or Assistant path
Semantic search over example data via MCP plus Python

Pinecone:Quickstart by the numbers

4 all-time installs (skills.sh)
Ranked #708 of 911 Databases skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/pinecone-io/pinecone-claude-code-plugin --skill pineconequickstart

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/pinecone-io/pinecone-claude-code-plugin/pinecone%3Aquickstart.svg)](https://skillselion.com/skills/pinecone-io/pinecone-claude-code-plugin/pinecone%3Aquickstart)

Installs	4
repo stars	★ 67
Last updated	July 17, 2026
Repository	pinecone-io/pinecone-claude-code-plugin ↗

How do I helps with ai & agent building tasks.?

Interactive Pinecone quickstart letting new developers choose a Database vector-search path or an Assistant document Q&A path.

Who is it for?

A solo builder working on ai & agent building tasks who needs structured help with pinecone:quickstart.

Skip if: Teams with no ai & agent building needs, or anyone wanting a generic chat assistant without this specific workflow.

When should I use this skill?

When you need to helps with ai & agent building tasks., or when pinecone:quickstart is a claude code skill for ai & agent building.

What you get

Structured output aligned to pinecone:quickstart: pinecone:quickstart, AI & Agent Building.

Files

SKILL.mdMarkdownGitHub ↗

Pinecone Quickstart

Welcome! This skill walks you through your first Pinecone experience using the tools available to you. In this quickstart, you will learn how to do a simple form of semantic search over some example data.

Prerequisites

Before starting either path, verify the API key works by calling list-indexes via the Pinecone MCP. If it succeeds, proceed. If it fails, ask the user to set their key:

export PINECONE_API_KEY="your-key"

Then retry list-indexes to confirm.

Step 0: Choose Your Path

Use AskUserQuestion to let the user choose their path:

Database – Build a vector search index. Best for developers who want to store and search embeddings. Uses the Pinecone MCP + a Python upsert script.
Assistant – Build a document Q&A assistant. Best for users who want to upload files and ask questions with cited answers. No code required.

---

Path A: Database Quickstart

For each step, explain to the user what will happen. An overview is here:

1. Check if MCP is set 2. Create an integrated index with MCP 3. Upsert sample data using the bundled script (9 sentences across productivity, health, and nature themes) 4. Run a semantic search query and explore further queries 5. Optionally try reranking 6. Offer the complete standalone script

Step 1 – Verify MCP is Available

The prerequisite check already called list-indexes. If it succeeded, the MCP is working — proceed to Step 2.

If it failed because MCP tools were unavailable (not an auth error):

Tell the user the MCP server needs to be configured
Point them to: https://docs.pinecone.io/reference/tools/mcp

Step 2 – Create an Integrated Index

Use the MCP create-index-for-model tool to create a serverless index with integrated embeddings:

name: quickstart-skills
cloud: aws
region: us-east-1
embed:
  model: llama-text-embed-v2
  fieldMap:
    text: chunk_text

Explain to the user what's happening:

An integrated index uses a built-in Pinecone embedding model (llama-text-embed-v2)
This means you send plain text and Pinecone handles the embedding automatically
The field_map tells Pinecone which field in your records contains the text to embed

Wait for the index to become ready before proceeding. Waiting a few seconds is sufficient.

Step 3 – Upsert Sample Data

Run the bundled upsert script to seed the index with sample records:

uv run scripts/upsert.py --index quickstart-skills

Explain to the user what's happening:

The script uploads 9 sample records across three themes: productivity (getting work done), health (feeling unwell), and nature (outdoors/wildlife)
The dataset is intentionally varied so semantic search can show its value — the queries below use completely different words than the records, but the right ones still surface
Each record has an _id, a chunk_text field (the text that gets embedded), and a category field
This is the same structure you'd use for your own data — just replace the records

Step 4 – Query with the MCP

Use the MCP search-records tool to run the first semantic search:

index: quickstart-skills
namespace: example-namespace
query:
  topK: 3
  inputs:
    text: "getting things done efficiently"

Display the results in a clean table: ID, score, and chunk_text.

Explain to the user what's happening:

Notice the query shares no keywords with the records — but it surfaces the productivity sentences
That's semantic search: it finds meaning, not just matching words
You sent plain text — Pinecone embedded the query using the same model as the index

Offer to explore further: Use AskUserQuestion to ask if they'd like to try another query:

Option A: "feeling under the weather" — should surface the health records
Option B: "wildlife spotting outside" — should surface the nature records
Option C: No thanks, move on

Run whichever query they choose and display the results the same way. If they want to try both, do both. After each result, point out which theme surfaced and why.

If they decline or are done exploring, proceed to Step 5 or offer to skip ahead to the complete script.

Step 5 – Try Reranking (Optional)

Use AskUserQuestion to ask if the user wants to try reranking.

If yes, use search-records again with reranking enabled:

rerank:
  model: bge-reranker-v2-m3
  rankFields: [chunk_text]
  topN: 3

Explain: Reranking runs a second-pass model over the results to improve relevance ordering.

Step 6 – Wrap Up

Congratulate the user on completing the quickstart. Use AskUserQuestion to ask if they'd like a standalone Python script that does everything in one go — create index, upsert, query, and rerank.

If yes, copy it to their working directory:

cp scripts/quickstart_complete.py ./pinecone_quickstart.py

Tell the user:

The script is at ./pinecone_quickstart.py
Run it with: uv run pinecone_quickstart.py
It uses uv inline dependencies — no separate install needed
They can swap in their own records list to build something real

---

Path B: Assistant Quickstart

Guide the user through the Pinecone Assistant workflow using the existing assistant skills:

Step 1 – Check for Documents

Before anything else, use AskUserQuestion to ask if the user has files to upload. Pinecone Assistant accepts .pdf, .md, .txt, and .docx files — a single file or a folder of files both work.

If they have files: ask for the path and proceed to Step 2.

If they don't have files: use AskUserQuestion to offer two options:

Generate sample docs — create a few short markdown files in ./sample-docs/ so they can complete the quickstart right now. Ask what topics they'd like (or default to: a product FAQ, a short how-to guide, and a brief company overview). Write 3 files, each 150–250 words.
Come back later — let them know they can return once they have documents and pick up from Step 2.

Step 2 – Create an Assistant

Invoke pinecone:assistant or run:

uv run ../assistant/scripts/create.py --name my-assistant

Explain: The assistant is a fully managed RAG service — upload documents, ask questions, get cited answers.

Step 3 – Upload Documents

Invoke pinecone:assistant or run:

uv run ../assistant/scripts/upload.py --assistant my-assistant --source ./your-docs

Explain: Pinecone handles chunking, embedding, and indexing automatically — no configuration needed.

Step 4 – Chat with the Assistant

Invoke pinecone:assistant or run:

uv run ../assistant/scripts/chat.py --assistant my-assistant --message "What are the main topics in these documents?"

Explain: Responses include citations with source file and page number.

Next Steps for Assistant

Invoke pinecone:assistant to keep the assistant up to date as documents change
Use the assistant skill to retrieve raw context snippets for custom workflows
Every assistant is also an MCP server — see https://docs.pinecone.io/guides/assistant/mcp-server

---

Troubleshooting

`PINECONE_API_KEY` not set

export PINECONE_API_KEY="your-key"

MCP tools not available

Verify the Pinecone MCP server is configured in your IDE's MCP settings
Check that PINECONE_API_KEY is set before the MCP server starts

Index already exists

The upsert script is safe to re-run — it will upsert over existing records
Or delete and recreate: use pc index delete -n quickstart-skills via the CLI

`uv` not installed See the uv installation guide.

#!/usr/bin/env python3
# /// script
# dependencies = [
#   "pinecone>=8.0.0",
# ]
# ///

import os
from pinecone import Pinecone

api_key = os.environ.get("PINECONE_API_KEY")
if not api_key:
    raise ValueError("PINECONE_API_KEY environment variable not set")

pc = Pinecone(api_key=api_key, source_tag="claude_code_plugin:quickstart_complete")

# 1. Create a serverless index with an integrated embedding model
index_name = "quickstart"

if not pc.has_index(index_name):
    pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model": "llama-text-embed-v2",
            "field_map": {"text": "chunk_text"}
        }
    )

# 2. Upsert records
# Three distinct themes — notice the queries below use different words than the records.
# That's semantic search: finding meaning, not just matching keywords.
records = [
    # Health / feeling unwell
    {"_id": "rec1", "chunk_text": "I've been sneezing all day and my nose won't stop running.", "category": "health"},
    {"_id": "rec2", "chunk_text": "She stayed home with a pounding headache and a low-grade fever.", "category": "health"},
    {"_id": "rec3", "chunk_text": "He felt completely drained after waking up with a sore throat and chills.", "category": "health"},
    # Productivity / work
    {"_id": "rec4", "chunk_text": "She blocked off two hours in the morning to focus without interruptions.", "category": "productivity"},
    {"_id": "rec5", "chunk_text": "He finished all his tasks ahead of schedule by prioritizing the hardest ones first.", "category": "productivity"},
    {"_id": "rec6", "chunk_text": "Turning off notifications helped her get into a deep flow state.", "category": "productivity"},
    # Outdoors / nature
    {"_id": "rec7", "chunk_text": "A red fox darted across the trail and disappeared into the underbrush.", "category": "nature"},
    {"_id": "rec8", "chunk_text": "The hikers paused to watch a bald eagle circle lazily over the valley.", "category": "nature"},
    {"_id": "rec9", "chunk_text": "Fireflies lit up the meadow as the sun dipped below the treeline.", "category": "nature"},
]

dense_index = pc.Index(index_name)
dense_index.upsert_records("example-namespace", records)

# 3. Search records
# The query uses different words than the records — semantic search finds meaning, not keywords.
query = "feeling ill and run down"

results = dense_index.search(
    namespace="example-namespace",
    query={"top_k": 3, "inputs": {"text": query}}
)

print("Search results:")
for hit in results["result"]["hits"]:
    print(f"  id: {hit['_id']} | score: {round(hit['_score'], 2)} | text: {hit['fields']['chunk_text']}")

# 4. Search with reranking
reranked_results = dense_index.search(
    namespace="example-namespace",
    query={"top_k": 3, "inputs": {"text": query}},
    rerank={"model": "bge-reranker-v2-m3", "top_n": 3, "rank_fields": ["chunk_text"]}
)

print("\nReranked results:")
for hit in reranked_results["result"]["hits"]:
    print(f"  id: {hit['_id']} | score: {round(hit['_score'], 2)} | text: {hit['fields']['chunk_text']}")

#!/usr/bin/env python3
# /// script
# dependencies = [
#   "pinecone>=8.0.0",
#   "typer>=0.15.0",
# ]
# ///

import os
import typer
from pinecone import Pinecone

app = typer.Typer()

@app.command()
def main(
    index: str = typer.Option(..., "--index", help="Name of the Pinecone index to upsert into"),
    namespace: str = typer.Option("example-namespace", "--namespace", help="Namespace to upsert into"),
):
    api_key = os.environ.get("PINECONE_API_KEY")
    if not api_key:
        typer.echo("Error: PINECONE_API_KEY environment variable not set", err=True)
        raise typer.Exit(1)

    pc = Pinecone(api_key=api_key, source_tag="claude_code_plugin:quickstart_upsert")

    records = [
        # Health / feeling unwell
        {"_id": "rec1", "chunk_text": "I've been sneezing all day and my nose won't stop running.", "category": "health"},
        {"_id": "rec2", "chunk_text": "She stayed home with a pounding headache and a low-grade fever.", "category": "health"},
        {"_id": "rec3", "chunk_text": "He felt completely drained after waking up with a sore throat and chills.", "category": "health"},
        # Productivity / work
        {"_id": "rec4", "chunk_text": "She blocked off two hours in the morning to focus without interruptions.", "category": "productivity"},
        {"_id": "rec5", "chunk_text": "He finished all his tasks ahead of schedule by prioritizing the hardest ones first.", "category": "productivity"},
        {"_id": "rec6", "chunk_text": "Turning off notifications helped her get into a deep flow state.", "category": "productivity"},
        # Outdoors / nature
        {"_id": "rec7", "chunk_text": "A red fox darted across the trail and disappeared into the underbrush.", "category": "nature"},
        {"_id": "rec8", "chunk_text": "The hikers paused to watch a bald eagle circle lazily over the valley.", "category": "nature"},
        {"_id": "rec9", "chunk_text": "Fireflies lit up the meadow as the sun dipped below the treeline.", "category": "nature"},
    ]

    idx = pc.Index(index)
    idx.upsert_records(namespace, records)
    typer.echo(f"Upserted {len(records)} records into '{index}' (namespace: '{namespace}')")

if __name__ == "__main__":
    app()