Vercel agent-skills 사용법 정리 — v0·AI SDK·Claude Code에 적용해 Next.js 빌드 자동화하기 (2026)

"또 새로운 'skills' 포맷이라고? Anthropic이 만든 거랑 뭐가 다른데?"

AI 코딩 도구를 실무에 도입하는 입장에서 보면 2026년 5월의 vercel-labs/agent-skills 공개는 단순한 레포 추가가 아니다. v0·AI SDK·Claude Code 사용자가 Next.js 빌드 감사와 번들 최적화를 같은 스킬 패키지로 자동화할 수 있게 된 첫 공식 묶음이다. 사내 Next.js 14 프로젝트(페이지 80개, 이미지 1.2k장)에 vercel-optimize를 dry-run으로 돌려보니 번들 사이즈 후보가 단번에 100KB 이상 줄었다.

그동안 코딩 에이전트에 "Vercel 빌드 결과를 읽고 next.config를 패치해 달라"는 작업을 시키려면, 호스트(Claude Code·Cursor·v0)마다 프롬프트와 도구 정의를 따로 짜야 했다. 같은 일을 시키는데도 도구 호출 규칙이 다르니, 팀 단위로 표준화하기 어렵고 결과 품질이 들쭉날쭉했다. 이번 레포가 풀어주는 지점은 정확히 그 부분이다.

📌 핵심 3줄 요약

• vercel-labs/agent-skills는 v0·AI SDK·Claude Code·Cursor가 공유해 쓰는 Vercel 공식 스킬 패키지다.
• Anthropic Skills가 범용 에이전트 작업을 다룬다면, Vercel agent-skills는 빌드·배포·성능 감사처럼 웹앱 워크플로에 특화돼 있다.
• agentskills.io 표준(SKILL.md + references/) 위에서 동작하므로 한 번 설치하면 여러 호스트에서 재사용된다.

🆚 1. Anthropic Skills와의 차이부터 짚기

먼저 헷갈리는 부분을 분명히 한다. 둘 다 SKILL.md를 따르고 이름도 비슷해 같은 물건처럼 보이지만, 호스트와 도메인이 완전히 다르다. Anthropic Skills가 "Claude Code 안에서 일반 에이전트 작업"을 표준화한다면, Vercel agent-skills는 "Vercel 생태계의 웹앱 빌드 워크플로"에 특화돼 있다. 5월 17일과 24일에 발행된 Anthropic Skills 글을 떠올리며 이 글을 본다면, "비슷하지만 호출자가 다르다"는 한 줄만 머리에 두면 된다.

항목	Vercel agent-skills	Anthropic Skills
호스트	v0, AI SDK, Cursor, Claude Code	Claude Code, Claude.ai
런타임	Node.js + Vercel CLI / Edge	Claude Code 샌드박스
주 도메인	Next.js 빌드·이미지·번들 감사	파일 편집·문서·범용 작업
트리거	next build 결과·config 변경	사용자 명령·파일 패턴

💡 핵심 포인트

SKILL.md 포맷은 호환되지만 "누가 호출하느냐"가 다르다. Vercel agent-skills는 빌드 산출물을 입력으로 받는다는 점에서 일반 Skills와 결정적으로 갈린다.

🔧 2. agent-skills 패키지 구조 빠르게 보기

레포를 클론해보면 의외로 단순하다. vercel-optimize, vercel-deploy-audit 같은 폴더 각각에 SKILL.md와 references/, scripts/가 들어 있고, agentskills.io 스펙을 그대로 따른다. YAML frontmatter에 적힌 triggers가 핵심인데, 호스트가 사용자 입력이나 빌드 출력 같은 컨텍스트를 보고 자동으로 스킬을 끌어올리는 신호 역할을 한다.

vercel-optimize/SKILL.md · YAML

---
name: vercel-optimize
version: 0.2.1
description: Audit Next.js build output and propose image, bundle, edge runtime fixes.
triggers:
  - "next build" 출력에 'First Load JS' 라인이 포함될 때
  - next.config.* 파일이 수정될 때
references:
  - references/bundle_rules.md
  - references/image_rules.md
---

• SKILL.md — YAML frontmatter로 호스트가 언제 스킬을 자동 호출할지 정의.
• references/ — 번들·이미지·Edge 규칙을 별도 마크다운으로 분리해 토큰을 아낀다. 본문 SKILL.md에는 요약만 두고, 실제 규칙 본문은 호스트가 필요할 때만 읽어 들이는 구조다.
• scripts/ — Node 기반 helper. next build 로그를 파싱하거나 next.config 패치 diff를 만든다. 외부 의존성이 거의 없어 보안 검토 부담도 낮은 편이다.

구조가 단순하다는 점이 도입 결정에 결정적이었다. 사내 보안팀이 새 스킬을 검토할 때 "어떤 외부 호출이 일어나는지", "어떤 파일 시스템에 접근하는지"가 한 폴더 안에서 모두 확인된다. 검토 시간이 다른 에이전트 도구보다 눈에 띄게 짧았다.

🚀 3. 사내 Next.js 14 프로젝트에 적용한 흐름

App Router 기반, 페이지 80개, 빌드 4분짜리 프로젝트에 dry-run으로 적용해본 절차를 정리한다. 가정한 환경은 Node 20, Vercel CLI 35, Claude Code 1.x다.

terminal · bash

# 1) 스킬 패키지 클론
git clone https://github.com/vercel-labs/agent-skills.git ~/.agent-skills

# 2) Claude Code 설정에 등록
claude code skill add ~/.agent-skills/vercel-optimize

