Main skill for all Pinecone Assistant operations. Read this first! Create, manage, and chat with Pinecone Assistants for document Q&A. Automatically recognizes natural language requests like "create an assistant from my docs" or "ask my assistant about authentication" without requiring slash commands. ALWAYS invoke when using Pinecone Assistant related commands
From atum-systemnpx claudepluginhub arnwaldn/atum-system --plugin atum-systemThis skill is limited to using the following tools:
scripts/chat.pyscripts/context.pyscripts/create.pyscripts/list.pyscripts/sync.pyscripts/upload.pyProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Builds automated SaaS billing systems: recurring payments, invoicing, subscription lifecycle, dunning, proration, taxes, and usage-based billing.
ALWAYS invoke this skill before running any assistant-* commands, as it will inform you of the correct directories for associated scripts!
All paths are relative to the directory containing this SKILL.md file. Scripts are run with:
uv run scripts/script_name.py [arguments]
You should proactively recognize and handle natural language requests about Pinecone Assistant without requiring slash commands.
Creating Assistants:
→ Run: uv run scripts/create.py --name [name]
→ Use AskUserQuestion if name is missing
Uploading Files:
→ Run: uv run scripts/upload.py --assistant [name] --source [path]
→ Use AskUserQuestion if missing info
Syncing Files:
→ Run: uv run scripts/sync.py --assistant [name] --source [path]
→ Sync only uploads new/changed files (uses mtime + size detection)
→ Add --delete-missing if user wants to remove files that no longer exist locally
→ Add --dry-run to preview changes without executing
Chatting/Asking Questions:
→ Run: uv run scripts/chat.py --assistant [name] --message "[question]"
→ IMPORTANT: Remember the last assistant used - if user says "my assistant" or doesn't specify, use the last one mentioned
Getting Context:
→ Run: uv run scripts/context.py --assistant [name] --query "[topic]"
Listing Assistants:
→ Run: uv run scripts/list.py
Track the last assistant used within the conversation:
User: "Create an assistant called docs-bot"
You: [Creates it] ✅ Remember: last_assistant = "docs-bot"
User: "Upload ./docs to it"
You: [Uploads to docs-bot] ✓ Using remembered assistant
User: "What is authentication?"
You: "Let me ask docs-bot..." [Runs chat with docs-bot]
User: "Tell me more"
You: [Continues with docs-bot]
Rules:
Handle chained requests naturally:
Example 1: Create + Upload + Chat "Create an assistant called docs-bot, upload my ./docs folder, and ask what the main features are"
→ Execute in sequence:
uv run scripts/create.py --name docs-botuv run scripts/upload.py --assistant docs-bot --source ./docsuv run scripts/chat.py --assistant docs-bot --message "what are the main features?"Example 2: Sync + Query "Update my assistant with the latest docs and tell me what changed about authentication"
→ Execute in sequence:
uv run scripts/sync.py --assistant [remembered-assistant] --source ./docsuv run scripts/chat.py --assistant [remembered-assistant] --message "what changed about authentication?"Pinecone Assistant is a fully managed RAG (Retrieval Augmented Generation) service that enables you to upload documents and ask questions about them with cited responses. The assistant automatically chunks, embeds, and indexes your files for instant semantic search and question answering.
Important Note: Pinecone Assistant is optimized for document-based content (PDFs, markdown, text files with natural language). It is not recommended for indexing codebases at this time. For code search and understanding, consider using Pinecone's vector database with specialized code embeddings instead.
Pinecone Assistant is ideal for users who want an instant Q&A assistant without writing code!
If you have local documentation, PDFs, or markdown files and want to:
Then Pinecone Assistant is the perfect solution. Simply:
/pinecone:assistant-create/pinecone:assistant-upload/pinecone:assistant-chatNo coding required - just point to your documentation directory and start chatting!
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])
assistant = pc.assistant.create_assistant(
assistant_name="my-docs-assistant",
instructions="Use professional tone and cite sources.",
region="us", # or "eu"
timeout=30
)
Parameters:
assistant_name (required): Unique identifier for the assistantinstructions (optional): Directive for assistant behavior (e.g., tone, format, language)region (optional): "us" or "eu" (default: "us")timeout (optional): Seconds to wait for ready status (default: 30)Returns: Assistant object with name, host, and status
# Get assistant instance
assistant = pc.assistant.Assistant(assistant_name="my-docs-assistant")
# Upload a single file
response = assistant.upload_file(
file_path="/path/to/document.pdf",
metadata={"source": "github", "repo": "owner/repo", "type": "documentation"},
timeout=None
)
Parameters:
file_path (required): Path to local filemetadata (optional): Dictionary of custom metadata attached to the filetimeout (optional): Wait duration (None = no timeout)Supported File Types:
Best for: Documentation, technical writing, reports, papers, guides, data files, and other natural language content.
Not recommended for: Source code files (.py, .js, .ts, etc.). Assistant is optimized for documents and natural language, not code syntax and structure.
Best Practice: Add metadata to track file sources, types, versions, etc. This helps with:
from pinecone_plugins.assistant.models.chat import Message
# Create message
msg = Message(role="user", content="What is the main feature of this product?")
# Get response
response = assistant.chat(messages=[msg])
# Access response components
print(response.message.content) # Assistant's answer
print(response.citations) # Source references with page numbers
print(response.usage) # Token usage statistics
Message Object:
role: "user" or "assistant"content: Text of the messageResponse Object:
message: Assistant's reply with content and rolecitations: List of citation objects, each containing:
position: Character position in response where citation appearsreferences: List of reference objects with:
file.name: Source file namefile.id: Unique file identifierfile.signed_url: Temporary download URL (valid ~1 hour)pages: List of page numbers (for PDFs)metadata: File metadata (content_type, file_path, etc.)usage: Token consumption (prompt_tokens, completion_tokens, total_tokens)finish_reason: "stop", "length", or "error"Multi-turn Conversations:
messages = [
Message(role="user", content="What is RAG?"),
Message(role="assistant", content=response1.message.content),
Message(role="user", content="How does it work with Pinecone?")
]
response = assistant.chat(messages=messages)
# Get relevant context snippets without generating a full response
response = assistant.context(
query="deployment architecture",
top_k=5,
snippet_size=2048 # Maximum tokens per snippet
)
# Process context snippets
for snippet in response.snippets:
# Extract file info from reference
file_name = snippet.reference.file.name
pages = snippet.reference.pages # List of page numbers
content = snippet.content # The actual text snippet
score = snippet.score # Relevance score
print(f"File: {file_name}")
print(f"Pages: {pages}")
print(f"Content: {content}")
print(f"Score: {score}")
Parameters:
query (required): Search query texttop_k (optional): Number of snippets to return (default: 16, max: 16)snippet_size (optional): Maximum tokens per snippet (default: 2048)Response Structure:
response.snippets: List of snippet objects containing:
content: The text snippetscore: Relevance score (0-1)type: Content type (usually "text")reference: Reference object with:
file.name: Source filenamefile.id: Unique file identifierfile.signed_url: Temporary download URL (~1 hour)pages: List of page numbersUse Cases for Context Retrieval:
# List all assistants in account
assistants = pc.assistant.list_assistants()
for asst in assistants:
print(f"Name: {asst.name}")
print(f"Region: {asst.region}")
print(f"Status: {asst.status}")
print(f"Host: {asst.host}")
# Delete assistant and all uploaded files
pc.assistant.delete_assistant(assistant_name="my-docs-assistant")
Warning: This permanently deletes the assistant and all associated files.
import os
import glob
# User provides repo path
repo_path = "/path/to/user/repo"
# Find relevant files
patterns = ["**/*.md", "**/*.py", "**/*.js", "**/*.txt"]
files_to_upload = []
for pattern in patterns:
files_to_upload.extend(glob.glob(f"{repo_path}/{pattern}", recursive=True))
# Filter out unwanted directories
exclude_dirs = ["node_modules", ".venv", ".git", "build", "dist"]
files_to_upload = [
f for f in files_to_upload
if not any(excl in f for excl in exclude_dirs)
]
# Upload each file with metadata
for file_path in files_to_upload:
relative_path = os.path.relpath(file_path, repo_path)
assistant.upload_file(
file_path=file_path,
metadata={
"source": "local_repo",
"repo_path": repo_path,
"file_path": relative_path,
"file_type": os.path.splitext(file_path)[1]
}
)
export PINECONE_API_KEY="your-api-key-here"
Get your API key from: https://app.pinecone.io/?sessionType=signup
export PINECONE_ASSISTANT_HOST="https://prod-1-data.ke.pinecone.io"
The assistant host is automatically provided when you create an assistant. Typical values:
https://prod-1-data.ke.pinecone.ioEvery Pinecone Assistant is also an MCP (Model Context Protocol) server, enabling AI agents to access the assistant's knowledge.
Format: https://<YOUR_ASSISTANT_HOST>/mcp/assistants/<YOUR_ASSISTANT_NAME>
Add to your MCP configuration (.mcp.json or Claude Desktop config):
{
"mcpServers": {
"my-assistant": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "PINECONE_API_KEY",
"-e", "PINECONE_ASSISTANT_HOST",
"pinecone/assistant-mcp"
],
"env": {
"PINECONE_API_KEY": "${PINECONE_API_KEY}",
"PINECONE_ASSISTANT_HOST": "${PINECONE_ASSISTANT_HOST}"
}
}
}
}
company-docs-qa, codebase-search, product-supporttest, assistant1, my-assistantmetadata = {
"source": "github",
"repo": "owner/repo",
"branch": "main",
"commit": "abc123",
"file_path": "docs/api.md",
"uploaded_at": "2024-01-15",
"category": "documentation"
}
instructions = """
- Use professional technical tone
- Cite specific page numbers and files
- If unsure, say so rather than guessing
- Format code examples with proper syntax highlighting
"""
Maintain conversation history by passing previous messages to enable context-aware responses.
When you need raw context without generated responses, use the context API instead of chat.
API Key Missing:
# Check before use
if not os.environ.get('PINECONE_API_KEY'):
raise ValueError("PINECONE_API_KEY not set")
Assistant Not Found:
# List assistants first
assistants = pc.assistant.list_assistants()
if assistant_name not in [a.name for a in assistants]:
raise ValueError(f"Assistant '{assistant_name}' not found")
File Upload Failures:
Timeout Errors:
pip install pinecone-client pinecone-plugin-assistant
Or with the unified SDK:
pip install "pinecone[assistant]"
For use with uv:
# /// script
# dependencies = [
# "pinecone[assistant]",
# ]
# ///
This skill provides Python scripts that Claude Code can invoke via uv run:
list.py - List all assistants in account (use --files flag to show file details)create.py - Create a new assistantupload.py - Upload files or repository to assistant (one-time upload)sync.py - Sync local files to assistant (only uploads new/changed files)chat.py - Chat with assistant and get cited responsescontext.py - Retrieve context snippets from assistantAll scripts assume PINECONE_API_KEY is set in the environment, and uv is installed.