TanStack Intent 리뷰 — 스킬을 npm 패키지로 배포한다는 좋은 아이디어, 아쉬운 구현 (I Wish This Was Better)

출처: I Wish This Was Better — Web Dev Simplified (Kyle). 영상의 내용을 기록으로 남겨두기 위해 ai로 번역해서 블로그를 작성했다.

TanStack Intent 가 풀려는 문제

TanStack Intent 는 라이브러리에 딸린 Agent Skills(SKILL.md) 를 npm 패키지 안에 번들해서 배포하는 도구다. 지금은 라이브러리를 설치한 뒤 스킬은 별도의 사이트에서 따로 받아야 하는데, 이러면 "설치된 라이브러리 버전"과 "스킬이 가정하는 버전"이 어긋나기 쉽다. 스킬을 패키지와 함께 배포하면 패키지를 업데이트할 때 스킬도 같은 버전으로 따라온다는 것이 핵심 아이디어다.

Kyle 은 이 아이디어 자체는 훌륭하다고 평가한다. 문제는 구현 방식이다.

소비자 관점 — install 이 사실은 프롬프트다

소비자가 하는 일은 install 커맨드 하나를 터미널에 붙여넣는 것뿐이다. 그런데 이 커맨드는 실제 설치 스크립트가 아니라 AI 에게 보내는 프롬프트다. 프롬프트를 받은 에이전트가 node_modules 를 뒤져 스킬을 찾고, 그 목록을 AGENTS.md 에 써넣는다. "이 작업을 할 때는 이 라이브러리의 이 스킬을 써라"는 안내와 함께, 스킬 로딩은 TanStack Intent 라이브러리 실행으로 연결된다.

Kyle 이 지적하는 문제는 이렇다:

• 결정적(deterministic)이어야 할 작업을 LLM 에 맡겼다. node_modules 에서 스킬을 찾아 목록을 만드는 건 그냥 코드로 하면 되는 일이다. LLM 이 하면 실행할 때마다 결과가 달라지거나 틀릴 수 있다.
• AGENTS.md 가 자동으로 갱신되지 않는다. 패키지 업데이트로 스킬이 추가·삭제·변경돼도 AGENTS.md 는 그대로다. 매번 프롬프트를 다시 실행해야 한다. "패키지가 새 스킬 파일을 배포하니까 항상 최신"이라는 주장은 스킬 목록 자체가 AI 생성물이라는 점에서 성립하지 않는다.
• 일반 스킬처럼 동작하지 않는다. 보통 스킬은 에이전트에 로드되어 직접 참조할 수 있는데, 이 방식은 스킬이 node_modules 와 AGENTS.md 두 곳에 흩어진다. 실제로 에이전트의 스킬 목록에는 아무것도 안 잡히고, 스킬을 쓰려면 라이브러리 커맨드로 수동 로드해야 한다. 자동완성도 없다.

보안 문제 — 악성 스킬 주입

더 큰 문제는 공급망 공격 표면이다. 인기 없는 라이브러리 하나만 탈취해서 TanStack Intent 가 기대하는 형식으로 악성 스킬을 심어두면, 소비자가 install 프롬프트를 실행할 때 그 스킬이 AGENTS.md 에 함께 등록된다. AI 실행 과정을 눈으로 검수하지 않으면 이후 다른 작업을 할 때 악성 스킬이 로드될 수 있다. Kyle 이 AI 작업을 항상 샌드박스에서 돌리는 이유이기도 하다.

Kyle 의 대안 — node_modules 의 스킬을 직접 참조

스킬을 npm 패키지에 번들하는 것까지는 그대로 가져가되, AGENTS.md 로 복사하는 중간 단계를 없애고 에이전트 설정 파일에서 node_modules 안의 스킬 경로를 직접 참조하자는 것이 Kyle 의 대안이다.

영상에서는 pi 에이전트로 시연한다. .pi/settings.json 하나만 만들면 된다 (화면 코드를 직접 본 것이 아니라 자막 기반 재구성이다):

{
  "skills": [
    "node_modules/@trpc/client/skills",
    "node_modules/@trpc/server/skills",
    "node_modules/follow/skills"
  ]
}

에이전트를 재시작하면 해당 경로의 스킬이 일반 스킬로 로드된다. 이 방식의 장점은:

• 복사가 없으니 어긋날 일이 없다. 패키지가 업데이트되면 참조 대상(source of truth)이 곧바로 바뀐다. 중간에 낀 AGENTS.md 라는 중개자가 없다.
• 명시적 허용 목록이다. 원하는 라이브러리의 스킬만 지정하므로, 악성 패키지의 스킬이 자동으로 딸려 들어오지 않는다.
• 서드파티 도구가 필요 없다. 설정 파일 하나면 되고, 대부분의 에이전트 하니스가 비슷한 기능을 지원한다.

메인테이너 관점 — scaffold 도 반쯤만 좋다

라이브러리 메인테이너용으로는 npx @tanstack/intent@latest scaffold 커맨드가 있는데, 이것도 실행하면 마크다운 프롬프트를 출력한다 — 역시 에이전트와 함께 쓰라는 것이다. 코드베이스를 스캔해서 스킬 초안을 만들어주는 용도라 이 경우는 AI 를 쓰는 게 적절하다고 Kyle 도 인정한다. 다만:

• GitHub 이슈 라벨을 멋대로 만들고 package.json 에 keywords 를 추가하는 등 지나치게 opinionated 하다. NPM 커맨드일 필요 없이 복사해서 쓰는 프롬프트면 충분했다.
• 생성된 스킬이 오픈 스탠다드를 잘 따르지 않는다. TanStack DB 용으로 생성된 스킬을 보면 이름에 dash 대신 slash 를 쓰고, 루트 스킬 + 참조 파일 구조 대신 서브 스킬을 잔뜩 만들고, description 이 "왜 이 스킬을 써야 하는가"가 아니라 "스킬 안에 뭐가 들었는가"만 설명한다. 에이전트가 스킬을 고르는 기준은 description 인데, 이래서는 쓸모가 떨어진다.

정리

• 스킬을 npm 패키지에 번들해서 라이브러리 버전과 함께 배포한다 — 이 아이디어는 좋고, 유지할 가치가 있다.
• 하지만 스킬 목록을 LLM 프롬프트로 AGENTS.md 에 복사하는 방식은 비결정적이고, 갱신이 수동이고, 악성 스킬 주입에 취약하다. 문서와 코드는 결국 어긋난다는 오래된 교훈 그대로다.
• 대안: 에이전트 설정 파일(예: pi 의 .pi/settings.json)로 node_modules 안의 스킬 경로를 직접 참조하면, 복사 없이 source of truth 를 바라보므로 항상 동기화되고 허용 목록도 명시적이다.
• 스킬을 자동 생성할 때는 이름·구조·description 이 Agent Skills 오픈 스탠다드를 따르는지 직접 검수해야 한다.