add-provider-package

add-provider-package 스킬 개요

add-provider-package 스킬은 vercel/ai 안에 새로운 @ai-sdk/<provider> 패키지를 만들기 위한 집중형 구현 가이드입니다. 모델 제공자를 AI SDK에 통합하면서 패키지 구조, 어댑터 레이어 구성, 저장소 관례까지 제대로 맞추고 싶은 유지보수자, 외부 기여자, API 플랫폼 팀에 특히 잘 맞습니다.

add-provider-package가 실제로 도와주는 일

실제 해야 할 일은 단순히 “래퍼 코드를 몇 줄 쓰는 것”이 아닙니다. add-provider-package 스킬은 AI SDK의 내부 아키텍처에 맞는 provider 패키지를 추가하고, 기대되는 provider 표면을 export하며, 이 저장소의 패키지 레이아웃, 테스트 전략, 구현 패턴을 따르도록 도와줍니다.

add-provider-package를 써야 하는 사람

다음에 해당한다면 add-provider-package 스킬을 사용하는 것이 좋습니다.

• vercel/ai 모노레포에 새로운 모델 provider를 추가하려는 경우
• 퍼스트파티 패키지를 본떠 서드파티 provider 패키지를 만들려는 경우
• 외부 API를 AI SDK의 language model, embeddings 같은 추상화에 매핑하려는 경우
• “어댑터를 만들어라” 수준의 일반론이 아니라, 실제로 따라갈 수 있는 구체적 경로가 필요한 경우

특히 provider의 HTTP API 자체는 이미 이해하고 있지만, 그것을 AI SDK 패키지 관례로 어떻게 번역해야 할지 도움이 필요할 때 유용합니다.

add-provider-package가 가장 잘 맞는 사용 사례

add-provider-package 스킬은 특히 다음이 필요할 때 강합니다.

• 기대되는 구조를 갖춘 새로운 packages/<provider> 폴더를 만들 때
• @ai-sdk/provider 인터페이스에 맞춰 provider 클래스를 구현할 때
• 스스로 구조를 발명하기보다 기존 provider 패키지 패턴을 재사용하고 싶을 때
• 시간을 본격적으로 투자하기 전에 퍼스트파티와 서드파티의 기대치 차이를 이해하고 싶을 때

일반적인 코딩 프롬프트와 다른 핵심 차별점

일반적인 프롬프트도 어댑터 코드를 초안 수준으로 만들어줄 수는 있습니다. 하지만 add-provider-package는 저장소 맥락을 아는 가이드가 필요할 때 더 큰 가치가 있습니다. 예를 들어 패키지가 어디에 위치해야 하는지, provider 아키텍처가 어떤 레이어로 나뉘는지, 보통 어떤 파일들이 존재하는지, 그리고 이 코드베이스에서 “완성된 provider 패키지”가 어떤 모습이어야 하는지까지 안내합니다.

도입 전에 알아야 할 가장 중요한 제약

이 스킬은 의도적으로 범위가 좁습니다. 대상은 @ai-sdk/<provider> 패키지 생성이지, 범용 API SDK 설계나 무관한 래퍼, 임의의 플러그인 시스템이 아닙니다. 목표가 AI SDK provider 아키텍처 밖에 있다면, 이 스킬은 지나치게 세부적이라고 느껴질 수 있습니다.

add-provider-package 스킬 사용 방법

add-provider-package 설치 맥락

이 스킬은 vercel/ai의 skills/add-provider-package 아래에 있습니다. Skills 지원 워크플로에서는 다음으로 설치할 수 있습니다.

npx skills add vercel/ai --skill add-provider-package

환경에서 저장소 스킬을 이미 자동으로 노출한다면, 스킬 이름만 호출해도 충분할 수 있습니다.

가장 먼저 봐야 할 핵심 파일 하나부터 시작하기

먼저 skills/add-provider-package/SKILL.md를 읽으세요. 이 저장소 스냅샷 기준으로, 스킬의 핵심 가이드는 여기에 집중되어 있습니다. 포함 내용은 다음과 같습니다.

• 퍼스트파티와 서드파티 패키지의 기대치 차이
• 레이어드 provider 아키텍처
• 패키지 구조
• 단계별 구현 가이드
• 완성형 예시를 볼 수 있는 참조 PR

