TanStack Intent: 라이브러리와 함께 배포하는 에이전트 스킬

TanStack Intent: 라이브러리와 함께 배포하는 에이전트 스킬

AI 에이전트에게 라이브러리를 다루는 코드를 맡겼다가 한숨을 쉬어 본 적 있으신가요? 분명 최신 버전을 설치했는데 2년 전에 사라진 API를 자신 있게 써 놓거나, 이름만 남고 시그니처가 바뀐 함수를 옛날 방식으로 호출해 놓는 경우 말입니다.

모델이 게을러서가 아닙니다. 학습 데이터에 남은 옛 코드와 지금 node_modules에 설치된 코드가 다를 뿐이죠. 문제는 에이전트가 그 차이를 알 방법이 마땅치 않다는 데 있습니다.

TanStack Intent는 이 간극을 조금 색다른 방식으로 메웁니다. 문서를 어딘가에 잘 정리해 두고 에이전트가 찾아오길 기다리는 대신, 라이브러리를 만드는 쪽이 사용 설명서를 npm 패키지 안에 넣어서 함께 배포하게 합니다.

문서 링크만으로는 부족합니다

지금까지 이 문제를 다루던 방식은 대체로 셋 중 하나였습니다.

우선 AGENTS.md에 공식 문서 URL을 적어 두는 방법이 있습니다. 간단하지만 에이전트가 그 링크를 실제로 열어 볼지는 운에 맡겨야 하고, 열더라도 문서 사이트는 보통 최신 버전 기준이라 내가 쓰는 버전과 어긋납니다.

다음으로 문서를 통째로 프로젝트에 복사해 두기도 합니다. 확실하긴 한데 라이브러리를 올릴 때마다 사람이 직접 갱신해야 하고, 대개는 그 사실을 잊습니다.

마지막으로 문서 검색용 MCP 서버를 붙이는 방법도 있죠. 이건 꽤 잘 동작하지만 서버를 띄우고 연결해야 하며, 무엇보다 내가 설치한 버전이 아니라 최신 문서를 돌려주는 경우가 많습니다.

셋 다 공통점이 있습니다. 라이브러리 사용자가 뭔가를 챙겨야 한다는 것, 그리고 설명이 코드와 따로 논다는 것입니다.

스킬을 패키지에 담아 보냅니다

TanStack Intent의 접근은 반대 방향입니다. 에이전트 스킬(Agent Skills)을 라이브러리 저장소 안에 작성해 두고, npm에 배포할 때 패키지에 함께 실어 보냅니다.

구조는 단순합니다. 패키지 루트에 skills/ 디렉토리를 만들고, 그 아래 각 스킬을 하위 디렉토리로 두고 SKILL.md 파일을 넣으면 끝입니다. 별도의 레지스트리도, 데이터베이스도 없습니다. 그냥 npm 패키지에 들어가는 평범한 파일입니다.

그래서 사용자는 아무것도 하지 않아도 됩니다. bun add로 라이브러리를 설치하는 순간 그 버전에 맞는 설명서가 node_modules 안에 이미 들어와 있으니까요.

설치된 패키지에서 스킬 찾기

실제로 어떻게 보이는지 확인해 보겠습니다. 빈 프로젝트에 스킬을 제공하는 라이브러리를 하나 설치해 봤습니다.

bun add @tanstack/db

설치가 끝난 뒤 list 명령을 실행하면 프로젝트 안에서 스킬을 가진 패키지를 찾아 줍니다.

bunx @tanstack/intent@latest list
결과
PACKAGE       SOURCE  VERSION  SKILLS
───────────────────────────────────────
@tanstack/db  local   0.6.17   7

