Vercel Agent Skills 실전 가이드: AI 에이전트에 프로덕션 레디 능력을 붙이는 법

AI 에이전트의 고질적인 문제

Claude Code나 Cursor로 Next.js 프로젝트를 개발하다 보면 반복되는 패턴이 있다. 에이전트가 getServerSideProps를 쓰거나, 구버전 Image 컴포넌트 API를 그대로 가져오거나, 삭제된 pages/api/ 방식으로 Route Handler를 만들려 한다.

에이전트의 지식에는 cut-off가 있다. Next.js 15의 async params, App Router 전용 캐싱 API, React 19의 Server Actions 최신 패턴 — 훈련 데이터가 따라가지 못하는 부분들이다. 에이전트가 틀린 코드를 자신 있게 생성하면, 개발자는 그걸 다시 고치느라 시간을 쓴다.

Vercel이 이 문제를 다르게 접근했다. "에이전트를 더 잘 훈련시키자"가 아니라, "에이전트가 실행 시점에 최신 컨텍스트를 가져오게 하자"는 방향이다. 그 결과물이 Agent Skills다.

Agent Skills란 무엇인가

Agent Skills는 AI 에이전트에게 패키지화된 능력을 주입하는 구조화된 방법이다. 각 스킬은 마크다운 문서 + 코드 예제 + 참조 자료로 구성되어 있고, 에이전트가 특정 도메인의 작업을 수행할 때 이 컨텍스트를 읽어 최신 패턴으로 코드를 생성한다.

간단히 말하면: 에이전트의 지식을 런타임에 업데이트하는 플러그인 시스템이다.

# 전체 스킬 컬렉션 설치
npx skills add vercel-labs/agent-skills

# 특정 스킬만 설치
npx skills add vercel-labs/agent-skills --skill nextjs-app-router

설치하면 프로젝트 루트에 skills/ 디렉토리가 생성된다. Claude Code, Cursor, Copilot 같은 에이전트들은 이 디렉토리를 자동으로 인식해서 작업 시 참조한다.

18+ 에이전트가 지원하는 이유

Agent Skills가 23K+ 스타를 받은 건 단순히 Vercel 브랜드 때문이 아니다. 지원하는 에이전트 목록을 보면 이유가 명확해진다.

• 코딩 에이전트: Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Aider
• AI 어시스턴트: Google Gemini CLI, Amazon Q Developer, Continue
• 커스텀 에이전트: OpenAI Codex, Devin, 자체 구축 에이전트

이 에이전트들이 공통적으로 따르는 컨벤션이 있다. 프로젝트 루트의 skills/ 디렉토리, 또는 AGENTS.md/CLAUDE.md 같은 컨텍스트 파일을 읽는다. Agent Skills는 이 컨벤션을 활용해서 에이전트 중립적으로 동작한다. 특정 에이전트에 종속되지 않는다.

6개 카테고리, 30+ 스킬

현재 Agent Skills 컬렉션에는 6개 주요 카테고리가 있다.

React / Next.js

1인 개발자에게 가장 실용적인 카테고리다. Next.js App Router의 최신 패턴, Server Components vs Client Components 결정 기준, Streaming과 Suspense 활용법이 담겨 있다.

npx skills add vercel-labs/agent-skills --skill nextjs-app-router
npx skills add vercel-labs/agent-skills --skill react-server-components

에이전트가 이 스킬을 가지면 use client 지시어를 남발하지 않는다. Server Component에서 처리 가능한 로직을 클라이언트로 내리지 않는다.

AI SDK

Vercel AI SDK를 사용하는 경우 필수다. streamText, generateObject, useChat 훅의 최신 API, 멀티모달 처리, 도구 호출 패턴이 포함된다.

npx skills add vercel-labs/agent-skills --skill ai-sdk

AI SDK는 버전 업데이트가 잦고 API가 크게 바뀐 적이 있다. 에이전트가 구버전 패턴을 쓰는 걸 이 스킬이 막아준다.

Design / UI

shadcn/ui 컴포넌트 패턴, Tailwind CSS v4 유틸리티, Radix UI 접근성 패턴이 포함된다. 디자인 시스템이 있는 프로젝트에서 에이전트가 일관된 컴포넌트를 생성하게 한다.

Browser Automation

Playwright, Puppeteer 기반 자동화 스크립트 패턴이다. 테스트 작성, 스크래핑, E2E 시나리오를 에이전트가 생성할 때 최신 API를 사용하게 한다.

Deployment

Vercel 배포 설정, vercel.json 구성, Edge Functions vs Serverless Functions 선택 기준, 환경변수 관리 패턴이다.

Commerce

결제 연동은 버그가 생기면 치명적인 영역이다. Stripe Elements, 구독 관리, 웹훅 처리의 검증된 패턴을 에이전트가 참조하게 한다.

AGENTS.md vs Agent Skills: 솔직한 비교

Vercel이 자체 블로그에서 흥미로운 연구 결과를 공개했다. 에이전트에게 컨텍스트를 제공하는 두 가지 방식을 비교한 것이다.

방식	Pass Rate	특징
AGENTS.md (루트 파일)	100%	단일 파일, 프로젝트 전체 컨텍스트
Agent Skills	79%	카테고리별 분리, 재사용 가능

