Ch10. skills.sh 생태계 활용
npx skills CLI, 추천 스킬, 설치·업데이트, 커스텀 스킬 배포와 보안 정책
핵심 요약
- Vercel Skills v1.1부터
npx add-skill이 deprecated되고npx skills find/add/update인터페이스를 사용합니다. - 엔터프라이즈는 전역 설치 대신 프로젝트 로컬 설치를 기본값으로 두고, 스킬도 코드처럼 리뷰하고 버전을 고정하며 변경 이력을 남깁니다.
- 좋은 스킬은 "항상 읽는 회사 소개"가 아니라 결제 webhook·DB migration 리뷰처럼 반복 작업의 판단 기준이며, 큰 파일 하나보다 작업 단위로 작게 쪼갭니다.
- 외부 스킬은 npm·GitHub Action 같은 공급망 자산으로 다루며 제공자 신뢰성·설치 명령 일치·SKILL.md 위험 유도 여부를 도입 전 체크합니다.
- 운영 프로젝트에서는
npx skills add를 개인 판단으로 실행하지 않고 PR+CODEOWNERS 리뷰를 거칩니다.
skills.sh 개요
skills.sh는 에이전트가 특정 도메인의 작업 규칙과 문맥을 재사용하도록 돕는 스킬 생태계입니다. Vercel Skills v1.1부터 기존 npx add-skill 명령은 deprecated 됐고, 이제 npx skills 인터페이스를 씁니다.
# 대화형 검색
npx skills find
# 스킬 설치
npx skills add vercel/turborepo
npx skills add vercel-labs/next-skills
npx skills add vercel-labs/agent-skills
# 설치된 스킬 업데이트
npx skills update엔터프라이즈에서는 전역 설치보다 프로젝트 로컬 설치를 기본값으로 둡니다. 스킬도 코드처럼 리뷰하고, 버전을 고정하고, 변경 이력을 관리해야 합니다.
추천 스킬 조합
| 단계 | 추천 스킬 | 용도 |
|---|---|---|
| 모노레포 설계 | vercel/turborepo | task graph, cache, --affected, worktree 운영 |
| 앱 아키텍처 | vercel/nextjs | App Router, Server Components, Proxy, Cache Components |
| UI 품질 | vercel/react-best-practices, vercel/web-design-guidelines | 컴포넌트 구조, 접근성, 프론트엔드 리뷰 |
| 배포 | vercel/deployments-cicd, vercel/env-vars | Vercel CLI, preview, production, 환경 변수 |
| 운영 | vercel/observability, vercel/vercel-functions | 로그, 함수 런타임, Fluid Compute, 장애 분석 |
| 보안 | 보안 리뷰 전용 내부 스킬 | 조직 정책, 금지 명령, 데이터 접근 규칙 |
스킬 이름과 제공자는 시간이 지나면 바뀝니다. 설치 전에 npx skills find와 GitHub 소스, 제공자 조직을 함께 확인하세요.
프로젝트 단계별 적용
| 프로젝트 단계 | 스킬 운영 방식 |
|---|---|
| 초기 설계 | 공식 스킬 위주로 설치하고 커스텀 스킬은 만들지 않음 |
| 첫 프로덕션 | CLAUDE.md/AGENTS.md와 겹치는 규칙을 줄이고 반복 작업만 스킬화 |
| 팀 확장 | 보안·배포·데이터 접근 규칙을 내부 스킬로 분리 |
| 다중 에이전트 운영 | Codex/Claude/Cursor에서 공통으로 읽히는 규칙과 도구별 규칙을 분리 |
좋은 스킬은 "항상 읽어야 하는 회사 소개"가 아니라 "특정 작업에서 필요한 판단 기준"입니다. 예를 들어 결제 webhook 구현, DB migration 리뷰, Vercel 배포 장애 triage처럼 반복되는 작업에 맞춥니다.
커스텀 스킬 제작
---
name: acme-api-patterns
description: ACME API route, webhook, server action 설계 규칙
---
# ACME API 패턴
## 적용 범위
- `app/api/**/route.ts`
- server action mutation
- 외부 webhook handler
## 규칙
- 응답은 `{ data, error, meta }` 형태로 통일
- 외부 webhook은 원문 body 검증과 idempotency key를 기록
- server action은 Zod 검증 후 domain service를 호출
- 시크릿은 환경 변수에서만 읽고 로그에 출력하지 않음커스텀 스킬은 한 파일에 모든 규칙을 넣기보다 작업 단위로 작게 쪼갭니다. 스킬 설명은 에이전트가 언제 쓸지 판단하는 trigger 역할을 하니 구체적으로 적습니다.
스킬 공급망 보안
스킬은 코드가 아니어도 에이전트 행동을 바꿉니다. 그래서 외부 스킬은 npm 패키지나 GitHub Action과 같은 공급망 자산으로 다룹니다.
## 스킬 도입 전 체크리스트
- [ ] 제공자와 저장소가 공식 또는 신뢰 가능한 조직인가?
- [ ] 설치 명령이 예상 저장소와 정확히 일치하는가?
- [ ] SKILL.md에 외부 다운로드, secret 출력, 무제한 shell 실행 유도가 없는가?
- [ ] 프로젝트 로컬에 설치하고 PR 리뷰를 거쳤는가?
- [ ] 업데이트 시 diff를 확인하고 changelog를 남겼는가?스킬 설치 정책
운영 프로젝트에서는 npx skills add를 개발자 개인 판단으로 실행하지 않습니다. 새 스킬은 PR로 추가하고, CODEOWNERS에서 플랫폼/보안 담당자의 리뷰를 거치게 하세요.
참고 문서
- skills.sh — 스킬 검색·설치
- Vercel: Skills v1.1.1 —
npx skillsCLI와 deprecatedadd-skill안내 - Vercel Skills GitHub — 공식 스킬 소스