Skills:

  @tanstack/db
    db-core                 [core]        TanStack DB core concepts: createCollection with ...
      Load: bunx @tanstack/intent@latest load @tanstack/db#db-core
      collection-setup      [sub-skill]   Creating typed collections with createCollection. ...
        Load: bunx @tanstack/intent@latest load @tanstack/db#db-core/collection-setup
      live-queries          [sub-skill]   Query builder fluent API: from, where, join, ...
        Load: bunx @tanstack/intent@latest load @tanstack/db#db-core/live-queries
      mutations-optimistic  [sub-skill]   collection.insert, collection.update (Immer-style ...
        Load: bunx @tanstack/intent@latest load @tanstack/db#db-core/mutations-optimistic
    meta-framework          [composition] Integrating TanStack DB with meta-frameworks ...
      Load: bunx @tanstack/intent@latest load @tanstack/db#meta-framework

패키지 하나에 스킬이 7개 들어 있고, 평평하게 나열된 게 아니라 계층을 이룹니다. core가 입구 역할을 하고 그 아래 sub-skill이 세부 주제를 맡으며, 여러 도구를 엮는 내용은 composition으로 따로 빠져 있죠.

이렇게 층을 나눠 둔 이유는 컨텍스트에 있습니다. 라이브러리 문서 전체를 한 번에 밀어 넣으면 정작 작업에 필요한 정보가 묻혀 버립니다. 컬렉션을 만드는 작업이면 collection-setup만, 쿼리를 짜는 작업이면 live-queries만 읽으면 되죠.

필요한 스킬만 골라 읽기

load 명령은 지정한 스킬의 SKILL.md를 그대로 출력합니다.

bunx @tanstack/intent@latest load "@tanstack/db#db-core"
결과 (앞부분)
---
name: db-core
description: >
  TanStack DB core concepts: createCollection with queryCollectionOptions,
  electricCollectionOptions, powerSyncCollectionOptions, rxdbCollectionOptions,
  ...
type: core
library: db
library_version: '0.6.0'
---

# TanStack DB — Core Concepts

TanStack DB is a reactive client-side data store. It loads data into typed
collections from any backend (REST APIs, sync engines, local storage), provides
sub-millisecond live queries via differential dataflow, and supports instant
optimistic mutations with automatic rollback.

frontmatter의 library_version을 눈여겨보세요. 이 스킬이 어느 버전을 기준으로 쓰였는지가 파일 안에 박혀 있습니다.

라이브러리와 설명서가 같은 패키지에 들어 있으니 버전이 어긋날 수가 없습니다. 0.6.17을 설치했으면 0.6.x 기준으로 쓰인 스킬이 따라오고, 나중에 0.7.0으로 올리면 그때 갱신된 스킬이 함께 옵니다. 사람이 문서를 다시 복사해 올 필요도, 에이전트가 어느 버전 문서를 봐야 할지 고민할 필요도 없습니다.

에이전트에게 규칙 알려주기

스킬이 node_modules에 있어도 에이전트가 스스로 찾아 읽지는 않습니다. install 명령이 그 안내문을 에이전트 설정 파일에 넣어 줍니다.

bunx @tanstack/intent@latest install
결과
Created AGENTS.md with skill loading guidance.
Tip: Keep the intent-skills block near the top of AGENTS.md so agents read it before task-specific instructions.

만들어진 AGENTS.md를 열어 보면 이런 블록이 들어 있습니다.

AGENTS.md
<!-- intent-skills:start -->
## Skill Loading

Before editing files for a substantial task:
- Run `bunx @tanstack/intent@latest list` from the workspace root to see available local skills.
- If a listed skill matches the task, run `bunx @tanstack/intent@latest load <package>#<skill>` before changing files.
- Use the loaded `SKILL.md` guidance while making the change.
<!-- intent-skills:end -->

주석으로 시작과 끝을 표시해 둔 덕분에 나중에 다시 실행해도 이 블록만 갈아 끼웁니다. AGENTS.md에 직접 적어 둔 다른 규칙은 건드리지 않죠.

스킬을 만들어 배포하기

여기까지가 라이브러리를 쓰는 쪽 이야기였다면, 이제 만드는 쪽 차례입니다. 간단한 UI 라이브러리를 가정하고 스킬을 하나 붙여 보겠습니다.

패키지 루트에 skills/getting-started/SKILL.md를 만듭니다.

skills/getting-started/SKILL.md
---
name: getting-started
description: Sparkle UI의 Button 컴포넌트를 설치하고 사용하는 방법. 버튼, 아이콘 버튼, 로딩 상태를 다룰 때 사용한다.
---

# Sparkle UI 시작하기

## Button 사용법

```tsx
import { Button } from "sparkle-ui";

<Button variant="primary" loading={false}>
  저장
</Button>;
```

description을 성의 없이 쓰면 안 됩니다. 에이전트는 이 문장만 보고 지금 하는 작업에 이 스킬이 필요한지 판단하기 때문에, 어떤 상황에서 읽어야 하는지가 드러나야 합니다.

작성했으면 validate로 검사합니다.

bunx @tanstack/intent@latest validate
결과
✅ Validated 1 skill files — all passed

Warnings:
  ⚠ @tanstack/intent is not in devDependencies
  ⚠ Missing "tanstack-intent" in keywords array

형식은 통과했지만 배포 준비가 덜 됐다고 알려 주네요. keywords가 필요한 이유는 npm에서 스킬을 제공하는 패키지를 검색할 수 있게 하기 위해서입니다.

이런 설정은 손으로 고치지 않아도 됩니다.

bunx @tanstack/intent@latest edit-package-json
결과
✓ Added keywords: "tanstack-intent"
✓ Added files: "skills"
✓ Added files: "!skills/_artifacts"

package.json을 열어 보면 세 항목이 들어가 있습니다.

package.json
{
  "name": "sparkle-ui",
  "version": "1.2.0",
  "keywords": ["tanstack-intent"],
  "files": ["skills", "!skills/_artifacts"]
}

files에 skills를 넣어야 npm 배포본에 실제로 포함되고, !skills/_artifacts는 빌드 과정에서 생기는 중간 산출물을 제외합니다. 이제 평소처럼 npm publish만 하면 됩니다.

스킬도 낡습니다

문서를 코드 옆에 두면 좋은 점이 하나 더 있습니다. 코드가 바뀌었는데 설명이 그대로인 상황을 자동으로 잡아낼 수 있죠.

bunx @tanstack/intent@latest stale
결과
sparkle-ui
  All skills up-to-date

setup 명령으로 GitHub Actions 워크플로 템플릿을 받아 두면 이 검사를 CI에서 돌릴 수 있습니다. 소스가 바뀌었는데 스킬을 손대지 않은 PR에서 경고가 뜨는 식이라, 문서가 조용히 낡아 가는 흔한 문제를 막아 줍니다.

스킬을 처음부터 사람이 다 쓸 필요도 없습니다. meta 명령을 실행하면 메인테이너를 돕는 메타 스킬 목록이 나옵니다.

결과
Meta-skills (for library maintainers):

  domain-discovery             Analyze library documentation and source code, then inter...
  generate-skill               Generate a complete SKILL.md file for a library from sour...
  skill-staleness-check        Evaluate intent skills for staleness when source files ch...
  tree-generator               Generate, update, and version a complete skill tree (coll...

에이전트에게 이 스킬을 읽히고 “우리 라이브러리 스킬 트리를 만들어 줘”라고 시키는 구조입니다. 스킬을 만드는 방법을 스킬로 배포한다는 점이 재미있는데요. 소스 코드와 문서를 읽어 초안을 뽑아 주니 백지에서 시작하는 부담이 확 줄어듭니다.

이름과 달리 TanStack 전용이 아닙니다

TanStack이 만들었다고 해서 TanStack 라이브러리에서만 쓰는 물건은 아닙니다. npm에서 tanstack-intent 키워드로 검색하면 이런 이름들이 나옵니다.

npm search "keywords:tanstack-intent"
결과 (일부)
@reduxjs/toolkit 2.12.0
@trpc/client 11.18.0
@apollo/client 4.2.9
@trpc/server 11.18.0
@tanstack/db 0.6.17
@electric-sql/client 1.5.24
trigger.dev 4.5.9

Redux Toolkit, tRPC, Apollo Client처럼 TanStack과 무관한 라이브러리들이 이미 스킬을 함께 배포하고 있습니다. 스킬 형식 자체가 특정 벤더에 묶이지 않은 개방형 표준을 따르기 때문에 가능한 일입니다.

이 지점이 skills.sh 같은 공개 스킬 디렉토리와 갈리는 부분이기도 합니다. 공개 디렉토리는 스킬을 찾아서 설치하는 쪽에 초점이 있고, Intent는 라이브러리를 배포하는 쪽이 스킬을 함께 실어 보내는 데 초점이 있습니다. 전자는 내가 필요한 스킬을 골라 오는 구조고, 후자는 라이브러리를 설치하면 딸려 오는 구조죠.

마치며

TanStack Intent가 푸는 문제는 결국 하나입니다. 라이브러리 사용법을 아는 사람은 그 라이브러리를 만든 사람인데, 정작 그 지식이 에이전트에게 닿는 경로가 없었다는 것입니다.

해법도 단순합니다. 새로운 프로토콜이나 서버 대신 npm 패키지 안에 마크다운 파일 몇 개를 넣는 것으로 끝나죠. 버전 관리는 npm이 이미 잘하고 있으니 그 위에 얹기만 하면 됩니다.

라이브러리를 만들어 배포하고 계신다면 skills/ 디렉토리를 하나 만들어 보시길 권합니다. 사용자가 여러분의 라이브러리를 에이전트와 함께 쓸 때 겪는 삽질을 꽤 줄여 줄 수 있습니다. 반대로 라이브러리를 쓰는 입장이라면 intent list를 한 번 돌려 보세요. 이미 설치해 둔 패키지에 읽을거리가 들어 있을지도 모릅니다.

에이전트 스킬 자체가 처음이시라면 Agent Skills에서 개념과 구조를 먼저 살펴보시는 편이 좋습니다. 더 자세한 사용법은 TanStack Intent 공식 문서를 참고하세요.

This work is licensed under CC BY 4.0CCBY

개발자를 위한 뉴스레터

달레가 정리한 AI 개발 트렌드와 직접 만든 콘텐츠를 전해드립니다.

관련 포스트

Agent Skills: AI를 위한 업무 매뉴얼

AI 코딩 에이전트를 사용하다 보면 같은 종류의 작업을 반복적으로 요청하게 될 때가 있습니다. 예를 들어, "이 프로젝트에서는 Jest 대신 Vitest를 사용해", "API 테스트를 작성할 때는 이런 패턴을 따라줘", "마이그레이션 스크립트를 작성할 때는 항상 롤백 코드도 함께 작성해" 같은 지시를 매번 반복하게 되죠. 🤔 AGENTS.md나 CLAUDE.md 같은 컨텍스트 파일로 프로젝트 전반에 대한 정보를 제공할 수 있지만, 특정 작업에 대한 세부 지침까지 모두 담기에는 한계가 있습니다. 컨텍스트 파일이 너무 길어지면 AI가

skills.sh: 공개 에이전트 스킬 생태계

이전 글에서 에이전트 스킬이 무엇인지, 왜 필요한지 살펴보았습니다. 그런데 매번 필요한 스킬을 처음부터 만들어야 할까요? 다른 개발자들이 만든 유용한 Skill을 쉽게 찾아서 설치할 수 있다면 좋겠죠? 이번 글에서는 이런 필요를 채워주는 에이전트 스킬 공개 디렉토리인 skills.sh에 대해서 알아보겠습니다. skills.sh란? skills.sh는 2026년 1월 Vercel에서 출시한 Skills 디렉토리입니다. 공식 슬로건은 "The Open Agent Skills Ecosystem"인데요, Skills를 검색하고, 설치하고,

Agent Skill 만들기: SKILL.md 작성 가이드

이전 글에서 Agent Skills가 무엇인지, 왜 필요한지 살펴보았습니다. 컨텍스트 파일이 "프로젝트 소개서"라면, Skills는 "업무 매뉴얼"이라고 했죠. 이번 글에서는 한 걸음 더 나아가 직접 Skill을 설계하고 SKILL.md로 작성하는 방법을 알아보겠습니다. 🛠️ 좋은 Skill의 조건 Skill을 만들기 전에 어떤 Skill이 잘 동작하는지 생각해 볼 필요가 있습니다. 가장 중요한 건 범위가 명확해야 한다는 점입니다. "웹 개발하기" 같은 광범위한 Skill보다는 "Next.js API 라우트 작성하기"처럼 구체적인

클로드 코드 내장 에이전트 스킬

클로드 코드를 쓰다 보면 /help나 /clear 같은 슬래시 커맨드가 익숙해집니다. 이런 커맨드는 세션 초기화, 모델 전환 같은 단일 동작을 바로 실행하죠. 그런데 슬래시 /를 눌러보면 이것과는 좀 다른 느낌의 명령어들이 눈에 띕니다. /code-review, /batch, /loop 같은 것들인데요. 이것들은 슬래시 커맨드가 아니라 내장 스킬입니다. 슬래시 커맨드가 고정된 로직을 실행하는 것과 달리, 내장 스킬은 프롬프트 기반으로 동작해요. Claude에게 상세한 플레이북을 주고 도구를 조합해서 작업을 수행하게 하는 방식이죠.

Agent Plugins: 스킬과 MCP를 한 패키지로 묶기

에이전트용 스킬을 하나 잘 만들어 두면 여기저기서 쓰고 싶어집니다. 팀 동료는 클로드 코드 대신 Codex를 쓰고, 다른 동료는 Cursor를 쓰니까요. 스킬만 나눠주는 거라면 방법은 이미 있습니다. skills.sh의 npx skills add에 -a '*'를 붙이면 지원하는 코딩 에이전트 전부에 같은 스킬을 한 번에 설치해 주거든요. 진짜 문제는 스킬이 혼자 굴러가지 않을 때 드러납니다. 배포 상태를 조회하는 MCP 서버가 있어야 동작하는 스킬이라면, 서버 설정은 여전히 도구마다 손으로 넣어야 하죠. 스킬과 도구가 한 몸인데 배

Herdr: AI 코딩 에이전트를 위한 터미널 멀티플렉서

AI 코딩 에이전트 하나를 터미널에서 돌릴 때는 별문제가 없습니다. 그런데 버그 수정은 Codex에 맡기고, 테스트 실패 원인 조사는 Claude Code에 시키고, 옆에서는 개발 서버까지 띄우기 시작하면 상황이 달라져요. 터미널 탭을 돌아다니며 누가 작업 중인지, 누가 권한 승인을 기다리는지 계속 확인해야 합니다. 일은 에이전트들이 하는데 정작 사람은 터미널을 순찰하느라 바쁜 셈이죠. 🤔 Herdr는 이 문제를 풀기 위해 만든 터미널 멀티플렉서(terminal multiplexer)입니다. 화면을 나누고 세션을 유지하는 데서 그