여기서는 추가 resources/, rules/, 헬퍼 스크립트가 별도로 드러나지 않기 때문에, 실질적으로 유용한 신호는 대부분 SKILL.md와 모노레포 내 기존 provider 패키지들에 있습니다.

add-provider-package에 제공해야 할 입력

유의미한 결과를 얻으려면 “X 지원 추가해줘” 같은 수준이 아니라, provider의 구체적인 정보를 줘야 합니다. 최소한 다음 정도는 있어야 도움이 됩니다.

• provider 이름과 패키지 대상(예: @ai-sdk/acme)
• API 인증 방식
• 지원 모델 유형: chat, completion, embeddings, image 등
• 스트리밍 동작 방식
• 요청/응답 스키마
• 에러 포맷과 rate-limit 동작
• tool calling, JSON mode 차이 같은 provider별 특이사항

이 정보가 없으면 스킬은 구조를 개괄하는 수준까진 가능하지만, 어댑터를 신뢰성 있게 설계하긴 어렵습니다.

거친 목표를 강한 프롬프트로 바꾸기

약한 프롬프트:

Use add-provider-package to add Acme AI to the SDK.

더 강한 프롬프트:

Use add-provider-package to scaffold a new packages/acme provider for vercel/ai. Acme uses API key auth via Authorization: Bearer <key>. It supports text generation and embeddings, with SSE streaming for text. I need the package structure, main source files, likely exports, and the mapping from Acme endpoints to AI SDK model interfaces. Show the repo files I should create first and call out any ambiguous areas I must resolve from the API docs.

이 프롬프트가 더 잘 작동하는 이유는, 스킬이 올바른 provider 표면을 고르고 아직 해결되지 않은 통합 리스크를 초기에 드러내기에 충분한 정보를 제공하기 때문입니다.

add-provider-package 사용 시 추천 워크플로

실무적으로는 add-provider-package usage를 다음 순서로 진행하는 것이 좋습니다.

1. 대상이 퍼스트파티 패키지인지 서드파티 패키지인지 확인합니다.
2. 아키텍처와 기대 패키지 레이아웃을 이해하기 위해 SKILL.md를 읽습니다.
3. 연결된 참조 예시 PR https://github.com/vercel/ai/pull/8136/files를 확인합니다.
4. packages/ 안의 기존 provider 패키지 한두 개와 비교합니다.
5. 파일 생성을 시키기 전에, provider API를 AI SDK 인터페이스에 어떻게 매핑할지 먼저 스킬에 요청합니다.
6. 그다음 패키지 스켈레톤, 구현 계획, 테스트 체크리스트를 요청합니다.

이 순서는 코드 생성 전에 인터페이스 불일치를 먼저 잡아낼 수 있어 재작업을 줄여줍니다.

SKILL.md 다음으로 확인할 저장소 경로

실제 구현 결정을 내려야 한다면, 보통 다음 순서로 읽는 것이 가장 좋습니다.

