AI 에이전트한테 10년치 React 최적화 룰 한 방에 주입하기 — Vercel Agent Skills 완전분석

Claude Code나 Cursor로 Next.js 코드를 짜다 보면 에이전트가 뻔한 실수를 반복하는 상황이 있습니다. useEffect를 연속으로 쌓거나, 병렬로 돌려도 되는 API 호출을 순차적으로 처리하거나, 클라이언트 번들에 무거운 라이브러리를 그냥 넣는 식입니다. LLM이 React를 모르는 게 아니라, 프로젝트 맥락과 프론트엔드 고수들이 머릿속에 담고 다니는 우선순위 판단 기준이 없기 때문입니다. Vercel이 2026년 1월에 공개한 Agent Skills는 이 문제를 패키지 매니저 방식으로 해결합니다.

Agent Skills가 뭔지

Agent Skills는 Anthropic이 내부적으로 Claude에게 특화 태스크를 가르치기 위해 만든 포맷에서 출발했습니다. 이후 오픈 표준으로 공개됐고, Vercel이 그 위에 배포 레이어를 얹었습니다. 개념은 간단합니다. SKILL.md 파일에 자연어 인스트럭션을 담고, 선택적으로 실행 스크립트를 추가해서 폴더 하나로 패키징하면 Agent Skills 포맷이 됩니다. 이 패키지를 CLI로 설치하면 Claude Code, Cursor, OpenCode, Codex 등 호환 에이전트들이 코딩 세션 중에 자동으로 참조합니다.

npm이 JavaScript 생태계에서 재사용 가능한 코드를 공유하는 방식을 표준화한 것처럼, Agent Skills는 AI 에이전트에게 주입하는 전문 지식을 패키지로 표준화합니다. npx skills add 명령 하나면 됩니다. Vercel CEO Guillermo Rauch가 1월 18일 직접 발표했고, GitHub 저장소는 vercel-labs/agent-skills에서 확인할 수 있습니다.

설치: 세 줄이면 끝난다

React·Next.js 프로젝트에 Vercel 공식 스킬 패키지를 설치하는 가장 빠른 방법입니다. Node.js만 설치되어 있으면 됩니다.

# Vercel 공식 React 최적화 스킬 설치
npx skills add vercel-labs/react-best-practices

# UI·접근성 감사 스킬 설치
npx skills add vercel-labs/web-design-review

# Vercel 자동 배포 스킬 설치
npx skills add vercel-labs/vercel-deploy

설치 후 스킬은 ~/.agents/skills 디렉터리에 저장되고, Claude Code의 ~/.claude/skills나 Cursor의 해당 경로로 심링크가 걸립니다. 하나만 설치하면 시스템에 설치된 모든 호환 에이전트가 동시에 사용할 수 있습니다. 업데이트도 마찬가지입니다.

# 설치된 스킬 목록 확인
npx skills list

# 전체 업데이트
npx skills update

# 커뮤니티 스킬 검색
npx skills find "performance"

CLI는 ~/.agents/.skill-lock.json으로 버전 잠금을 관리합니다. skills update 실행 시 설치된 폴더의 해시값을 중앙 API에 보내 실시간으로 변경사항을 비교하는 방식이라 캐시된 낡은 데이터를 참조하지 않습니다.

react-best-practices 스킬: 40개 이상의 룰

Vercel의 플래그십 스킬입니다. Vercel 엔지니어링이 10년 이상 프로덕션 Next.js 코드베이스에서 반복적으로 마주친 병목들을 57개 룰로 정리했습니다. 룰은 Core Web Vitals 영향도 순으로 우선순위가 매겨져 있습니다.

스킬의 진짜 가치는 개별 룰 자체보다 이 우선순위에 있습니다. 일반적인 LLM이 "React 성능 최적화"라는 트리거를 받으면 useMemo와 useCallback 남발을 먼저 제안하는 경우가 많습니다. 실제로는 API 워터폴이 600ms를 잡아먹고 있는데 메모이제이션 미세 조정을 하고 있는 셈입니다. react-best-practices는 에이전트가 워터폴 → 번들 크기 → 직렬화 오버헤드 → 리렌더 비용 순서로 접근하도록 유도합니다.

스킬이 포착하는 실제 사례들을 보면, 채팅 컴포넌트에서 같은 메시지 리스트를 8번 스캔하던 코드를 단일 패스로 합치거나, 서로 의존하지 않는 DB 호출을 순차 실행에서 병렬로 전환하거나, 매 렌더마다 localStorage에서 JSON을 파싱하던 코드를 초기 상태에서 한 번만 파싱하도록 수정하는 패턴들입니다. 이런 수정들은 툴 없이는 코드 리뷰에서 놓치기 쉬운 유형입니다.

