/quickstart

name: pinecone:quickstart
description: Interactive Pinecone quickstart for new developers. Choose between two paths - Database (create an integrated index, upsert data, and query using Pinecone MCP + Python) or Assistant (create a Pinecone Assistant for document Q&A). Use when a user wants to get started with Pinecone for the first time or wants a guided tour of Pinecone's tools.
allowed-tools: Skill(pinecone:assistant *), Bash, Read

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.

Whenever this skill asks the user to choose between options, confirm a destructive step, or pick from a list, use the AskUserQuestion tool rather than plain prose. Fall back to prose only if the tool is unavailable.

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:

• Run `export PINECONE_API_KEY="your-key"` in your terminal. Claude Code reads

your shell environment, so this is enough.

• To use a `.env` file instead, run scripts with `uv run --env-file .env scripts/...`.

Then retry `list-indexes` to confirm.

Step 0: Choose Your Path

Ask the user which path they want:

• **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.

If `PINECONE_API_KEY` is set in the environment:

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

If using a `.env` file:

uv run --env-file .env 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:** Ask the user if they'd like to try another query to see the effect more clearly:

• 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)

Ask the user if they want 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. 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 th