feat: attach hosted provider Skills to code-execution / shell tools

.changeset/provider-skills.md

@@ -0,0 +1,20 @@
+---
+'@tanstack/ai-anthropic': minor
+'@tanstack/ai-openai': minor
+'@tanstack/openai-base': minor
+'@tanstack/ai-grok': patch
+'@tanstack/ai-groq': patch
+---
+
+feat: attach hosted provider Skills to code-execution / shell tools
+
+Hosted, provider-managed Agent Skills can now be attached to the server-side execution tool that runs them:
+
+- **Anthropic** — `codeExecutionTool(config, { skills: [{ type: 'anthropic', skill_id: 'pptx', version: 'latest' }] })`. The adapter lifts the skills into the request's top-level `container.skills` and automatically attaches the required beta headers (`code-execution-2025-08-25` — or `code-execution-2025-05-22` for the legacy `code_execution_20250522` variant — plus `skills-2025-10-02`).
+- **OpenAI** — `shellTool({ environment: { type: 'container_auto', skills: [{ type: 'skill_reference', skill_id: '...', version: '2' }] } })`, threaded through the Responses API shell tool.
+
+Scope: hosted/managed skills referenced by id + version. Skills are inert without the execution tool that runs them.
+
+Setting skills via Anthropic's `modelOptions.container.skills` is deprecated in favor of `codeExecutionTool(config, { skills })`.
+
+Bumps the `openai` SDK to `^6.41.0` (required for the typed shell `environment.skills` surface).

docs/adapters/anthropic.md

