feat(ai): add support for uploading provider skills using the provider references abstraction by felixarntz · Pull Request #12880 · vercel/ai

felixarntz · 2026-02-26T15:38:33Z

Background

#12995 introduced a new concept of provider references for managing uploaded assets to a provider in a container that supports multi-provider references. In #12995, this was implemented for uploading files (e.g. large media) to a provider for referencing it in inference calls.

This PR uses that same approach for uploading skills to a provider with programmatic tool calling. This is currently supported by Anthropic and OpenAI.

Summary

Introduces a new SkillsV4 specification in @ai-sdk/provider for uploading remote skills across providers
Adds new core function uploadSkill in the ai package
Implements SkillsV4 for both @ai-sdk/openai and @ai-sdk/anthropic, including provider-specific API handling
Includes comprehensive unit tests for all new code and example scripts demonstrating basic CRUD and skill-referenced inference for both providers

Manual Verification

Run the new examples included in the PR.

Checklist

Tests have been added / updated (for bug fixes / features)
Documentation has been added / updated (for bug fixes / features)
A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
I have reviewed this pull request (self-review)

Future Work

N/A

Related Issues

Fixes #12855

Related: #12995

Add SkillsManagerV1 interface to @ai-sdk/provider with create, list, retrieve, update, and delete operations. Implement for both OpenAI and Anthropic providers with file upload support via multipart form data. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

OpenAI skill responses return stale name/description after updates. Use the version list endpoint (GET /skills/{id}/versions?order=desc&limit=1) to fetch the latest version metadata for create and retrieve operations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Switch from version list to GET /skills/{id}/versions/{version} using latest_version from the skill response. Enriches create, retrieve, and update with accurate name/description from the version object. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

OpenAI's version list and retrieve endpoints are non-functional (list returns empty data, retrieve returns 404 for all versions). Confirmed via real API testing. Only update can enrich using the version CREATE response metadata. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

This reverts commit 545abdd.

Normalize source to user/provider across spec and providers, re-capture Anthropic/OpenAI fixtures from real APIs, add explanatory comments for non-obvious code paths, and fix OpenAI update to promote default_version via POST. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…external API surface

felixarntz · 2026-02-26T15:48:17Z

+  /**
+   * The content of the file, either as a base64 string or binary data.
+   */
+  content: string | Uint8Array;


For now, this is still using base64 for strings, in alignment with existing types.

However, per the discussion in #12855, this may not be as suitable here, given the content is often Markdown files. A counter-argument would be that skills can still contain binary data, or the entire skill could be a ZIP and no direct Markdown files at all.

But that could still be passed via Uint8Array then. Something to think about further.

Update: I would suggest, we leave it as is for now, mostly for consistency with present expectations. However, we should probably revise how file parts are being sent anyway: Breaking down the existing file type into distinct file-data, file-url, and file-reference types would clarify the API surface and reduce complexity of having to figure out what the overloaded data field actually contains. This would then also allow us to add e.g. file-text (name TBD), which could be used to pass text file contents in plain text instead of base64-encoded.

I think we should make this change as part of v7, which will then alleviate the concern about base64 vs plain text for skills - we'd allow either.

cc @lgrammel

… concept

lgrammel · 2026-04-07T13:00:55Z

+  /**
+   * Optional human-readable title for the uploaded skill.
+   */
+  displayTitle?: string;


is this needed in the result if we have it as part of the params?

I think it's good to have data like this in the result as it allows verifying the actual display name applied. Providers may do some minor sanitization, or they may add a default display name if none is provided.

Additionally, I think it makes sense to return comprehensive information about the created entity, so you don't have to patch this together yourself if you want to further process or store it.

lgrammel

Needs to be added to our documentation

felixarntz · 2026-04-07T14:10:28Z

@lgrammel added a documentation guide for this in c5b6678

vercel-ai-sdk · 2026-04-07T15:56:56Z

🚀 Published in:

