Merge pull request #2 from pinecone-io/sync/skills-23154564948

Finalized plugin with validation.

Author: arjunpatel7

.cursor-plugin/plugin.json

@@ -1,10 +1,11 @@
 {
   "name": "pinecone",
-  "description": "Pinecone vector database integration. Streamline your Pinecone development with powerful tools for managing vector indexes, querying data, and rapid prototyping. Use slash commands like /quickstart to generate AGENTS.md files and initialize Python projects and /query to quickly explore indexes. Access the Pinecone MCP server for creating, describing, upserting and querying indexes with Cursor. Perfect for developers building semantic search, RAG applications, recommendation systems, and other vector-based applications with Pinecone.",
+  "description": "Pinecone vector database integration. Streamline your Pinecone development with powerful tools for managing vector indexes, querying data, and rapid prototyping. Use slash commands like /quickstart to learn how to build with Pinecone and /query to quickly explore indexes. Access the Pinecone MCP server for creating, describing, upserting and querying indexes with Cursor. Perfect for developers building semantic search, RAG applications, recommendation systems, and other vector-based applications with Pinecone.",
   "version": "1.0.0",
   "author": {
     "name": "Pinecone"
   },
+  "logo": "assets/logo.svg",
   "keywords": [
     "pinecone",
     "semantic search",

.github/workflows/contextualize-skills.yml

@@ -2,7 +2,7 @@ name: Contextualize Incoming Skills
 
 on:
   pull_request:
-    types: [opened, synchronize]
+    types: [opened]
 
 jobs:
   contextualize:

.mcp.json

@@ -1,25 +1,84 @@
 # Pinecone Cursor Plugin
 
-Official Pinecone plugin for Cursor. Provides skills, rules, and a Pinecone MCP server integration for building with Pinecone.
+Official [Pinecone](https://www.pinecone.io) plugin for [Cursor](https://cursor.com). Build semantic search, RAG, recommendation systems, and other vector-based applications with Pinecone — directly from your editor.
 
-## Skills
+## What's included
 
-| Skill | Description |
+### Skills
+
+Skills are specialized agent capabilities invoked automatically by Cursor Agent or manually via `/skill-name` in chat.
+
+| Skill | What it does |
 |-------|-------------|
-| `quickstart` | Onboarding — create an index, upload data, run your first search |
-| `query` | Natural language search across Pinecone indexes via MCP |
-| `cli` | Pinecone CLI (`pc`) for index and vector management |
-| `assistant` | Pinecone Assistants for document Q&A with citations |
-| `mcp` | Reference docs for all MCP server tools and parameters |
-| `docs` | Organized links to official Pinecone documentation |
-| `help` | Overview of all skills and getting-started guidance |
+| `/quickstart` | Step-by-step onboarding — create an index, upload data, and run your first search. Choose between a **Database** path (vector search) or **Assistant** path (document Q&A). |
+| `/query` | Search integrated indexes using natural language text via the Pinecone MCP server. |
+| `/cli` | Use the Pinecone CLI (`pc`) for terminal-based index and vector management. |
+| `/assistant` | Create, manage, and chat with Pinecone Assistants for document Q&A with citations. Includes scripts for uploading files, syncing changes, and retrieving context. |
+| `/mcp` | Reference documentation for all Pinecone MCP server tools and their parameters. |
+| `/docs` | Curated links to official Pinecone documentation, organized by topic. |
+| `/help` | Overview of all available skills and what you need to get started. |
+
+### MCP Server
+
+The plugin bundles the [Pinecone MCP server](https://github.com/pinecone-io/pinecone-mcp) (`@pinecone-database/mcp`), giving Cursor Agent direct access to your Pinecone resources:
 
-## MCP Server
+- Create, describe, and delete indexes
+- Upsert and query vectors
+- Search Pinecone documentation
+- Manage index configurations
 
-The plugin bundles the [Pinecone MCP server](https://github.com/pinecone-io/pinecone-mcp) (`@pinecone-database/mcp`). Requires a `PINECONE_API_KEY` environment variable.
+### Bundled Scripts
+
+Several skills include Python scripts (run via [`uv`](https://docs.astral.sh/uv/)) for operations beyond what MCP provides:
+
+| Script | Skill | Purpose |
+|--------|-------|---------|
+| `upsert.py` | quickstart | Seed an index with sample data |
+| `quickstart_complete.py` | quickstart | Standalone end-to-end quickstart |
+| `create.py` | assistant | Create a new Pinecone Assistant |
+| `upload.py` | assistant | Upload files to an assistant |
+| `chat.py` | assistant | Chat with an assistant |
+| `context.py` | assistant | Retrieve context snippets from an assistant |
+| `list.py` | assistant | List all assistants in your account |
+| `sync.py` | assistant | Sync local files to an assistant |
 
 ## Prerequisites
 
-- [Pinecone account](https://app.pinecone.io) (free)
-- Pinecone API key
-- Node.js v18+ (for the MCP server)
+- **Pinecone account** — free at [app.pinecone.io](https://app.pinecone.io/?sessionType=signup)
+- **API key** — create one in the Pinecone console, then set it:
+  ```bash
+  export PINECONE_API_KEY="your-key"
+  ```
+- **Node.js v18+** — required for the MCP server (`npx`)
+
+### Optional
+
+| Tool | What it enables | Install |
+|------|----------------|---------|
+| [Pinecone CLI](https://docs.pinecone.io/guides/operations/pinecone-cli) (`pc`) | Terminal-based index management, batch operations | `brew tap pinecone-io/tap && brew install pinecone-io/tap/pinecone` |
+| [uv](https://docs.astral.sh/uv/) | Run the bundled Python scripts | [Install guide](https://docs.astral.sh/uv/getting-started/installation/) |
+
+## Getting started
+
+1. Install the plugin from the [Cursor Marketplace](https://cursor.com/marketplace)
+2. Set your `PINECONE_API_KEY` environment variable
+3. Open Cursor Agent chat and type `/quickstart` to get started
+4. Verify the MCP server is connected: Cursor Settings > Features > Model Context Protocol
+
+## Verifying the installation
+
+| Component | Where to check |
+|-----------|---------------|
+| Skills | Cursor Settings > Rules — listed under "Agent Decides" |
+| MCP Server | Cursor Settings > Features > Model Context Protocol |
+| Commands | Type `/` in Agent chat and search |
+
+## Links
+
+- [Pinecone Documentation](https://docs.pinecone.io)
+- [Pinecone MCP Server](https://github.com/pinecone-io/pinecone-mcp)
+- [Pinecone Discord](https://discord.gg/pinecone)
+
+## License
+
+[Apache-2.0](LICENSE)

README.md

@@ -185,15 +185,17 @@ async function main() {
     }
   }
 
-  // 7. Check MCP config
-  const mcpPath = path.join(repoRoot, ".mcp.json");
-  if (await pathExists(mcpPath)) {
-    const mcp = await readJsonFile(mcpPath, "MCP config");
+  // 7. Check MCP config (mcp.json or .mcp.json)
+  const mcpPath = path.join(repoRoot, "mcp.json");
+  const mcpPathDot = path.join(repoRoot, ".mcp.json");
+  const mcpFile = (await pathExists(mcpPath)) ? mcpPath : (await pathExists(mcpPathDot)) ? mcpPathDot : null;
+  if (mcpFile) {
+    const mcp = await readJsonFile(mcpFile, "MCP config");
     if (mcp && !mcp.mcpServers) {
-      addError('.mcp.json missing "mcpServers" key');
+      addError(`${path.basename(mcpFile)} missing "mcpServers" key`);
     }
   } else {
-    addWarning("No .mcp.json found");
+    addWarning("No mcp.json found");
   }
 
   // 8. Check hooks

assets/logo.svg

@@ -0,0 +1,78 @@
+---
+name: assistant
+description: Create, manage, and chat with Pinecone Assistants for document Q&A with citations. Handles all assistant operations - create, upload, sync, chat, context retrieval, and list. Recognizes natural language like "create an assistant from my docs", "ask my assistant about X", or "upload my docs to Pinecone".
+---
+
+# Pinecone Assistant
+
+Pinecone Assistant is a fully managed RAG service. Upload documents, ask questions, get cited answers. No embedding pipelines or infrastructure required.
+
+> All scripts are in `scripts/` relative to this skill directory.
+> Run with: `uv run scripts/script_name.py [arguments]`
+
+## Operations
+
+| What to do | Script | Key args |
+|---|---|---|
+| Create an assistant | `scripts/create.py` | `--name` `--instructions` `--region` |
+| Upload files | `scripts/upload.py` | `--assistant` `--source` `--patterns` |
+| Sync files (incremental) | `scripts/sync.py` | `--assistant` `--source` `--delete-missing` `--dry-run` |
+| Chat / ask a question | `scripts/chat.py` | `--assistant` `--message` |
+| Get context snippets | `scripts/context.py` | `--assistant` `--query` `--top-k` |
+| List assistants | `scripts/list.py` | `--files` `--json` |
+
+For full workflow details on any operation, read the relevant file in `references/`.
+
+---
+
+## Natural Language Recognition
+
+Proactively handle these patterns without requiring explicit commands:
+
+**Create:** "create an assistant", "make an assistant called X", "set up an assistant for my docs"
+→ See [references/create.md](references/create.md)
+
+**Upload:** "upload my docs", "add files to my assistant", "index my documentation"
+→ See [references/upload.md](references/upload.md)
+
+**Sync:** "sync my docs", "update my assistant", "keep assistant in sync", "refresh from ./docs"
+→ See [references/sync.md](references/sync.md)
+
+**Chat:** "ask my assistant about X", "what does my assistant know about X", "chat with X"
+→ See [references/chat.md](references/chat.md)
+
+**Context:** "search my assistant for X", "find context about X"
+→ See [references/context.md](references/context.md)
+
+**List:** "show my assistants", "what assistants do I have"
+→ Run `uv run scripts/list.py`
+
+---
+
+## Conversation Memory
+
+Track the last assistant used within the conversation:
+- When a user creates or first uses an assistant, remember its name
+- If user says "my assistant", "it", or "the assistant" → use the last one
+- Briefly confirm which assistant you're using: "Asking docs-bot..."
+- If ambiguous and multiple exist → ask the user to clarify
+
+---
+
+## Multi-Step Requests
+
+Handle chained requests naturally. Example:
+
+> "Create an assistant called docs-bot, upload my ./docs folder, and ask what the main features are"
+
+1. `uv run scripts/create.py --name docs-bot`
+2. `uv run scripts/upload.py --assistant docs-bot --source ./docs`
+3. `uv run scripts/chat.py --assistant docs-bot --message "what are the main features?"`
+
+---
+
+## Prerequisites
+
+- `PINECONE_API_KEY` must be available — terminal: `export PINECONE_API_KEY="your-key"`, or add to a `.env` file and run scripts with `uv run --env-file .env scripts/...`
+- `uv` must be installed — [install uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Get a free API key at: https://app.pinecone.io/?sessionType=signup

scripts/validate-plugin.mjs

@@ -0,0 +1,33 @@
+# Chat with Assistant
+
+Send a message to an assistant and receive a cited response.
+
+## Arguments
+
+- `--assistant` (required): Assistant name
+- `--message` (required): The question or message
+- `--stream` (optional flag): Enable streaming for faster perceived response
+
+## Workflow
+
+1. Parse arguments. If assistant missing, run `uv run scripts/list.py --json` and ask the user to select.
+2. If message missing, prompt user for their question.
+3. Execute:
+   ```bash
+   uv run scripts/chat.py \
+     --assistant "assistant-name" \
+     --message "user's question"
+   ```
+4. Display:
+   - Assistant's response
+   - Citations table: citation number, source file, page numbers, position
+   - Token usage statistics
+
+**Note:** File URLs in citations are temporary signed links (~1 hour). They are not displayed in output.
+
+## Troubleshooting
+
+**Assistant not found** — run list command, check for typos.
+**No response or timeout** — verify assistant has files uploaded and status is "ready" (not "indexing").
+**Empty or poor responses** — assistant may lack relevant documents; suggest upload.
+**PINECONE_API_KEY not set** — export the variable or add to a `.env` file, then restart your IDE/agent session.

skills/assistant/SKILL.md

@@ -0,0 +1,39 @@
+# Retrieve Context Snippets
+
+Get raw context snippets from an assistant's knowledge base without generating a full chat response. Useful for debugging, custom RAG workflows, or quick lookups.
+
+## Arguments
+
+- `--assistant` (required): Assistant name
+- `--query` (required): Search query text
+- `--top-k` (optional): Number of snippets — default `5`, max `16`
+- `--snippet-size` (optional): Max tokens per snippet — default `2048`
+- `--json` (optional flag): JSON output
+
+## Workflow
+
+1. Parse arguments. If missing, list assistants and prompt for selection.
+2. Execute:
+   ```bash
+   uv run scripts/context.py \
+     --assistant "assistant-name" \
+     --query "search text" \
+     --top-k 5
+   ```
+3. Display snippets: file name, page numbers, relevance score, content.
+
+## Context vs Chat
+
+**Use context when:** you want raw snippets, are debugging knowledge, need source material, or are building custom workflows.
+**Use chat when:** you want synthesized answers, citations in a conversational response, or multi-turn Q&A.
+
+## Interpreting Results
+
+- **Score:** Higher (closer to 1.0) = more relevant
+- **Low scores (<0.5):** Weak match, assistant may need more relevant documents, or query is too broad/specific
+
+## Troubleshooting
+
+**No results** — try broader search terms; suggest uploading more documents.
+**context method not available** — update SDK: `pip install --upgrade pinecone` (requires v8.0.0+).
+**Assistant not found** — check name for typos, run list command.

skills/assistant/references/chat.md

@@ -0,0 +1,43 @@
+# Create Assistant
+
+Create a new Pinecone Assistant with custom configuration.
+
+## Arguments
+
+- `--name` (required): Unique name for the assistant
+- `--instructions` (optional): Behavior directive (tone, format, language)
+- `--region` (optional): `us` or `eu` — default `us`
+- `--timeout` (optional): Seconds to wait for ready status — default `30`
+
+## Workflow
+
+1. Parse arguments. If name is missing, prompt the user.
+2. Ask the user about region preference — US or EU.
+3. Ask if user wants custom instructions. Offer examples:
+   - "Use professional technical tone and cite sources"
+   - "Respond in Spanish with formal language"
+4. Execute:
+   ```bash
+   uv run scripts/create.py \
+     --name "assistant-name" \
+     --instructions "instructions" \
+     --region "us"
+   ```
+5. Show assistant name, status, and host URL.
+6. Offer to run upload next.
+
+## Naming Conventions
+
+Suggest: `{purpose}-{type}` — e.g. `docs-qa`, `support-bot`, `api-helper`
+Avoid: `test`, `assistant1`, `my-assistant`
+
+## Post-Creation
+
+- Save the assistant host URL shown in output (needed for MCP config)
+- View and manage at: https://app.pinecone.io/organizations/-/projects/-/assistant/
+
+## Troubleshooting
+
+**Assistant name already exists** — list assistants and suggest a different name or delete the existing one.
+**Timeout** — increase `--timeout 60`, check network connectivity.
+**PINECONE_API_KEY not set** — export the variable or add to a `.env` file, then restart your IDE/agent session.