@@ -299,6 +299,40 @@ const stream = chat({
 
 **Supported models:** Claude Sonnet 4.x and above. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
 
+#### Attaching hosted skills
+
+Pass a `skills` array as the second argument to load provider-managed skill
+bundles into the sandbox. The adapter auto-lifts them into the API's
+`container.skills` param and adds the required beta headers for you.
+
+```typescript
+import { chat, toServerSentEventsResponse } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+import { codeExecutionTool } from "@tanstack/ai-anthropic/tools";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  const stream = chat({
+    adapter: anthropicText("claude-sonnet-4-5"),
+    messages,
+    tools: [
+      codeExecutionTool(
+        { type: "code_execution_20250825", name: "code_execution" },
+        {
+          skills: [{ type: "anthropic", skill_id: "pptx", version: "latest" }],
+        },
+      ),
+    ],
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+For the full reference — skill shape, constraints, scope, and the OpenAI
+equivalent — see [Provider Skills](../tools/provider-skills.md).
+
 ### `computerUseTool`
 
 Allows Claude to observe a virtual desktop (screenshots) and interact with it

docs/adapters/openai.md

@@ -573,7 +573,8 @@ const stream = chat({
 ### `shellTool`
 
 A function-style shell tool that exposes shell execution as a structured
-function call. Takes no arguments.
+function call. Pass an `environment` object to attach container config and
+hosted skills.
 
 ```typescript
 import { chat } from "@tanstack/ai";
@@ -587,7 +588,43 @@ const stream = chat({
 });
 ```
 
-**Supported models:** GPT-5.x and other agent-capable models. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+**Supported models:** GPT-5.x and other agent-capable models. Responses API
+only — Chat Completions does not support the shell tool. See [Provider Tools](../tools/provider-tools.md#which-models-support-which-tools).
+
+#### Attaching hosted skills
+
+Pass `environment.skills` to load provider-managed skill bundles into the
+shell's container (Responses API only).
+
+```typescript
+import { chat, toServerSentEventsResponse } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+import { shellTool } from "@tanstack/ai-openai/tools";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  const stream = chat({
+    adapter: openaiText("gpt-5.2"),
+    messages,
+    tools: [
+      shellTool({
+        environment: {
+          type: "container_auto",
+          skills: [
+            { type: "skill_reference", skill_id: "skill_abc", version: "2" },
+          ],
+        },
+      }),
+    ],
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+For the full reference — skill shape, `version` string format, and the
+Anthropic equivalent — see [Provider Skills](../tools/provider-skills.md).
 
 ### `applyPatchTool`
 

docs/config.json

@@ -63,6 +63,10 @@
           "label": "Provider Tools",
           "to": "tools/provider-tools"
         },
+        {
+          "label": "Provider Skills",
+          "to": "tools/provider-skills"
+        },
         {
           "label": "Tool Architecture",
           "to": "tools/tool-architecture"

docs/tools/provider-skills.md

@@ -0,0 +1,178 @@
+---
+title: Provider Skills
+id: provider-skills
+order: 3
+description: "Attach hosted, provider-managed skills to code execution and shell tools in TanStack AI so the model can produce documents, run specialised environments, and more."
+keywords:
+  - tanstack ai
+  - provider skills
+  - anthropic skills
+  - openai skills
+  - code execution skills
+  - shell tool skills
+  - hosted skills
+  - container skills
+---
+
+Provider Skills are hosted, provider-managed capability bundles that the model
+loads on demand and runs inside the provider's server-side sandbox. You
+reference them by a skill ID; the provider handles installation and execution.
+
+> **Not to be confused with `@tanstack/ai-code-mode-skills`**, which are
+> locally-generated TypeScript functions evaluated client-side. Provider Skills
+> run entirely on the provider's infrastructure.
+
+Skills are **inert without an execution tool**. The execution tool activates the
+sandbox; skills are additional bundles that run inside it:
+
+- **Anthropic**: skills attach to `codeExecutionTool` (`@tanstack/ai-anthropic/tools`).
+- **OpenAI**: skills nest inside `shellTool` (`@tanstack/ai-openai/tools`) and
+  require the Responses API.
+
+You already have a `chat()` call working. By the end of this page you will have
+attached a hosted skill to the right execution tool, with the provider handling
+the rest.
+
+---
+
+## Anthropic: skills via `codeExecutionTool`
+
+### 1. Install the package
+
+```bash
+npm install @tanstack/ai-anthropic
+```
+
+### 2. Add the `codeExecutionTool` with skills
+
+Import `codeExecutionTool` from `@tanstack/ai-anthropic/tools`, not from the
+adapter root. Pass a `skills` array as the second argument.
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { codeExecutionTool } from '@tanstack/ai-anthropic/tools'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: anthropicText('claude-sonnet-4-5'),
+    messages,
+    tools: [
+      codeExecutionTool(
+        { type: 'code_execution_20250825', name: 'code_execution' },
+        {
+          skills: [{ type: 'anthropic', skill_id: 'pptx', version: 'latest' }],
+        },
+      ),
+    ],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+The adapter automatically:
+
+- Lifts your skills into the request's top-level `container.skills` parameter
+  (the shape Anthropic's API requires).
+- Attaches the `code-execution-2025-08-25` beta header, plus the
+  `skills-2025-10-02` beta header when skills are present.
+
+You do not set beta headers manually.
+
+### Skill shape
+
+Each entry in the `skills` array is an `AnthropicContainerSkill`:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `type` | `'anthropic' \| 'custom'` | yes | `'anthropic'` for Anthropic-hosted skills; `'custom'` for your own bundles. |
+| `skill_id` | `string` | yes | 1–64 characters. |
+| `version` | `string` | no | Specific version string, or `'latest'` (default when omitted). |
+
+Up to 8 skills per request. The factory throws at call time if you exceed this
+or supply an invalid `skill_id`.
+
+### Deprecation notice
+
+Setting skills via `modelOptions.container.skills` is deprecated. Use
+`codeExecutionTool(config, { skills })` instead — the legacy path bypasses the
+automatic beta-header wiring.
+
+---
+
+## OpenAI: skills via `shellTool` (Responses API only)
+
+The OpenAI `shellTool` accepts an `environment` object that can carry a
+`skills` array. This is **Responses API only**; the Chat Completions API does
+not support the shell tool.
+
+### 1. Install the package
+
+```bash
+npm install @tanstack/ai-openai
+```
+
+### 2. Add the `shellTool` with skills
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { shellTool } from '@tanstack/ai-openai/tools'
+
+export async function POST(request: Request) {
+  const { messages } = await request.json()
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.2'),
+    messages,
+    tools: [
+      shellTool({
+        environment: {
+          type: 'container_auto',
+          skills: [
+            { type: 'skill_reference', skill_id: 'skill_abc', version: '2' },
+          ],
+        },
+      }),
+    ],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+### Skill shape
+
+Each entry in the `skills` array is a `SkillReference`:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `type` | `'skill_reference'` | yes | Always `'skill_reference'` for OpenAI. |
+| `skill_id` | `string` | yes | The skill identifier provided by OpenAI. |
+| `version` | `string` | no | A positive integer as a string (e.g. `'2'`) or `'latest'`. |
+
+Note: `version` is a string, not a number.
+
+---
+
+## Scope
+
+Only **hosted, managed-by-id** skills are wired by these factories:
+
+- Anthropic: `type: 'anthropic'` or `type: 'custom'`
+- OpenAI: `type: 'skill_reference'`
+
+Inline bundles, local-path references, and upload-API skill creation are not
+handled by `codeExecutionTool` or `shellTool`.
+
+---
+
+## Related pages
+
+- [Provider Tools](./provider-tools.md) — all native provider tools and the
+  type-level guard that prevents pairing a tool with an unsupported model.
+- [Anthropic adapter → `codeExecutionTool`](../adapters/anthropic.md#codeexecutiontool)
+- [OpenAI adapter → `shellTool`](../adapters/openai.md#shelltool)

docs/tools/provider-tools.md

@@ -88,6 +88,15 @@ matrix is maintained alongside `model-meta.ts` and reflected here:
 For the exact per-model list, open the adapter page or read the model's
 `supports.tools` array directly from `model-meta.ts`.
 
+## Provider Skills
+
+Anthropic and OpenAI support hosted, provider-managed skill bundles that run
+inside the provider's server-side sandbox. Skills attach to an execution tool
+(`codeExecutionTool` for Anthropic, `shellTool` for OpenAI) and are referenced
+by ID — the provider handles installation and execution.
+
+See [Provider Skills](./provider-skills.md) for full setup steps and examples.
+
 ## Migrating from earlier versions
 
 If you were using `createWebSearchTool` from `@tanstack/ai-openrouter`, see