• skills/add-provider-package/SKILL.md
• 스킬 내부에 링크된 참조 PR
• 모노레포의 기존 packages/<provider>/src/* 구현
• @ai-sdk/provider의 공용 인터페이스
• @ai-sdk/provider-utils의 헬퍼 패턴

스킬 자체가 이 레이어드 아키텍처를 명시적으로 설명하므로, 생성된 코드가 현재 저장소 패턴과 맞는지 검증하려면 이 영역들을 직접 읽어보는 것이 가장 정확합니다.

add-provider-package가 잘 커버하는 범위

add-provider-package guide는 특히 다음에 유용합니다.

• 패키지 스캐폴딩
• AI SDK 내부에서의 아키텍처 적합성
• 어떤 provider 인터페이스가 중요한지 식별
• provider를 독자적인 클라이언트가 아니라 어댑터로 모델링하는 방법 이해
• 기존 provider 추가 사례를 참조 구현으로 활용

add-provider-package가 대신 결정해주지 않는 것

이 스킬이 있다고 해서 upstream provider API 문서를 해석할 필요가 사라지지는 않습니다. 여전히 다음은 직접 결정해야 합니다.

• 어떤 기능을 first-class 지원 대상으로 둘 것인지
• provider 전용 요청 옵션을 어떻게 처리할지
• 어떤 모델을 노출할지
• 비표준 에러와 스트리밍 payload를 어떻게 번역할지
• 지원하지 않는 기능은 생략할지, 아니면 provider 전용 옵션 뒤에 숨겨 노출할지

API 개발을 위한 add-provider-package 실전 프롬프트 패턴

add-provider-package for API Development 용도로 쓴다면, 출력도 의사결정 순서대로 요청하는 것이 좋습니다.

1. 기능 매핑
2. 패키지/파일 계획
3. 타입/인터페이스 계획
4. 요청/응답 변환 계획
5. 테스트와 엣지 케이스

예시:

Use add-provider-package to plan an @ai-sdk/zen package. First, map Zen's endpoints to AI SDK interfaces. Second, propose the package file tree. Third, list the core transforms for text generation, embeddings, and streaming. Finally, list the top 10 edge cases to test.

이렇게 하면 처음부터 전체 코드를 한 번에 뽑아달라고 하는 것보다 실제 구현 가능한 결과를 얻기 쉽습니다.

코딩 전에 자주 막히는 지점

가장 큰 장애물은 대개 문법 오류가 아니라, 빠진 제품 결정입니다.

• 이것이 퍼스트파티로 들어갈 예정인가, 서드파티인가?
• provider API가 실제로 AI SDK 추상화에 자연스럽게 맞아떨어지는가?
• 스트리밍 이벤트가 어댑터로 감쌀 만큼 충분히 안정적인가?
• 어떤 모델 기능이 외부에 노출할 만큼 성숙했는가?
• 형태가 더 비슷한 기존 provider가 있어서 그쪽을 복사하는 편이 나은가?

패키지를 만들기 전에 이런 질문이 먼저 드러나도록, 초반부터 스킬을 활용하는 것이 좋습니다.

add-provider-package 스킬 FAQ

add-provider-package는 Vercel 유지보수자만 위한 건가요?

아닙니다. 외부 기여자와 서드파티 패키지 작성자에게도 유용합니다. 원문에서도 서드파티 패키지와 퍼스트파티 @ai-sdk/<provider> 패키지를 명확히 구분하고 있으며, 퍼스트파티 추가는 먼저 논의해야 한다고 안내합니다.

add-provider-package는 초보자에게도 괜찮나요?

대상 provider의 API를 이미 이해하고 있는 초보자라면 사용할 수 있습니다. 다만 TypeScript, 패키지 퍼블리싱, SDK 설계를 처음부터 가르치는 입문형 튜토리얼은 아닙니다. 이 스킬의 진짜 가치는 저장소 특화 가이드와 아키텍처 적합성에 있습니다.

LLM에게 provider wrapper를 만들어 달라고 하는 것과 무엇이 다른가요?

일반 프롬프트는 그럴듯한 코드를 생성할 수는 있어도, AI SDK의 패키지 구조나 인터페이스와 맞지 않을 가능성이 큽니다. 반면 add-provider-package 스킬은 작업을 모노레포의 어댑터 아키텍처에 고정시키고, 실제로 참고할 수 있는 구체적인 참조 구현까지 안내합니다.

vercel/ai 저장소 밖에서도 add-provider-package를 쓸 수 있나요?

네, 패턴 참조용으로는 가능합니다. 다만 프로젝트가 AI SDK의 provider 추상화와 패키지 레이아웃에 가까울수록 결과도 더 그대로 옮겨 쓰기 좋습니다. 코드베이스의 인터페이스나 퍼블리싱 관례가 다르다면, 그만큼 추가 적응 작업이 필요하다고 보는 편이 맞습니다.

언제 add-provider-package를 쓰지 않는 게 좋나요?

다음에 해당한다면 건너뛰는 편이 낫습니다.

• 범용 API 클라이언트를 만드는 경우
• AI SDK 모델 구조 밖에서 provider를 통합하는 경우
• provider 패키지 코드가 아니라 프런트엔드 앱 예제를 찾는 경우
• 동등한 수준을 맞추기 위해 기존 provider 구현을 직접 확인할 준비가 안 된 경우

add-provider-package에는 완전한 end-to-end 예시가 포함되어 있나요?

완성된 provider 추가 사례를 보여주는 PR 참조가 포함되어 있습니다: https://github.com/vercel/ai/pull/8136/files. 이 부분은 스킬에서 가장 가치 있는 요소 중 하나인데, 실제 맥락 속에서 “완료된 추가 작업”이 어떤 모습인지 보여주기 때문입니다.

add-provider-package 스킬을 더 잘 활용하는 방법

add-provider-package에 기능 단위 입력을 구체적으로 주기

출력 품질을 가장 빨리 끌어올리는 방법은 provider 기능을 정확하게 설명하는 것입니다. “chat 지원”이라고만 하지 말고, 다음처럼 구체적으로 주세요.

• 엔드포인트 이름
• 스트리밍 프로토콜
• tool calling 지원 여부
• structured output 동작
• embeddings 차원 수 또는 요청 형식
• 인증과 헤더
• 재시도나 rate-limit 관련 특이점

이렇게 해야 스킬이 마케팅 용어를 보고 추측하는 대신, 인터페이스 적합성을 실제로 판단할 수 있습니다.

코드 생성 전에 갭 분석부터 요청하기

좋은 첫 단계는 다음과 같습니다.

Use add-provider-package to identify the gaps between this provider API and AI SDK expectations before proposing code.

바로 스캐폴딩을 요청하는 것보다 이 방식이 더 나은 경우가 많습니다. 빠진 기능, 호환되지 않는 스트리밍 포맷, provider 전용 옵션이 필요한 영역을 먼저 드러내주기 때문입니다.

비슷한 기존 provider를 참조 대상으로 지정하기

vercel/ai 안에서 API 형태가 비슷한 provider를 알고 있다면, 그 사실을 프롬프트에 명시하세요. 예를 들면:

Use add-provider-package and model this after the provider package that has the closest SSE text streaming and embeddings support.

이렇게 하면 일관성이 높아지고, 불필요하게 새로운 추상화를 만들어낼 가능성도 줄어듭니다.

한 번에 거대한 초안보다 파일 단위 출력 요청하기

다음처럼 쪼개서 요청하면 add-provider-package 결과를 검증하기가 훨씬 쉬워집니다.

• package tree
• src/index.ts exports
• provider factory
• model implementation files
• tests
• package metadata

패키지 전체를 한 번에 생성하는 것보다, 이런 방식이 검토 신뢰도가 더 높습니다.

add-provider-package 사용 시 자주 발생하는 실패 패턴

add-provider-package 결과를 검토할 때는 특히 다음을 확인하세요.

• 아직 안정적이지 않은 기능이 지원되는 것처럼 노출되는지
• 스트리밍이 지나치게 낙관적으로 매핑되지는 않았는지
• provider 전용 옵션이 범용 인터페이스로 새어 나오지 않는지
• 에러 정규화가 빠져 있지 않은지
• 패키지 구조가 기존 저장소 관례와 어긋나지 않는지
• 퍼스트파티와 서드파티의 프로세스 차이를 무시한 코드는 아닌지

구체적인 API 샘플로 프롬프트 개선하기

첫 결과가 너무 추상적이라면, provider 문서에서 실제 요청/응답 샘플을 추가하세요. 이것은 가장 효과가 큰 개선책 중 하나입니다. provider 패키지의 성패는 결국 변환 로직의 정확도에 달려 있기 때문입니다.

좋은 후속 프롬프트 예시:

Here are the exact JSON request and SSE response shapes for text generation. Revise the add-provider-package plan so the model implementation and streaming parser match these payloads.

미해결 결정을 명시적으로 분리해 반복하기

첫 번째 결과를 받은 뒤에는 스킬에 다음 항목을 구분해서 정리해 달라고 요청하세요.

• 확실한 구현 단계
• 가정
• provider 문서 확인이 필요한 열린 질문
• 가능성이 높은 테스트 항목

이 구조는 스킬 결과를 더 실행 가능하게 만들고, 숨어 있는 추측을 줄여줍니다.

add-provider-package 출력 검증의 가장 좋은 방법

출력을 “저장소 맥락을 반영한 구현 계획”으로 받아들이고, 다음과 대조해 검증하세요.

• SKILL.md
• 링크된 참조 PR
• 기존 provider 패키지 한두 개
• @ai-sdk/provider 인터페이스
• 대상 provider의 공식 API 문서

이 검증 루프가 있어야 add-provider-package usage가 단순한 “도움 되는 초안” 수준을 넘어, 실제로 merge하거나 publish할 수 있는 패키지로 발전합니다.