Skill 업로드

Skill 업로드 (Skill Uploads)

AI SDK는 uploadSkill 함수를 제공해 커스텀 스킬을 프로바이더에 업로드하고, 이후 추론 호출에 전달할 수 있는 ProviderReference 를 받아요.

스킬(skill) 은 프로바이더가 로드할 수 있는 파일 묶음(예: 스킬 동작을 설명하는 SKILL.md)이에요. 예를 들어 sandboxed 컨테이너 환경에서요.

AI SDK에서 업로드된 스킬은 ProviderReference — 프로바이더 이름을 프로바이더 특화 식별자에 매핑하는 Record<string, string> — 로 식별돼요. 이 개념은 업로드된 미디어 파일 같은 다른 프로바이더 특화 자산 참조에도 사용돼요.

import { uploadSkill, generateText } from 'ai';
import {
  anthropic,
  type AnthropicLanguageModelOptions,
} from '@ai-sdk/anthropic';
import { readFileSync } from 'fs';

const { providerReference } = await uploadSkill({
  api: anthropic.skills(),
  files: [
    {
      path: 'my-skill/SKILL.md',
      content: readFileSync('./SKILL.md'),
    },
  ],
  displayTitle: 'My Skill',
});

const { text } = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools: {
    code_execution: anthropic.tools.codeExecution_20260120(),
  },
  prompt: 'Use the skill to complete the task.',
  providerOptions: {
    anthropic: {
      container: {
        skills: [{ type: 'custom', providerReference }],
      },
    } satisfies AnthropicLanguageModelOptions,
  },
});

.skills() 를 명시적으로 호출하는 대신 api 에 프로바이더 인스턴스를 직접 전달할 수도 있어요. SDK가 .skills() 를 대신 호출해 주죠:

const { providerReference } = await uploadSkill({
  api: anthropic, // shorthand for anthropic.skills()
  files: [{ path: 'my-skill/SKILL.md', content: readFileSync('./SKILL.md') }],
  displayTitle: 'My Skill',
});

출처: 문서

본문

스킬 파일 (Skill Files)

스킬은 하나 이상의 파일로 구성되며, 각 파일은 상대 path 와 content 를 가져요. 파일 콘텐츠는 Uint8Array(예: fs.readFileSync 에서) 또는 base64 인코딩 문자열로 제공할 수 있어요:

const { providerReference } = await uploadSkill({
  api: openai.skills(),
  files: [
    {
      path: 'my-skill/SKILL.md',
      content: readFileSync('./SKILL.md'), // Uint8Array
    },
    {
      path: 'my-skill/helper.py',
      content: readFileSync('./helper.py'),
    },
  ],
});

업로드 결과 (Upload Result)

uploadSkill 은 다음 필드를 가진 UploadSkillResult 를 반환해요:

Field Type Description
providerReference ProviderReference 프로바이더 이름을 프로바이더 특화 스킬 ID에 매핑
displayTitle string? 사람이 읽을 수 있는 제목 (지원되고 제공되면)
name string? 프로바이더가 스킬 파일에서 추론한 이름
description string? 프로바이더가 스킬 파일에서 추론한 설명
latestVersion string? 프로바이더가 할당한 최신 버전 식별자
providerMetadata object? 추가 프로바이더 특화 메타데이터 (예: 타임스탬프)
warnings Warning[] 지원되지 않는 옵션에 대한 경고 (예: OpenAI에서 displayTitle)

프로바이더 참조 (Provider References)

ProviderReference 는 프로바이더 이름을 프로바이더 특화 스킬 식별자에 매핑하는 Record<string, string> 이에요:

// Example ProviderReference
{
  anthropic: 'skill_abc123',
}

추론 중에 스킬을 참조할 때 providerReference 를 전달하세요. 각 프로바이더는 참조에서 자신의 스킬 ID를 찾아요. 현재 프로바이더에 대한 항목이 없으면 오류가 throw돼요.

다중 프로바이더 사용법 (Multi-Provider Usage)

같은 스킬을 여러 프로바이더에서 사용하려면 각각에 업로드하고 참조를 병합하세요:

const [openaiUpload, anthropicUpload] = await Promise.all([
  uploadSkill({
    api: openai.skills(),
    files: [{ path: 'my-skill/SKILL.md', content: skillSource }],
  }),
  uploadSkill({
    api: anthropic.skills(),
    files: [{ path: 'my-skill/SKILL.md', content: skillSource }],
    displayTitle: 'My Skill',
  }),
]);

const mergedReference = {
  ...openaiUpload.providerReference,
  ...anthropicUpload.providerReference,
};

// mergedReference: { openai: 'sk_...', anthropic: 'sk_...' }

병합된 참조는 어떤 프로바이더가 요청을 처리하든 추론 호출에서 사용할 수 있어요. 각 프로바이더가 자신의 스킬 ID를 찾을 거예요.

추론 호출에서 스킬 사용하기 (Using Skills in Inference Calls)

스킬을 추론 호출에 첨부하는 방법은 프로바이더에 따라 달라요.

Anthropic

providerOptions 의 container.skills 배열 안에 providerReference 를 전달하세요:

await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools: {
    code_execution: anthropic.tools.codeExecution_20260120(),
  },
  prompt: '...',
  providerOptions: {
    anthropic: {
      container: {
        skills: [{ type: 'custom', providerReference }],
      },
    } satisfies AnthropicLanguageModelOptions,
  },
});

OpenAI

shell tool의 environment.skills 배열 안에 providerReference 를 전달하세요:

await generateText({
  model: openai.responses('gpt-6-astra'),
  tools: {
    shell: openai.tools.shell({
      environment: {
        type: 'containerAuto',
        skills: [{ type: 'skillReference', providerReference }],
      },
    }),
  },
  prompt: '...',
});

지원되는 프로바이더 (Supported Providers)

다음 프로바이더가 skills() 와 스킬 업로드를 지원해요:

Provider Factory Method
Anthropic anthropic.skills()
OpenAI openai.skills()

더 알아보기 (Learn more)

전체 사이트맵