web-design-review 스킬: 100개 이상의 접근성·UX 룰

UI 코드에 대한 감사 스킬입니다. 접근성, 성능, UX를 합쳐 100개 이상의 룰을 포함합니다. Claude Code나 Cursor로 컴포넌트를 짜고 "Review my UI for accessibility"라고 트리거하면 에이전트가 이 스킬을 로드해 색상 대비, 키보드 내비게이션, 스크린 리더 호환성, 반응형 레이아웃, 애니메이션 접근성 등을 체계적으로 점검합니다.

스킬의 로딩 방식에도 설계 포인트가 있습니다. 에이전트는 스킬 이름과 설명만 먼저 읽고, 관련 트리거 문구가 나왔을 때만 전체 인스트럭션을 로드합니다. "Progressive Disclosure"라고 부르는 방식으로, 컨텍스트 윈도우를 불필요하게 소모하지 않습니다.

vercel-deploy 스킬: 대화에서 바로 배포

세 번째 공식 스킬은 Vercel 자동 배포입니다. claude.ai나 Claude Desktop에서 "지금 이 코드 Vercel에 배포해줘"라고 하면 에이전트가 이 스킬을 참조해서 배포를 실행합니다. 완료되면 프리뷰 URL과 함께 클레임 URL이 나오는데, 이 클레임 URL을 통해 배포된 프로젝트 소유권을 본인 Vercel 계정으로 이전할 수 있습니다.

배포 완료!
Preview URL: https://skill-deploy-abc123.vercel.app
Claim URL: https://vercel.com/claim-deployment?code=...

에이전트가 배포까지 끝내는 엔드투엔드 워크플로가 코드 리뷰 사이클 없이 대화 한 번으로 완결됩니다.

실전: Claude Code에 스킬 적용하는 워크플로

실제로 Next.js 프로젝트에 스킬을 적용하는 워크플로는 이렇습니다. 스킬을 설치한 뒤 Claude Code를 열고 프로젝트 루트에서 세션을 시작합니다.

# 프로젝트에 스킬 설치
npx skills add vercel-labs/react-best-practices
npx skills add vercel-labs/web-design-review

# Claude Code 실행
claude

세션 안에서 트리거 문구를 쓰면 스킬이 활성화됩니다. "Review my React performance", "Audit this component for accessibility", "Check for waterfall issues in this page" 같은 자연어로 충분합니다. 에이전트가 SKILL.md를 로드하고 해당 룰셋을 기준으로 코드베이스를 분석하기 시작합니다.

팀 단위로 쓴다면 프로젝트 루트에 .github/skills 디렉터리를 두고 스킬을 버전 관리하는 방식도 있습니다. 모든 팀원이 같은 룰셋을 참조하고, CI 파이프라인에서도 동일한 스킬이 적용됩니다.

커스텀 스킬 만들기

Vercel 공식 스킬 외에도 직접 스킬을 만들어 팀 내부에서 배포할 수 있습니다. 구조는 단순합니다. 폴더를 하나 만들고 SKILL.md에 인스트럭션을 쓰면 최소 요건은 충족됩니다.

my-custom-skill/
├── SKILL.md          # 자연어 인스트럭션 (필수)
├── scripts/          # 실행 스크립트 (선택)
│   └── audit.js
└── examples/         # 예시 (선택)
    └── before-after.md

SKILL.md에는 스킬이 하는 일과 트리거 조건, 에이전트가 따라야 할 룰을 작성합니다. 팀의 코딩 컨벤션, 사내 디자인 시스템 룰, 특정 API 사용 패턴 등을 스킬로 패키징하면 신규 입사자도 에이전트를 통해 팀 표준을 즉시 적용할 수 있습니다. 완성한 스킬은 skills.sh 디렉터리에 등록해 커뮤니티에 공개할 수도 있습니다.

결론

Vercel Agent Skills는 "AI 에이전트에게 전문성을 주입하는 방법"의 패러다임을 바꿉니다. 프롬프트에 긴 컨텍스트를 직접 붙여 넣는 방식에서, 버전 관리되고 재사용 가능한 패키지로 전문 지식을 배포하는 방식으로의 전환입니다. npm이 JavaScript 생태계를 표준화했던 것과 같은 구조가 AI 에이전트 생태계에 그대로 적용됩니다. Claude Code, Cursor, OpenCode 어느 에이전트를 쓰든 같은 스킬을 참조하게 되고, 팀 전체가 동일한 룰셋 위에서 동작합니다. React·Next.js 기반 프로젝트를 에이전트와 함께 운영 중이라면 지금 당장 npx skills add vercel-labs/react-best-practices 하나를 먼저 실행해보는 것으로 충분합니다.