Provider 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-snippets, whose snippets are TypeScript functions your application generates and runs in its own Code Mode sandbox (a local JS isolate). 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

shell

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.

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

shell

npm install @tanstack/ai-openai

2. Add the shellTool with skills

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'.