Package	Version
`ai`	`7.0.0-beta.69`
`@ai-sdk/alibaba`	`2.0.0-beta.21`
`@ai-sdk/amazon-bedrock`	`5.0.0-beta.25`
`@ai-sdk/angular`	`3.0.0-beta.69`
`@ai-sdk/anthropic`	`4.0.0-beta.21`
`@ai-sdk/assemblyai`	`3.0.0-beta.16`
`@ai-sdk/azure`	`4.0.0-beta.25`
`@ai-sdk/baseten`	`2.0.0-beta.19`
`@ai-sdk/black-forest-labs`	`2.0.0-beta.15`
`@ai-sdk/bytedance`	`2.0.0-beta.15`
`@ai-sdk/cerebras`	`3.0.0-beta.19`
`@ai-sdk/cohere`	`4.0.0-beta.16`
`@ai-sdk/deepgram`	`3.0.0-beta.15`
`@ai-sdk/deepinfra`	`3.0.0-beta.19`
`@ai-sdk/deepseek`	`3.0.0-beta.17`
`@ai-sdk/devtools`	`1.0.0-beta.8`
`@ai-sdk/elevenlabs`	`3.0.0-beta.15`
`@ai-sdk/fal`	`3.0.0-beta.15`
`@ai-sdk/fireworks`	`3.0.0-beta.19`
`@ai-sdk/gateway`	`4.0.0-beta.38`
`@ai-sdk/gladia`	`3.0.0-beta.15`
`@ai-sdk/google`	`4.0.0-beta.29`
`@ai-sdk/google-vertex`	`5.0.0-beta.38`
`@ai-sdk/groq`	`4.0.0-beta.18`
`@ai-sdk/huggingface`	`2.0.0-beta.19`
`@ai-sdk/hume`	`3.0.0-beta.15`
`@ai-sdk/klingai`	`4.0.0-beta.16`
`@ai-sdk/langchain`	`3.0.0-beta.69`
`@ai-sdk/llamaindex`	`3.0.0-beta.69`
`@ai-sdk/lmnt`	`3.0.0-beta.15`
`@ai-sdk/luma`	`3.0.0-beta.15`
`@ai-sdk/mcp`	`2.0.0-beta.20`
`@ai-sdk/mistral`	`4.0.0-beta.17`
`@ai-sdk/moonshotai`	`3.0.0-beta.19`
`@ai-sdk/open-responses`	`2.0.0-beta.16`
`@ai-sdk/openai`	`4.0.0-beta.25`
`@ai-sdk/openai-compatible`	`3.0.0-beta.19`
`@ai-sdk/otel`	`1.0.0-beta.15`
`@ai-sdk/perplexity`	`4.0.0-beta.18`
`@ai-sdk/prodia`	`2.0.0-beta.18`
`@ai-sdk/provider`	`4.0.0-beta.8`
`@ai-sdk/provider-utils`	`5.0.0-beta.14`
`@ai-sdk/react`	`4.0.0-beta.69`
`@ai-sdk/replicate`	`3.0.0-beta.16`
`@ai-sdk/revai`	`3.0.0-beta.16`
`@ai-sdk/rsc`	`3.0.0-beta.70`
`@ai-sdk/svelte`	`5.0.0-beta.69`
`@ai-sdk/togetherai`	`3.0.0-beta.19`
`@ai-sdk/valibot`	`3.0.0-beta.14`
`@ai-sdk/vercel`	`3.0.0-beta.19`
`@ai-sdk/vue`	`4.0.0-beta.69`
`@ai-sdk/xai`	`4.0.0-beta.28`