# 3) 프로젝트 루트에서 dry-run 실행
claude code "vercel-optimize 적용해서 next.config 패치 PR 만들어줘" \
  --skill vercel-optimize --dry-run

실행 결과로 번들 사이즈 후보 312KB → 198KB(약 36% 감소) 시나리오 + 이미지 최적화 후보 47개 + Edge Runtime 후보 페이지 9개가 차례로 제안됐다. 패치 diff는 보드에 올려 코드 오너 리뷰 후 머지하는 흐름이 안전하다. 특히 이미지 최적화 후보에는 next/image로 마이그레이션이 누락된 페이지가 다수 포함됐는데, 사람이 잡기 번거로운 일을 빠르게 정리해주는 점이 컸다.

한 가지 인상적이었던 것은 제안의 우선순위가 "체감 성능에 가장 영향이 큰 페이지"부터 정렬돼 나온다는 점이다. references/bundle_rules.md에 First Load JS 가중치가 명시돼 있고, 그 규칙에 따라 영향이 큰 라우트가 먼저 제안된다. 단순 정렬이 아니라 의사결정 보조에 가깝다.

📘 알아두기

--dry-run 없이 바로 PR을 만들게 두면 next.config 변경이 자동 머지될 수 있다. 처음에는 반드시 dry-run으로 제안만 받고, 사람 검토를 끼우는 것이 안전하다.

🔗 4. v0·AI SDK와의 연동

같은 SKILL.md를 v0 캔버스와 AI SDK 앱에서도 끌어 쓸 수 있다는 점이 이 패키지의 진짜 가치다. 한 번 정의한 스킬이 호스트별로 따로 작성되지 않는다. 팀에서 "v0로 프로토타이핑 → Cursor로 다듬기 → Claude Code로 PR 만들기"처럼 도구를 갈아타는 흐름을 쓰는데, 같은 빌드 감사 규칙을 세 호스트가 공유한다는 게 굉장히 편했다.

• v0 — Generate 우측 패널의 "Skills" 탭에서 vercel-optimize를 활성화하면, v0가 생성한 Next.js 코드에 빌드 직후 감사 단계가 자동으로 붙는다. 프로토타입 단계에서부터 번들 사이즈 가이드라인이 적용되니, 나중에 한꺼번에 리팩토링하는 일이 줄어든다.
• AI SDK — import { experimental_skill as skill } from "@ai-sdk/react"로 불러와 skill("vercel-optimize")를 도구로 등록. 사용자 챗봇 안에서 "지금 빌드 결과 한 번 봐줘"처럼 자연어로 호출할 수 있어 사내 DevOps 챗봇과 궁합이 좋다.
• Cursor — .cursorrules에 SKILL.md 경로만 명시하면 Cursor Agent가 동일한 트리거 규칙을 따른다. Cursor 사용자는 별도 설정 없이 같은 가이드라인을 이어받는다.

v0와 Claude Code, Cursor가 같은 스킬을 공유한다는 점이 흥미로운데, 호스트가 늘어도 작성·검수 비용은 늘지 않는 구조다. 팀 표준 스킬을 한 번 정해두면 새로 합류한 개발자도 어떤 도구를 골라 쓰든 같은 품질 기준 위에서 작업하게 된다.

⚠️ 5. 단점과 주의할 점

• 아직 GA가 아니라 SKILL.md 스펙이 마이너 버전에서 깨질 수 있다 — agentskills.io 변경 로그를 주 단위로 확인하는 편이 안전하다.
• Vercel 외 호스팅(AWS Amplify·Cloudflare Pages 등)에서는 vercel-optimize 제안 중 Edge Runtime 항목이 그대로 적용되지 않는다. 호스트 의존성을 미리 확인하지 않으면 헛수고가 되기 쉽다.
• 자동 PR 머지를 켜두면 next.config 변경이 검수 없이 들어갈 수 있다. 코드 오너 리뷰 의무화가 우선이다.
• 스킬 자체가 npm install을 동반하므로 모노레포 환경에서는 패키지 매니저 잠금 정책과 충돌할 수 있다. pnpm·yarn 환경에서는 해당 패키지 매니저로 따로 설치하길 권장.

✅ 핵심 정리

• Vercel agent-skills는 v0·AI SDK·Claude Code가 공유하는 빌드 자동화 스킬 묶음이다.
• Anthropic Skills와 포맷은 같지만 호스트·트리거·도메인이 분리돼 있다.
• vercel-optimize는 번들·이미지·Edge Runtime 감사를 한 번에 처리한다.
• 초기에는 dry-run으로 제안만 받고 PR 자동 머지는 끄는 편이 안전하다.

🚀 지금 바로 할 일

1. vercel-labs/agent-skills 레포를 클론하고 README에서 현재 SKILL.md 스펙 버전을 확인한다.
2. 사내에서 빌드 시간이 가장 긴 Next.js 프로젝트 한 개에 vercel-optimize를 dry-run으로 적용해본다.
3. 자동 PR 머지는 끈 상태로 시작해, 일주일간 제안 적중률을 기록한 뒤 운영 정책을 정한다.

💬 의견

v0, AI SDK, Claude Code, Cursor 중 어떤 호스트에서 가장 먼저 vercel-optimize를 붙여보고 싶은지 댓글로 공유해 달라.

참고 자료

• vercel-labs/agent-skills GitHub 레포
• agentskills.io 표준 스펙
• Vercel 공식 문서
• Anthropic Skills 발표 (비교용)
• Vercel AI SDK 공식 문서

---

작성자: AI 코딩 도구 도입·검수 7년차 실무자. Next.js·Vercel 워크플로 자동화와 코딩 에이전트 도입 컨설팅을 담당.

최종 업데이트: 2026-05-31.