한 줄 요약: 코딩 에이전트마다 스킬 디렉터리 경로가 다르다. vercel-labs/skills는 그 파편을 npx skills 한 줄로 묶는 설치·검색·업데이트 CLI다. Agent Skills 스펙(SKILL.md + YAML frontmatter)을 파싱하고, 79개 에이전트 정의(src/agents.ts)에 맞춰 심링크·복사·링크 모드로 꽂으며, 글로벌 ~/.agents/.skill-lock.json(v3)과 프로젝트 skills-lock.json 이중 락으로 재현성을 분리한다. 오늘은 GitHub Trending 전체 일간 6위권(별 34,590·오늘 +190), npm skills@1.7.2(주간 다운로드 약 480만), MIT 라이선스를 API·레지스트리로 재확인하고, 10/09에 다룬 mattpocock/skills(콘텐츠 커리큘럼)와 계층을 분명히 가른 뒤 아키텍처를 코드·스모크로 해부한다.
왜 지금 이 저장소인가
에이전트 스킬 논의는 두 층으로 갈린다. 하나는 무엇을 가르칠지(스킬 본문·워크플로·TDD 가이드), 다른 하나는 어디에 어떻게 꽂을지(경로·심링크·락·멀티 에이전트). 10/09 포스트의 mattpocock/skills는 전자다. 오늘 다룰 vercel-labs/skills는 후자—Vercel Labs가 공개한 오픈 에이전트 스킬 생태계 CLI이며, 디렉터리는 skills.sh, 공식 스킬 묶음은 vercel-labs/agent-skills다. 같은 “skills” 이름이지만 패키지 경계가 다르다.
| 항목 | 확인한 값 (2026-10-14 ~11:56 KST) | 해석 |
|---|---|---|
| 저장소 | vercel-labs/skills — TypeScript CLI |
설명문 그대로 “The open agent skills tool – npx skills”. 홈페이지 skills.sh |
| 별 / 포크 / 이슈 | 34,590 / 2,953 / 1,115 (GitHub API) | 오늘 Trending 전체 일간 6위, stars today 190. 2026-01-14 생성 |
| 최근 푸시 / 태그 | 2026-10-09 17:54 UTC → 10/10 02:54 KST. 태그 v1.7.2 (sha 671e8c3) |
릴리스·트렌딩이 맞물림. 박스에서 v1.7.2 shallow clone |
| npm | skills@1.7.2, license MIT, bin skills/add-skill |
주간 다운로드 4,804,674 · 월간 25,093,274 (npm downloads API). 런타임 의존성 tar, yaml |
| 라이선스 | MIT (Copyright 2026 Vercel, Inc.). LICENSE·배지·npm 필드 일치 | 재배포·상용 연동에 부담이 적다. ELv2(Context Mode)와 대비 |
| 엔진 | engines.node >= 22.20.0 |
fs/promises.glob 사용. Node 20에서는 SyntaxError. 박스에 Node 22.20.0 바이너리로 스모크 |
| 에이전트 매핑 | src/agents.ts에 name 79개 |
README는 “OpenCode, Claude Code, Codex, Cursor, and 75 more”. 유니버설·공유 경로 포함 |
이 글은 README, LICENSE, AGENTS.md, package.json 1.7.2, src/{cli,add,installer,agents,skill-lock,local-lock,use,providers}/*, npm 레지스트리·다운로드 API, 그리고 박스에서 Node 22.20.0으로 돌린 skills --help·add --list·init·add … --copy -y·use·list -g 결과를 바탕으로 썼다. 대화형 fzf find와 전체 vitest 스위트(69개 테스트 파일)는 이 환경에서 돌리지 않았다.
mattpocock/skills와 무엇이 다른가
독자가 “또 skills 포스트?”라고 넘기지 않게 경계를 먼저 긋는다.
| 축 | mattpocock/skills (10/09) | vercel-labs/skills (오늘) |
|---|---|---|
| 계층 | 에이전트 엔지니어링 콘텐츠 | 생태계 설치 CLI + 디렉터리 |
| 산출물 | 흐름·태스크 그래프·TDD 가이드 | npx skills 바이너리, 락 파일, 에이전트 경로 매핑 |
| 배포 | 레포를 읽고 따라 하기 | npm 패키지 skills, skills.sh 검색 |
| 멀티 에이전트 | 개념·프랙티스 중심 | 79개 --agent 타깃 + 자동 감지 |
| 같이 쓸 수 있나 | 보완 관계. 콘텐츠 레포를 skills add owner/repo로 꽂는 쪽이 오늘 CLI의 역할 |
|
문제가 무엇인가
Agent Skills 스펙은 단순하다—디렉터리 하나와 SKILL.md(YAML name/description). 현실은 그렇지 않다. Claude Code는 .claude/skills/, Cursor·Codex·Cline 다수는 .agents/skills/, OpenClaw는 프로젝트 루트 skills/, Windsurf는 글로벌이 ~/.codeium/windsurf/skills/다. 팀이 Cursor와 Claude Code를 동시에 쓰면 같은 스킬을 두 경로에 수동 복사하거나, 경로를 잊고 “스킬이 안 떠요”로 빠진다. skills CLI는 그 매핑 테이블을 코드로 고정하고, 캐논컬 한 곳에 둔 뒤 에이전트 쪽으로 심링크(권장)한다.
저장소 구조
| 경로 | 역할 | 실무 포인트 |
|---|---|---|
bin/cli.mjs → dist/cli.mjs |
배포 엔트리(~341KB 번들) | obuild. 런타임 deps는 tar·yaml만 남기고 @clack·simple-git·detect-agent는 청크로 내장 |
src/cli.ts |
커맨드 라우팅 | add/use/list/find/remove/update/init + experimental_install·experimental_sync |
src/add.ts (~2.6k줄) |
설치 오케스트레이션 | well-known → download → git clone 순서. CI용 -y/--all/--json |
src/installer.ts (~1.4k줄) |
심링크·복사·경로 안전 | InstallMode = symlink|copy|link. path traversal 가드 sanitizeName/isPathSafe |
src/agents.ts (915줄) |
에이전트 카탈로그 | project/global 경로, 감지 함수, Eve 서브에이전트, universal 그룹 |
src/skill-lock.ts / local-lock.ts |
이중 락 | 글로벌 v3(폴더 해시), 프로젝트 skills-lock.json 커밋용 |
src/source-parser.ts |
소스 URL 정규화 | GitHub shorthand, tree URL, GitLab, Azure Repos, SSH, 로컬 |
src/providers/* |
원격 프로바이더 | well-known v1/v2(schemas.agentskills.io/discovery/0.2.0), Mintlify·HuggingFace 등 |
src/use.ts |
설치 없이 프롬프트 생성 | 임시 디렉터리에 풀어 stdout만. --agent면 대화형 에이전트 기동 |
skills/find-skills/ |
번들 메타 스킬 | CLI 레포 자체에 포함. agent-skills의 9개 스킬과는 별개 |
tests/ + *.test.ts |
vitest | 69개 테스트 파일. 심링크·sanitize·well-known·cross-platform path |
설계 결정과 트레이드오프
| 결정 | 선택 | 트레이드오프 |
|---|---|---|
| 캐논컬 + 심링크 | 기본은 ~/.agents/skills/(글로벌) 또는 프로젝트 캐논컬에 복사 후 에이전트 경로에 심링크 |
단일 소스·업데이트 용이. Windows·일부 샌드박스에선 심링크 실패 → --copy 폴백 |
| 이중 락 | 글로벌 .skill-lock.json v3 + 프로젝트 skills-lock.json |
개인 머신 추적과 팀 재현을 분리. 복원은 experimental_install—아직 실험 API |
| 폴더 해시(tree SHA) | 스킬 폴더 전체 GitHub tree SHA를 락에 저장 | SKILL.md만 해시하면 부속 파일 변경을 놓침. API 의존·프라이빗 레포는 토큰 필요 |
| 발견 depth≤3 | 알려진 컨테이너 안에서 최대 3단계. 얕은 SKILL.md가 하위 섀도 |
거대한 monorepo 오탐 감소. 깊은 예제는 --full-depth |
| well-known 스코프 비폴백 | 경로 스코프 미해결 시 루트 인덱스로 떨어지지 않음 | 호스트 전체 카탈로그 오설치 방지. URL 오타는 명시적 에러 |
| 자격 증명 격리 | Git credential → gh repo clone → SSH. gh auth token을 Node로 읽지 않음 |
토큰 유출면 축소. 디버깅은 덜 직관적. 명시 GITHUB_TOKEN/GH_TOKEN은 허용 |
| 텔레메트리 | skills.sh /tele/t. 공개 GitHub만 식별자 전송 |
제품 개선용. DISABLE_TELEMETRY=1 또는 DO_NOT_TRACK=1로 차단 |
| 보안 평가 UI | 설치 요약에 Gen/Socket/Snyk 배지(skills.sh) | 스킬은 에이전트 전체 권한으로 돈다—배지는 보조. 리뷰는 여전히 필수 |
설치 스코프·모드·커맨드
| 스코프 | 플래그 | 위치 | 언제 |
|---|---|---|---|
| Project | (기본) | ./<agent>/skills/ |
팀과 커밋·공유 |
| Global | -g |
~/<agent>/skills/ |
모든 프로젝트 공통 |
| 모드 | 동작 | 선택 기준 |
|---|---|---|
symlink (권장) |
캐논컬 복사 + 에이전트 심링크 | 업데이트·단일 진실 |
copy |
에이전트별 독립 복사 | 심링크 불가 환경 |
link |
캐논컬이 소스 자체를 가리킴 | experimental_sync / node_modules 연동 |
| 커맨드 | 역할 | 스모크에서 확인 |
|---|---|---|
skills --help / --version |
도움말·버전 | 1.7.2, add/use/list/find/… 노출 |
skills add <src> --list |
설치 없이 목록 | vercel-labs/agent-skills에서 9개 스킬 나열 |
skills add … -g -a claude-code --copy -y |
비대화형 설치 | web-design-guidelines → ~/.claude/skills/… + 락 v3 |
skills use owner/repo@skill |
임시 프롬프트 stdout | SKILL.md frontmatter+본문 출력 (설치 없음) |
skills init [name] |
템플릿 생성 | demo-skill/SKILL.md name/description 스캐폴드 |
skills list -g |
설치 목록 | Agents: Claude Code, Source: vercel-labs/agent-skills |
skills find / update / remove |
검색·갱신·제거 | help에 옵션 확인. 대화형 find는 미실행 |
에이전트 경로 매트릭스 (발췌)
전체 79개는 README 표와 agents 배열이 권위다. 실무에서 자주 겹치는 것만 정리한다.
| 에이전트 | --agent |
프로젝트 | 글로벌 |
|---|---|---|---|
| Claude Code | claude-code |
.claude/skills/ |
~/.claude/skills/ |
| Cursor | cursor |
.agents/skills/ |
~/.cursor/skills/ |
| Codex / Cline / Pi / Zed 등 | codex … |
.agents/skills/ |
~/.agents/skills/ |
| OpenCode | opencode |
.agents/skills/ |
~/.config/opencode/skills/ |
| Gemini CLI | gemini-cli |
.agents/skills/ |
~/.gemini/skills/ |
| GitHub Copilot | github-copilot |
.agents/skills/ |
~/.copilot/skills/ |
| OpenClaw | openclaw |
skills/ |
~/.openclaw/skills/ |
| Amp / Replit / Universal | amp 등 |
.agents/skills/ |
~/.config/agents/skills/ |
호환성 표(README) 기준: Basic skills는 주요 에이전트 전부 Yes. allowed-tools는 대부분 Yes(Kiro CLI·Zencoder는 No). context: fork는 Claude Code만 Yes. Hooks는 Claude Code·Cline·Kiro CLI 등으로 제한된다. 스킬 본문이 모든 런타임에서 동일하게 동작한다고 가정하면 안 된다.
대안 비교
| 대안 | 계층 | 강점 | 이 CLI 대비 |
|---|---|---|---|
| 수동 복사 / git submodule | 파일 | 단순·감사 용이 | 에이전트 수×경로 폭발. 업데이트·락 없음 |
| 에이전트 네이티브 마켓(Claude plugin 등) | 플랫폼 | 1급 UX·훅 연동 | 벤더 록인. 크로스 에이전트 팀에는 부족 |
mattpocock/skills |
콘텐츠 | 엔지니어링 커리큘럼 | 설치기가 아님. 보완재 |
| Context Mode / Headroom | 컨텍스트 절약 | 토큰·도구 출력 통제 | 스킬 배포와 다른 문제. 병행 가능 |
| 직접 well-known 호스팅 | 배포 | 사내 카탈로그 | 이 CLI가 클라이언트. 서버 스펙은 agentskills.io discovery |
박스에서 돌린 스모크
환경: Node v22.20.0(공식 linux-x64 tar), npm install skills@1.7.2, 격리 HOME=…/smoke-home. 시스템 Node 20.19.2는 fs/promises.glob 미지원으로 CLI 기동 실패—엔진 제약이 실제임을 확인했다.
skills --version→1.7.2skills add vercel-labs/agent-skills --list -y→ Found 9 skills (composition-patterns, deploy-to-vercel, react-best-practices, … writing-guidelines)skills init demo-skill→demo-skill/SKILL.md스캐폴드skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a claude-code --copy -y→~/.claude/skills/web-design-guidelines/SKILL.md, 락 v3에skillFolderHash기록, skills.sh 보안 평가(Gen Safe / Socket 0 / Snyk Low) 표시skills use vercel-labs/agent-skills@web-design-guidelines→ 설치 없이 SKILL.md 프롬프트 stdoutskills list -g→ Agents: Claude Code, Source: vercel-labs/agent-skills
의도적 실패 사례: --skill find-skills는 agent-skills에 없어 “No matching skills” + 가용 목록 출력. find-skills는 CLI 레포 skills/ 번들이다.
한계·주의·라이선스
| 항목 | 내용 |
|---|---|
| 권한 모델 | 설치된 스킬은 에이전트와 동일 권한. CLI 설치 완료 메시지 그대로 “Review skills before use”. 배지≠감사 |
| Node ≥22.20 | 구형 CI 이미지·일부 컨테이너는 바로 깨짐. 엔진을 먼저 올려야 함 |
| 실험 API | experimental_install/experimental_sync는 이름 그대로. 프로덕션 표준화 전 계약 변경 가능 |
| 오픈 이슈 1,115 | 별 대비 이슈 수가 큼. 에이전트 경로 드리프트·엣지 케이스가 계속 유입되는 신호 |
| 텔레메트리 기본 ON | 기업망·규정 환경은 배포 스크립트에 DO_NOT_TRACK=1을 박을 것 |
| 다운로드 한도 | 직접 URL 기본 10MiB / 추출 25MiB / 파일 1000. 신뢰 소스에서만 상향 |
| 라이선스 | MIT (Vercel, Inc. 2026). ThirdPartyNoticeText로 번들 고지. 스킬 콘텐츠 라이선스는 각 업스트림을 따로 볼 것 |
누가 도입해야 하는가
- 맞다: Claude Code·Cursor·Codex·OpenCode 등을 섞어 쓰는 팀. 스킬을 git에 넣고 CI로
-y재현 설치하고 싶은 조직. skills.sh/well-known으로 사내·오픈 카탈로그를 배포하려는 플랫폼 팀. - 보류: 에이전트 하나·스킬 소수만 쓰는 개인(수동 복사로 충분). Node 22를 아직 못 올리는 레거시 CI. 스킬 내용 자체의 품질·가드레일이 더 급한 팀(그때는 콘텐츠·정책이 병목).
- 같이 보면 좋은 것: Agent Skills 스펙(agentskills.io),
vercel-labs/agent-skills공식 묶음, 10/09mattpocock/skills콘텐츠 심층, 컨텍스트 계층의 Context Mode/Headroom.
정리하면, vercel-labs/skills는 “에이전트에게 무엇을 가르칠지”가 아니라 “가르친 것을 79개 런타임에 같은 계약으로 심는 배관”이다. Trending 6위·주간 npm 480만이 말해 주듯, 2026년 에이전트 스택에서 설치·락·경로 매핑은 이미 인프라 문제다.