…r references abstraction (#12880) uploaded assets to a provider in a container that supports multi-provider references. In #12995, this was implemented for uploading files (e.g. large media) to a provider for referencing it in inference calls. This PR uses that same approach for uploading skills to a provider with programmatic tool calling. This is currently supported by Anthropic and OpenAI. - Introduces a new `SkillsV4` specification in `@ai-sdk/provider` for uploading remote skills across providers - Adds new core function `uploadSkill` in the `ai` package - Implements `SkillsV4` for both `@ai-sdk/openai` and `@ai-sdk/anthropic`, including provider-specific API handling - Includes comprehensive unit tests for all new code and example scripts demonstrating basic CRUD and skill-referenced inference for both providers Run the new examples included in the PR. - [x] Tests have been added / updated (for bug fixes / features) - [ ] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) N/A Fixes #12855 Related: #12995 --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

…Skill` as shorthand (#14242) ## Background `uploadFile` and `uploadSkill` required callers to pass the specific sub-interface (`FilesV4` / `SkillsV4`) directly. Since `ProviderV4` already exposes optional `files()` and `skills()` methods returning those interfaces, it's unnecessarily verbose to call `provider.files()` manually before passing it in. It still makes sense as API primitive, but we can make it easier. ## Summary Both `uploadFile` and `uploadSkill` now accept `ProviderV4` as the `api` argument in addition to `FilesV4` / `SkillsV4` respectively. When a provider instance is passed, the SDK automatically resolves the appropriate sub-interface by calling `.files()` or `.skills()`. If the provider doesn't expose the required method, a clear error is thrown. Also adds a general function doc for `uploadSkill` that was missing from #12880. Also renames `SkillsV4`'s `upload` method to `uploadSkill`, for consistency and clarity - this was an oversight in the original PR. ## Manual Verification You can run the new examples for verify the shorthand works. ## Checklist - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Future Work N/A ## Related Issues Follow up to #12995 and #12855

## Summary Fixes the changesets for the following v7 major PRs after the fact to mark them as `major`, for proper referencing in future changelog / docs: - #13352 - #13816 - #12880 - #13553 - #13971 - #14150

felixarntz and others added 14 commits February 25, 2026 20:41

chore: add changeset for remote skills management

545abdd

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Revert "chore: add changeset for remote skills management"

209463f

This reverts commit 545abdd.

changeset

7fd8f9a

prefix provider package skills exports with Experimental_ and reduce …

6fd21de

…external API surface

remove unnecessary files just for result types

8c1bea1

add example that includes skill reference in inference

67f0830

avoid continuing problems with OpenAI skill versions endpoints

2f72b72

fix broken example

9949e05

do not modify ProviderV3 with experimental type

c523ea7

github-actions bot assigned felixarntz Feb 26, 2026

vercel bot deployed to Preview February 26, 2026 15:39 View deployment

felixarntz mentioned this pull request Feb 26, 2026

Add support for creating and managing remote skills (e.g. Anthropic, OpenAI) via abstraction with new top-level API #12855

Closed

felixarntz added 2 commits February 26, 2026 09:46

document SkillsManagerV1 types

454e6fa

include base64 string usage in examples

760dfb2

vercel bot deployed to Preview February 26, 2026 15:48 View deployment

felixarntz commented Feb 26, 2026

View reviewed changes

Merge branch 'main' into remote-skills-management

71eb42d

vercel bot deployed to Preview February 26, 2026 15:50 View deployment

felixarntz added 2 commits March 2, 2026 11:56

Merge branch 'main' into remote-skills-management

9e67e9f

fix OpenAI implementation to propagate version so that updates show up

c8ff0c3

felixarntz added 6 commits April 6, 2026 14:47

align implementation with uploadFile (#12995), use provider reference…

1bf34ed

… concept

fix examples and make them clean up their uploaded skill

fed5995

include latestVersion as top-level field on uploaded skill result

d74ecba

rename old SkillsManager references to simply Skills

fa16c08

refresh changeset

6bb3f32

fix multi-provider uploadSkill example

1ee502b

vercel bot deployed to Preview April 6, 2026 20:54 View deployment

Merge branch 'main' into remote-skills-management

0fbd19c

felixarntz marked this pull request as ready for review April 6, 2026 20:59

vercel bot deployed to Preview April 6, 2026 21:00 View deployment

remove now unnecessary deleteFromApi helper

364e868

felixarntz requested a review from lgrammel April 6, 2026 21:01

felixarntz changed the title ~~feat(ai): add support for creating and managing provider skills~~ feat(ai): add support for uploading provider skills using the provider references abstraction Apr 6, 2026

vercel bot deployed to Preview April 6, 2026 21:02 View deployment

felixarntz added this to the v7.0 milestone Apr 6, 2026

lgrammel reviewed Apr 7, 2026

View reviewed changes

lgrammel approved these changes Apr 7, 2026

View reviewed changes

felixarntz added 2 commits April 7, 2026 08:58

add documentation

c5b6678

Merge branch 'main' into remote-skills-management

37777cc

felixarntz enabled auto-merge (squash) April 7, 2026 14:11

vercel bot deployed to Preview April 7, 2026 14:11 View deployment

felixarntz merged commit 34bd95d into main Apr 7, 2026
18 checks passed

felixarntz deleted the remote-skills-management branch April 7, 2026 14:17

felixarntz mentioned this pull request Apr 8, 2026

feat(ai): allow passing provider instance to uploadFile and uploadSkill as shorthand #14242

Merged

4 tasks

felixarntz mentioned this pull request Apr 10, 2026

chore: fix v7 changesets to mark them as major #14326

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ai): add support for uploading provider skills using the provider references abstraction#12880

feat(ai): add support for uploading provider skills using the provider references abstraction#12880
felixarntz merged 35 commits intomainfrom
remote-skills-management

felixarntz commented Feb 26, 2026 •

edited

Loading

Uh oh!

felixarntz Feb 26, 2026

Uh oh!

felixarntz Apr 6, 2026

Uh oh!

lgrammel Apr 7, 2026

Uh oh!

felixarntz Apr 7, 2026

Uh oh!

lgrammel left a comment

Uh oh!

felixarntz commented Apr 7, 2026

Uh oh!

Uh oh!

vercel-ai-sdk bot commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

felixarntz commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Summary

Manual Verification

Checklist

Future Work

Related Issues

Uh oh!

felixarntz Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

felixarntz Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

lgrammel Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

felixarntz Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

lgrammel left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz commented Apr 7, 2026

Uh oh!

Uh oh!

vercel-ai-sdk bot commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

felixarntz commented Feb 26, 2026 •

edited

Loading