sync: skills from pinecone-io/skills

skills/pinecone-assistant/SKILL.md

@@ -10,6 +10,8 @@ Pinecone Assistant is a fully managed RAG service. Upload documents, ask questio
 > All scripts are in `scripts/` relative to this skill directory.
 > Run with: `uv run scripts/script_name.py [arguments]`
 
+Whenever this skill asks the user to choose between options, confirm a destructive step, or pick from a list, ask in plain prose, list the options, and wait for their answer before continuing.
+
 ## Operations
 
 | What to do | Script | Key args |
@@ -73,6 +75,10 @@ Handle chained requests naturally. Example:
 
 ## Prerequisites
 
-- `PINECONE_API_KEY` must be available — add it to a `.env` file at your workspace root (the bundled MCP config loads it via Cursor's `envFile` field) and run scripts with `uv run --env-file .env scripts/...`. For terminal-only scripts, `export PINECONE_API_KEY="your-key"` also works.
+- `PINECONE_API_KEY` must be available:
+- Add `PINECONE_API_KEY=your-key` to a `.env` file at your workspace root. The
+  bundled MCP config reads it through Cursor's `envFile` field.
+- For scripts, either `export PINECONE_API_KEY="your-key"` in your terminal or
+  run them 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

skills/pinecone-assistant/scripts/context.py

@@ -131,8 +131,8 @@ def main(
 
             # Suggest next action
             next_action = f"""[bold]Next steps:[/bold]
-• Ask a question: [cyan]/pinecone:assistant-chat assistant {assistant} message [your question][/cyan]
-• Upload more files: [cyan]/pinecone:assistant-upload assistant {assistant} source [path][/cyan]"""
+• Ask a question: [cyan]uv run chat.py --assistant {assistant} --message "YOUR QUESTION"[/cyan]
+• Upload more files: [cyan]uv run upload.py --assistant {assistant} --source PATH[/cyan]"""
             console.print(Panel(next_action, title="What's Next?", border_style="green"))
 
     except AttributeError as e:
@@ -141,7 +141,7 @@ def main(
         console.print(f"[dim]Details: {e}[/dim]")
         console.print("\n[yellow]Note:[/yellow] Context API requires SDK version with assistant.context() support")
         console.print("\n[yellow]Try using chat instead:[/yellow]")
-        console.print(f"  /pinecone:assistant-chat assistant {assistant} message \"{query}\"")
+        console.print(f"  uv run chat.py --assistant {assistant} --message \"{query}\"")
         raise typer.Exit(1)
     except Exception as e:
         console.print(f"[red]Error: {e}[/red]")

skills/pinecone-assistant/scripts/create.py

@@ -112,9 +112,9 @@ def main(
 
         # Next steps
         next_steps = f"""[bold]Next steps:[/bold]
-1. Upload files: [cyan]/pinecone:assistant-upload assistant {name} source [path][/cyan]
-2. Chat: [cyan]/pinecone:assistant-chat assistant {name} message [your question][/cyan]
-3. Get context: [cyan]/pinecone:assistant-context assistant {name} query [search][/cyan]"""
+1. Upload files: [cyan]uv run upload.py --assistant {name} --source PATH[/cyan]
+2. Chat: [cyan]uv run chat.py --assistant {name} --message "YOUR QUESTION"[/cyan]
+3. Get context: [cyan]uv run context.py --assistant {name} --query "SEARCH TEXT"[/cyan]"""
 
         console.print(Panel(next_steps, title="What's Next?", border_style="green"))
 

skills/pinecone-assistant/scripts/list.py

@@ -61,7 +61,7 @@ def main(
             else:
                 console.print("[yellow]No assistants found.[/yellow]\n")
                 console.print("Create your first assistant with:")
-                console.print("  [cyan]/pinecone:assistant-create name [assistant-name][/cyan]")
+                console.print("  [cyan]uv run create.py --name ASSISTANT_NAME[/cyan]")
             return
 
         if json_output:
@@ -195,10 +195,10 @@ def main(
 
             # Next steps panel
             next_steps = """[bold]Next steps:[/bold]
-• List with files: [cyan]/pinecone:assistant-list --files[/cyan]
-• Chat: [cyan]/pinecone:assistant-chat assistant [name] message [your question][/cyan]
-• Upload: [cyan]/pinecone:assistant-upload assistant [name] source [path][/cyan]
-• Context: [cyan]/pinecone:assistant-context assistant [name] query [search][/cyan]"""
+• List with files: [cyan]uv run list.py --files[/cyan]
+• Chat: [cyan]uv run chat.py --assistant NAME --message "YOUR QUESTION"[/cyan]
+• Upload: [cyan]uv run upload.py --assistant NAME --source PATH[/cyan]
+• Context: [cyan]uv run context.py --assistant NAME --query "SEARCH TEXT"[/cyan]"""
 
             console.print(Panel(next_steps, title="Available Commands", border_style="blue"))
 

skills/pinecone-assistant/scripts/upload.py

@@ -208,8 +208,8 @@ def main(
         # Next steps
         if uploaded > 0:
             next_steps = f"""[bold]Next steps:[/bold]
-• Chat: [cyan]/pinecone:assistant-chat assistant {assistant} message [your question][/cyan]
-• Context: [cyan]/pinecone:assistant-context assistant {assistant} query [search][/cyan]
+• Chat: [cyan]uv run chat.py --assistant {assistant} --message "YOUR QUESTION"[/cyan]
+• Context: [cyan]uv run context.py --assistant {assistant} --query "SEARCH TEXT"[/cyan]
 
 [dim]Note: Files are being processed and will be available shortly[/dim]"""
             console.print(Panel(next_steps, title="What's Next?", border_style="green"))

skills/pinecone-docs/SKILL.md

@@ -22,7 +22,7 @@ Use this as a last resort if you cannot find the relevant page below.
 
 | Topic | URL |
 |---|---|
-| Quickstart for all languages and coding environments (Cursor, n8n, Python, JavaScript, Java, Go, C#) | https://docs.pinecone.io/guides/get-started/quickstart |
+| Quickstart for all languages and coding environments (Cursor, Claude Code, n8n, Python, JavaScript, Java, Go, C#) | https://docs.pinecone.io/guides/get-started/quickstart |
 | Pinecone concepts — namespaces, terminology, and key database concepts | https://docs.pinecone.io/guides/get-started/concepts |
 | Data modeling for text and vectors | https://docs.pinecone.io/guides/index-data/data-modeling |
 | Architecture of Pinecone | https://docs.pinecone.io/guides/get-started/database-architecture |
@@ -57,6 +57,7 @@ Use this as a last resort if you cannot find the relevant page below.
 | Semantic search | https://docs.pinecone.io/guides/search/semantic-search |
 | Hybrid search | https://docs.pinecone.io/guides/search/hybrid-search |
 | Lexical search | https://docs.pinecone.io/guides/search/lexical-search |
+| Full-text search (preview) — document-schema FTS indexes with `text` / `query_string` / dense / sparse scoring | https://docs.pinecone.io/guides/search/full-text-search |
 | Metadata filtering — narrow results and speed up searches | https://docs.pinecone.io/guides/search/filter-by-metadata |
 
 ---

skills/pinecone-full-text-search/SKILL.md

@@ -3,9 +3,12 @@ name: pinecone-full-text-search
 description: Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API (2026-01.alpha, public preview). Use when the user or agent asks to build a text search index on Pinecone, add dense or sparse vector fields, ingest documents, construct score_by clauses (text / query_string / dense_vector / sparse_vector), or compose with text-match filters ($match_phrase / $match_all / $match_any). Ships `scripts/ingest.py` for safe bulk ingestion (batch_upsert + error inspection + readiness polling); query construction is documented inline in this skill — write `documents.search(...)` calls directly, validated against `pc.preview.indexes.describe(...)` output.
 ---
 
-# pinecone-full-text-search
+# Pinecone Full-Text Search
 
-> **Requires `pinecone` Python SDK ≥ 9.0** (`pip install pinecone>=9.0`). The FTS document-schema API lives under `pinecone.preview` and is incomplete or absent in earlier SDK builds. The packaged helper scripts pin `pinecone==9.1.0` via PEP 723 inline metadata; if you're writing your own code against this skill, pin v9 explicitly. The wire API version is `2026-01.alpha`.
+> **Requires `pinecone` Python SDK ≥ 9.0** (`pip install pinecone>=9.0`). The FTS document-schema API lives under `pinecone.preview` and is incomplete or absent in earlier SDK builds. The packaged helper scripts pin `pinecone==9.1.0` via PEP 723 inline metadata; if you're writing your own code against this skill, **pin the exact version** —
+`pinecone.preview` is explicitly outside SemVer, so signatures can change in any
+minor release. `documents.fetch` and `documents.delete` both lost their `filter`
+parameter between 9.0.0 and 9.1.0. The wire API version is `2026-01.alpha`.
 
 > **Authoritative reference (last resort).** If you hit a question this skill and its `references/*.md` files don't answer, the official Pinecone FTS docs are at <https://docs.pinecone.io/guides/search/full-text-search>. Prefer this skill's content for anything covered here — the docs may describe surfaces (e.g. classic vector API) that don't apply to the document-schema FTS path. Consult the link only when you're genuinely stuck.
 
@@ -267,7 +270,7 @@ schema = (
     SchemaBuilder()
     .add_string_field("body", full_text_search={"language": "en"})  # TODO: rename for your content
     .add_string_field("category", filterable=True)                   # TODO: any exact-match metadata
-    .add_integer_field("year", filterable=True)                      # TODO: any numeric filter — emits `"type": "float"` on the wire
+    .add_float_field("year", filterable=True)                        # TODO: any numeric filter — `float` is the only numeric wire type
     .build()
 )
 
@@ -323,7 +326,7 @@ for m in resp.matches:
 - **One scoring type per search request.** `score_by` accepts `text`, `query_string`, `dense_vector`, or `sparse_vector` — but a request ranks by *one* type. Multi-field BM25 is fine (pass several `text` clauses, or a single cross-field `query_string`). To combine BM25 ranking with a `dense_vector` (or `sparse_vector`) signal, restrict the dense search with a text-match `filter` operator (`$match_phrase` / `$match_all` / `$match_any`) on the lexical field, *not* by mixing types in `score_by`. The "blend a dense vector and a text clause in `score_by`" pattern is rejected by the server.
 - **Text-match filter operators are the cross-modal hinge.** `$match_phrase` (exact phrase), `$match_all` (every token, any order), `$match_any` (at least one token) are filter-side operators on `full_text_search` fields. Each takes a single string (max 128 tokens). They reuse the field's tokenizer / stemmer, compose under `$and` / `$or` / `$not`, and are the supported way to compose lexical pre-filtering with dense or sparse ranking. **Phrase slop (`"…"~N`), term boost (`^N`), and phrase prefix (`"… word"*`) are scoring-only — they live in `query_string`, not in `filter`.**
 - **Preprod backends need `additional_headers={"x-environment": "..."}` on the `Pinecone()` client.** Missing the header lands you on prod and you'll see "index not found" / empty-result symptoms that look like code bugs but aren't.
-- **`include_fields` is required on every `documents.search(...)` call.** When omitted, defaults to `[]` (`_id` + `_score` only). Pass `["*"]` for all stored fields or a list of names to project. Omitting it on some SDK builds yields `400` / `422` instead of the documented default; always pass it explicitly to avoid surprises.
+- **`include_fields` is required on every `documents.search(...)` call.** When omitted, the key is left off the request and the server returns **all** stored fields. Pass `["*"]` for all stored fields or a list of names to project. Omitting it on some SDK builds yields `400` / `422` instead of the documented default; always pass it explicitly to avoid surprises.
 - **Match score is `_score`; doc id is `_id`.** Public-preview docs return the system match score on the `_score` field so a user metadata field literally named `score` can coexist. Always prefer `_score` on read; some older SDK builds may still surface plain `score`, so for defensive code use `getattr(m, "_score", getattr(m, "score", None))`.
 - **Reserved field names: leading `_` and `$`, max 64 bytes.** `_` is for system fields (`_id`, `_score`); `$` is for filter operators. Schema validation rejects names that violate either rule. Length cap is bytes, not characters — be careful with non-ASCII names.
 - **Vector-field cardinality: at most one `dense_vector` and at most one `sparse_vector` per index** in `2026-01.alpha`. Multiple text fields are fine.

skills/pinecone-full-text-search/references/onboarding-walkthrough.md

@@ -85,15 +85,15 @@ If any field starts with `_` or `$`:
 >     # Filter only — exact-match category like "fiction"
 >     .add_string_field("category", filterable=True)
 >     # Numeric range filter (e.g. year > 2024)
->     .add_integer_field("year", filterable=True)
+>     .add_float_field("year", filterable=True)
 >     # Tag filter — list membership ($in)
 >     .add_string_list_field("tags", filterable=True)
 >     .build()
 > ```
 >
 > A few notes:
 > - **No dense_vector field** — you said you don't have embeddings yet. We can add one later, but it requires creating a *new* index because schemas are immutable. Want to add a placeholder now and keep the door open?
-> - **`year` uses `add_integer_field`** but Pinecone stores it as `float` on the wire. The naming is confusing but normal — there's no separate integer type.
+> - **`year` uses `add_float_field`** — `float` is the only numeric wire type; there is no integer helper.
 > - **`tags`** will become `["a","b","c"]` after the comma-split we discussed.
 >
 > Schemas are immutable in `2026-01.alpha` — once we create this, changing it means re-creating the index and re-ingesting all the data.

skills/pinecone-full-text-search/references/schema-design.md

@@ -12,7 +12,7 @@ schema = (
     .add_string_field("title", full_text_search={"language": "en"})
     .add_string_field("body",  full_text_search={"language": "en", "stemming": True})
     .add_string_field("category", filterable=True)
-    .add_integer_field("year", filterable=True)              # emits `"type": "float"` on the wire
+    .add_float_field("year", filterable=True)                # `float` is the only numeric wire type
     .add_dense_vector_field("embedding",       dimension=1024, metric="cosine")
     .add_sparse_vector_field("sparse_embedding", metric="dotproduct")
     .build()            # terminal: returns the schema object you pass to indexes.create
@@ -81,18 +81,18 @@ Stored verbatim, not tokenized, not text-scored. Enables exact-match filtering:
 ## Numeric, boolean, and array metadata
 
 ```python
-.add_integer_field("year", filterable=True)                              # wire type: "float"
-.add_custom_field("featured", {"type": "boolean", "filterable": True})  # no add_boolean_field helper in v9
+.add_float_field("year", filterable=True)      # `float` is the only numeric wire type
+.add_boolean_field("featured", filterable=True)
 .add_string_list_field("tags", filterable=True)
 ```
 
-- **`float`** is the only numeric wire type — there is no separate integer type. The SchemaBuilder helper is misleadingly named `add_integer_field` but emits `{"type": "float", "filterable": ...}`. Supports `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`.
-- **`boolean`** has no dedicated builder helper in pinecone v9 — declare via `add_custom_field("name", {"type": "boolean", "filterable": True})`. Supports `$eq` and `$exists`.
+- **`float`** is the only numeric wire type — there is no separate integer type, and **there is no `add_integer_field` helper**. Use `add_float_field`, which emits `{"type": "float", "filterable": ...}`. Note `describe()` may still report the field class as `PreviewIntegerField`. Supports `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`.
+- **`boolean`** uses `add_boolean_field("name", filterable=True)`. Supports `$eq` and `$exists`.
 - **`string_list`** supports `$in` / `$nin` membership semantics — handy for tag-style metadata.
 
 All filter operators compose under `$and`, `$or`, `$not`. Multiple keys at the top level of `filter` are combined with implicit AND.
 
-> **SchemaBuilder helper-name pitfall** (pinecone v9): `add_integer_field()` produces `{"type": "float"}`, not a separate integer type. The class name in `describe()` responses is also `PreviewIntegerField`, but the wire/server type is `"float"`. Use `add_integer_field` for any numeric metadata; use `add_custom_field` with an explicit `{"type": "boolean", ...}` dict for booleans.
+> **SchemaBuilder numeric-type pitfall**: there is no `add_integer_field()` helper — calling it raises `AttributeError`. Use `add_float_field()` for any numeric metadata; `float` is the only numeric wire type. `describe()` responses may still name the class `PreviewIntegerField`, but the wire/server type is `"float"`.
 
 > **Forward-looking note.** In the public preview, metadata fields you send at upsert time are auto-indexed for filtering even if not declared in the schema. In a future release, only schema-declared fields with `filterable: true` will be indexed. Declare your metadata fields in the schema today to be future-proof.
 

skills/pinecone-help/SKILL.md

@@ -9,19 +9,20 @@ Pinecone is the leading vector database for building accurate and performant AI
 
 Here's everything you need to get started and a summary of all available skills.
 
-Invoke any skill from Cursor Agent chat with `/pinecone-<skill-name>` (for example, `/pinecone-quickstart` or `/pinecone-n8n`).
+Invoke any skill from Cursor Agent chat with `/pinecone-<skill-name>` — for example `/pinecone-quickstart` or `/pinecone-n8n`.
 
 ---
 
 ## What You Need
 
 ### Required
 - **Pinecone account** — free to create at https://app.pinecone.io/?sessionType=signup
-- **API key** — create one in the Pinecone console after signing up, then add it to a `.env` file at your workspace root (the bundled MCP config loads it via Cursor's `envFile` field):
-  ```
-  PINECONE_API_KEY=your-key
-  ```
-  For terminal scripts you can also `export PINECONE_API_KEY="your-key"`.
+- **API key** — create one in the Pinecone console after signing up, then make it
+  available to this environment:
+  - Add `PINECONE_API_KEY=your-key` to a `.env` file at your workspace root. The
+  bundled MCP config reads it through Cursor's `envFile` field.
+- For scripts, either `export PINECONE_API_KEY="your-key"` in your terminal or
+  run them with `uv run --env-file .env scripts/...`.
 
 ### Optional (unlock more capabilities)
 

skills/pinecone-query/SKILL.md

@@ -8,6 +8,8 @@ argument-hint: query [q] index [indexName] namespace [ns] topK [k] reranker [rer
 
 Search for records in Pinecone integrated indexes using natural language text queries via the Pinecone MCP server.
 
+Whenever this skill asks the user to choose between options, confirm a destructive step, or pick from a list, ask in plain prose, list the options, and wait for their answer before continuing.
+
 ## What is this skill for?
 
 This skill provides a simple way to query **integrated indexes** (indexes with built-in Pinecone embedding models) using text queries. The MCP server automatically converts your text into embeddings and searches the index.
@@ -60,9 +62,13 @@ Utilize Pinecone MCP's `search-records` tool to search for records within a spec
 
 **`PINECONE_API_KEY` is required.** Get a free key at https://app.pinecone.io/?sessionType=signup
 
-If you get an access error, the key is likely missing. Ask the user to add `PINECONE_API_KEY=your-key` to a `.env` file at their workspace root — the bundled MCP config loads it via Cursor's `envFile` field — then restart their IDE or agent session. For terminal-only scripts, `export PINECONE_API_KEY="your-key"` also works.
+If you get an access error, the key is likely missing. Ask the user to set it and restart their IDE or agent session:
+- Add `PINECONE_API_KEY=your-key` to a `.env` file at your workspace root. The
+  bundled MCP config reads it through Cursor's `envFile` field.
+- For scripts, either `export PINECONE_API_KEY="your-key"` in your terminal or
+  run them with `uv run --env-file .env scripts/...`.
 
-**IMPORTANT** At the moment, the /pinecone-query command can only be used with integrated indexes, which use hosted Pinecone embedding models to embed and search for data.
+**IMPORTANT** At the moment, the pinecone-query skill can only be used with integrated indexes, which use hosted Pinecone embedding models to embed and search for data.
 If a user attempts to query an index that uses a third party API model such as OpenAI, or HuggingFace embedding models, remind them that this capability is not available yet
 with the Pinecone MCP server.