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 vercel-react-best-practices

설치하면 각 에이전트의 스킬 디렉토리 — Claude Code는 .claude/skills/, Cursor와 Codex는 .agents/skills/ — 에 스킬이 들어간다. 기본은 정본 하나를 두고 에이전트별 디렉토리에 symlink를 거는 방식이라, 여러 에이전트를 써도 스킬 사본이 흩어지지 않는다.

72개 에이전트가 지원하는 이유

Agent Skills가 28K+ 스타(2026년 7월 기준)를 받은 건 단순히 Vercel 브랜드 때문이 아니다. 설치를 담당하는 skills CLI가 지원하는 에이전트 목록 — 공식 README 기준 72개 — 을 보면 이유가 명확해진다.

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

이 에이전트들은 각자 자기 스킬 디렉토리에서 SKILL.md를 읽는 컨벤션을 따른다. skills CLI가 스킬을 에이전트별 디렉토리에 맞게 설치해 주기 때문에, Agent Skills는 에이전트 중립적으로 동작한다. 특정 에이전트에 종속되지 않는다.

무엇이 들어 있나: 9개 스킬

2026년 7월 기준, 리포지토리의 skills/ 디렉토리에는 9개 스킬이 있다. 수십 개짜리 카탈로그가 아니라 Vercel Engineering이 직접 관리하는 좁은 컬렉션이다.

React / Next.js

1인 개발자에게 가장 실용적인 영역이다. vercel-react-best-practices는 Vercel Engineering의 React/Next.js 성능 최적화 가이드라인으로, 워터폴 제거·번들 크기·서버 사이드 성능 등 8개 카테고리 70개 규칙이 임팩트 우선순위와 함께 담겨 있다.

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices
npx skills add vercel-labs/agent-skills --skill vercel-composition-patterns

에이전트가 이 스킬을 가지면 use client 지시어를 남발하지 않는다. Server Component에서 처리 가능한 로직을 클라이언트로 내리지 않는다. vercel-composition-patterns는 boolean prop이 늘어나는 컴포넌트를 compound component로 리팩터링하는 패턴을, vercel-react-view-transitions는 React View Transition API로 페이지 전환 애니메이션을 구현하는 법을 다룬다.

Design / UI · 문서

web-design-guidelines는 접근성, 포커스 상태, 폼, 애니메이션, 타이포그래피 등 100+ 규칙으로 UI 코드를 리뷰한다. 에이전트에게 “Review my UI”라고 요청하면 이 기준으로 감사한다. writing-guidelines는 Vercel writing handbook 기반 80+ 규칙으로 문서와 산문을 리뷰한다.

React Native

vercel-react-native-skills는 React Native/Expo 베스트 프랙티스다. FlashList·메모이제이션 같은 성능 규칙부터 레이아웃·애니메이션·아키텍처까지 7개 섹션 16개 규칙을 담고 있다.

Deployment / Vercel 운영

deploy-to-vercel은 대화에서 바로 배포를 실행한다. 프레임워크를 자동 감지해 preview URL을 돌려주고, CLI 인증이 없는 환경(claude.ai 샌드박스 등)에서는 소유권 이전용 claim URL을 함께 준다. vercel-cli-with-tokens는 토큰 기반 Vercel CLI 조작을, vercel-optimize는 배포된 프로젝트의 비용·성능을 감사해 순위를 매긴 리포트를 만든다.

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

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

방식	Pass Rate	특징
Baseline (문서 없음)	53%	비교 기준선
Agent Skills (기본 동작)	53%	baseline과 동일 — 개선 폭 0
Agent Skills (명시적 사용 지시)	79%	프롬프트에 “스킬을 써라” 지시 추가
AGENTS.md (docs index)	100%	단일 파일, 매 턴 시스템 프롬프트에 포함

기본 설정에서는 테스트의 56%에서 에이전트가 스킬을 아예 호출하지 않아, pass rate가 문서 없는 baseline과 같은 53%에 머물렀다. 스킬 사용을 명시적으로 지시해 호출률을 95% 이상으로 끌어올려도 79%로, AGENTS.md의 100%에는 못 미쳤다. AGENTS.md는 매 턴 시스템 프롬프트에 포함되므로 “찾아볼지 말지” 판단 단계 자체가 없다.

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

커스텀 스킬 만들기

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

스킬의 기본 구조:

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

SKILL.md 작성 예시. skills CLI가 스킬을 인식하려면 YAML frontmatter에 name과 description이 필수다:

---
name: supabase-rls-pattern
description: 이 프로젝트의 Supabase Row Level Security 설정 패턴
---

# 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 웹 앱을 Vercel에 올리는 조합이라면:

npx skills add vercel-labs/agent-skills \
  --skill vercel-react-best-practices \
  --skill web-design-guidelines \
  --skill deploy-to-vercel

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

성능 리팩터링

느려진 페이지를 손볼 때 vercel-react-best-practices 스킬이 특히 유용하다. 워터폴 제거·번들 최적화 규칙이 임팩트 우선순위와 함께 컨텍스트에 들어가 있어서, 에이전트가 효과 큰 것부터 고친다.

코드 리뷰 보조

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

실전에서 주의할 점

컨텍스트 크기 관리

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

스킬 최신화

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

에이전트별 동작 차이

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

설치와 관리

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

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

# 특정 스킬 제거
npx skills remove web-design-guidelines

# 전체 제거
npx skills remove --all

# 설치된 스킬 업데이트
npx skills update

프로젝트 스코프로 설치한 스킬 디렉토리(.claude/skills/, .agents/skills/ 등)는 git으로 커밋하는 게 좋다. 팀원 모두가 동일한 스킬 세트를 쓰게 된다.

결론

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

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

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

npx skills add vercel-labs/agent-skills