본문으로 건너뛰기

에이전트 스킬 (TanStack Intent)

Code Mode 안의 런타임 스니펫을 찾고 있나요? 이는 다른 기능이므로 Code Mode with Snippets을 참고하세요. 이 페이지에서는 코딩 어시스턴트에게 TanStack AI의 작동 방식을 가르치는 Markdown 파일인 에이전트 작성 스킬을 다룹니다.

앱의 모델이 런타임에 SKILL.md 스킬을 로드하게 하려 하나요? 이름이 비슷하지만 이는 다른 기능입니다. 앱 내부 모델을 위한 런타임 카탈로그와 load_skill 도구를 제공하는 Portable Agent Skills를 참고하세요. 이 페이지에서는 _코딩 어시스턴트_에게 TanStack AI 사용 방법을 가르치는 내용만 다룹니다.

1단계: TanStack AI 설치​

아직 설치하지 않았다면 @tanstack/ai와 필요한 어댑터 패키지를 설치합니다. 전체 과정은 Quick Start를 참고하세요.

pnpm add @tanstack/ai

2단계: intent install 실행​

프로젝트 루트에서 다음을 실행합니다.

npx @tanstack/intent@latest install

에이전트 스킬이란 무엇인가요?​

에이전트 스킬은 npm 패키지에 포함되어 배포되는 Markdown 문서(SKILL.md)로, AI 코딩 에이전트에 라이브러리를 올바르게 사용하는 방법, 즉 사용할 함수와 피해야 할 패턴, 각 모듈을 사용해야 하는 시점을 알려줍니다. 이 형식은 Claude Code, Cursor, GitHub Copilot, Codex 등이 지원하는 개방형 표준입니다.

TanStack AI는 패키지 안에 스킬을 배포하므로 지침이 모델의 학습 데이터에 고정되거나 CLAUDE.md에 수동으로 복사되지 않고 npm update와 함께 업데이트됩니다.

TanStack AI가 제공하는 스킬​

패키지스킬학습 내용
@tanstack/aiai-coreuseChat의 채팅 경험과 브라우저 영속성, 도구 호출, 어댑터, 미들웨어, 잠금, 구조화된 출력, 미디어 생성, AG-UI 프로토콜, 사용자 지정 백엔드
@tanstack/ai-persistenceai-persistence서버 채팅 상태(withPersistence), 스토어 계약, 기존 Drizzle, Prisma 또는 Cloudflare D1 설정을 기반으로 앱에 chat-persistence.ts를 작성하는 스택별 레시피
@tanstack/ai-memorytanstack-ai-memorymemoryMiddleware, 회상/저장 어댑터 계약, 인메모리 / Redis / Hindsight / Mem0 / Honcho 어댑터
@tanstack/ai-mcpai-mcpMCP 서버 연결, chat() 내부에서 해당 도구 실행, 리소스, 프롬프트 및 타입 생성 CLI
@tanstack/ai-sandboxai-sandboxdefineSandbox / withSandbox를 사용해 격리된 샌드박스에서 하네스 어댑터 실행
@tanstack/ai-code-modeai-code-mode샌드박스 드라이버로 Code Mode를 설정하고 서버 도구 등록
@tanstack/ai-skillsai-skills런타임의 Portable Agent Skills: withSkills 미들웨어, load_skill, SkillSource 인터페이스, inlineSkill / skillDirectory / staticSkills, 코드가 포함된 스킬을 위한 자체 도구 추가

스킬은 서로 연결됩니다. ai-core는 관련 패키지의 스킬을 가리키며, ai-persistence는 ai-core와 같은 중첩 구조로 skills/ai-persistence/ 아래의 자체 하위 스킬(server, stores, build-{drizzle,prisma,cloudflare,custom}-adapter 레시피)로 연결되는 진입점입니다. 다중 인스턴스 잠금은 가르치는 코드와 함께 제공되므로 ai-core/locks는 withLocks와 함께 @tanstack/ai에 있습니다.

각 스킬은 가르치는 코드와 함께 제공됩니다. 브라우저 영속성은 프레임워크 패키지에 있으므로 ai-core/client-persistence는 @tanstack/ai-persistence가 아니라 @tanstack/ai에 있습니다. 브라우저에만 영속성을 적용하는 앱은 서버 패키지를 설치하지 않습니다.

패키지를 설치하면 각 스킬은 node_modules/<package>/skills/<skill-name>/SKILL.md 아래에 위치합니다.

3단계: 생성된 매핑 검토​

설치 명령은 다음과 같은 intent-skills 블록을 추가하거나 생성합니다.

<!-- intent-skills:start -->
# Skill mappings — when working in these areas, load the linked skill file into context.
skills:
  - task: "Building chat, tool calling, adapters, or streaming with TanStack AI"
    load: "node_modules/@tanstack/ai/skills/ai-core/SKILL.md"
  - task: "Persisting chat state or building a persistence adapter"
    load: "node_modules/@tanstack/ai-persistence/skills/ai-persistence/SKILL.md"
  - task: "Setting up Code Mode with TanStack AI"
    load: "node_modules/@tanstack/ai-code-mode/skills/ai-code-mode/SKILL.md"
<!-- intent-skills:end -->

task: 설명이 실제로 작업하는 영역과 일치하는지 확인합니다. 필요하면 더 구체적으로 조정하거나 표현을 바꿉니다. 에이전트는 이 설명을 바탕으로 스킬을 컨텍스트에 불러올 시점을 결정합니다.

4단계: 연결 확인​

코딩 에이전트에서 새 세션을 열고 TanStack AI를 사용해 무언가를 만들도록 요청합니다. 예를 들면 다음과 같습니다. "@tanstack/ai와 OpenAI 어댑터를 사용해 스트리밍 채팅 엔드포인트를 추가해 줘."

다음과 같은 결과가 나타나야 합니다.

  • 에이전트가 streamText()가 아닌 chat()을 사용합니다.
  • 어댑터를 createOpenAI()가 아닌 @tanstack/ai-openai의 openaiText()로 가져옵니다.
  • 응답을 수동으로 SSE에 연결하지 않고 toServerSentEventsResponse()로 감쌉니다.
  • 수명 주기 이벤트에 미들웨어를 사용합니다(chat()에 onFinish 콜백이 없습니다).

에이전트가 계속 다른 SDK 패턴으로 되돌아가면 구성 파일을 다시 열어 intent-skills 블록이 있고 task: 설명이 요청한 영역을 명확히 다루는지 확인합니다.

스킬 최신 상태 유지​

스킬은 패키지와 함께 버전이 관리됩니다. @tanstack/ai를 업데이트하면 node_modules 아래의 SKILL.md 파일도 함께 업데이트되므로 CLI를 다시 실행할 필요가 없습니다. 새로운 Intent 지원 패키지를 _추가_할 때(예: 나중에 @tanstack/ai-code-mode 추가)나 작업 매핑을 새로 고칠 때만 npx @tanstack/intent@latest install을 다시 실행합니다.

CLI 없이 스킬 사용​

스킬을 직접 연결하려면 에이전트 구성 파일에서 node_modules의 스킬을 직접 참조할 수 있습니다. 에이전트에 필요한 최소 설정은 파일을 가리키는 포인터입니다.

When working on TanStack AI code, read and follow:
node_modules/@tanstack/ai/skills/ai-core/SKILL.md

CLI는 패키지를 자동으로 검색하고 에이전트 스킬 표준과 일관성을 유지하므로 권장되지만, 기반 파일 경로는 안정적입니다.

더 알아보기​