AGENTS.md가 더 높은 pass rate를 보였다. 이유는 에이전트가 단일 컨텍스트 파일을 더 일관되게 처리하기 때문으로 분석됐다.

AGENTS.md는 "이 프로젝트에서 우리가 어떻게 코드를 쓰는가"를 정의하고, Agent Skills는 "Next.js/React/AI SDK의 최신 올바른 방법"을 제공한다. 레이어가 다르다.

커스텀 스킬 만들기

팀 전용 패턴, 사내 라이브러리, 반복되는 보일러플레이트가 있다면 직접 스킬을 만들 수 있다.

스킬의 기본 구조:

my-custom-skill/
├── SKILL.md          # 스킬 설명 + 에이전트 지시사항
└── references/       # 코드 예제, 참조 파일
    ├── example-1.ts
    └── pattern.ts

SKILL.md 작성 예시:

# Supabase RLS Pattern

이 프로젝트에서 Supabase Row Level Security를 설정할 때 따르는 패턴이다.

## 규칙

1. 모든 테이블에 RLS 활성화 필수
2. SELECT 정책은 항상 `auth.uid() = user_id` 기반
3. INSERT 시 `user_id`를 `auth.uid()`로 자동 설정
4. 서비스 역할은 RLS bypass — admin 작업에만 사용

## 참조

- `references/rls-example.sql`: 표준 RLS 설정 예시
- `references/admin-client.ts`: service role 클라이언트 패턴

스킬 배포는 GitHub 리포지토리로 한다. 팀원이 npx skills add your-org/your-skills로 설치하면 된다.

# 로컬 스킬 테스트
npx skills add ./my-custom-skill

# GitHub에서 설치
npx skills add your-org/your-skills

# 특정 브랜치/태그
npx skills add your-org/your-skills#v1.2.0

1인 개발자가 실제로 활용하는 방법

Agent Skills의 실용적인 사용 패턴 몇 가지다.

프로젝트 초기화 시

새 프로젝트를 시작할 때 기술 스택에 맞는 스킬을 미리 설치해 둔다. Next.js + AI SDK + Stripe 조합이라면:

npx skills add vercel-labs/agent-skills --skill nextjs-app-router
npx skills add vercel-labs/agent-skills --skill ai-sdk
npx skills add vercel-labs/agent-skills --skill commerce

에이전트가 첫 날부터 최신 패턴으로 코드를 생성한다.

레거시 프로젝트 마이그레이션

Pages Router에서 App Router로 마이그레이션할 때 nextjs-app-router 스킬이 특히 유용하다. 에이전트가 구버전과 신버전의 차이를 컨텍스트로 갖고 있어서, 변환 작업에서 실수가 줄어든다.

코드 리뷰 보조

에이전트에게 PR 리뷰를 시킬 때 해당 도메인의 스킬을 붙이면 "최신 패턴과 다른 부분"을 더 정확하게 잡아낸다.

실전에서 주의할 점

컨텍스트 크기 관리

스킬을 너무 많이 설치하면 에이전트의 컨텍스트 윈도우가 소모된다. 실제로 사용하는 스킬만 설치하는 게 원칙이다. 스킬을 전부 설치하고 싶은 충동을 억제하자.

스킬 최신화

npx skills add는 설치 시점의 스킬을 가져온다. 프레임워크가 메이저 업데이트될 때 스킬도 다시 설치해서 최신 상태를 유지해야 한다.

에이전트별 동작 차이

18+ 에이전트가 지원된다고 하지만, 스킬을 처리하는 방식은 에이전트마다 미묘하게 다르다. Claude Code와 Cursor가 같은 스킬을 읽더라도 결과물이 완전히 동일하지는 않다. 본인이 주로 쓰는 에이전트에서 충분히 테스트해 보자.

설치와 관리

# 설치
npx skills add vercel-labs/agent-skills

# 현재 설치된 스킬 확인
npx skills list

# 특정 스킬 제거
npx skills remove nextjs-app-router

# 전체 제거
npx skills remove --all

# 스킬 업데이트
npx skills update vercel-labs/agent-skills

skills/ 디렉토리는 git으로 커밋하는 게 좋다. 팀원 모두가 동일한 스킬 세트를 쓰게 된다.

결론

Agent Skills는 AI 에이전트의 구조적 한계 — 훈련 데이터 cut-off — 를 실용적으로 우회하는 도구다. Vercel이 공식으로 관리하는 컬렉션이기 때문에 Next.js 관련 스킬은 특히 신뢰할 수 있다.

AGENTS.md보다 pass rate가 낮다는 Vercel 자체 연구 결과는 솔직하게 공개된 데이터다. 그렇다고 쓸모없다는 뜻이 아니다. "프로젝트 고유 규칙은 AGENTS.md, 프레임워크 최신 패턴은 Agent Skills"로 역할을 나누면 둘을 시너지 있게 활용할 수 있다.

23K+ 스타는 커뮤니티가 이미 검증한 결과다. 에이전트 기반 개발을 본격적으로 하고 있다면, 한 번 설치해 보고 직접 판단하는 게 제일 빠르다.

npx skills add vercel-labs/agent-skills