The Skills Ecosystem — What, Why, and How It Works
스킬 생태계 입문 — 무엇이고, 왜 쓰고, 어떻게 작동하나
Claude Code 스킬은 단순한 프롬프트 저장소가 아니다. 컨텍스트가 일치할 때 자동 트리거되는 재사용 가능한 에이전트 워크플로다.
Overview
Claude Code를 처음 접한 사람들이 빠지는 함정이 있다. 스킬을 '저장된 프롬프트'로 이해하는 것이다. 스킬은 훨씬 더 정교한 시스템이다.
스킬은 SKILL.md 파일(또는 skill.md) 하나로 정의된다. 이 파일은 YAML frontmatter와 마크다운 지시사항으로 구성된다. 핵심은 description 필드다 — Claude Code가 현재 대화 컨텍스트와 이 설명을 비교해 자동으로 스킬을 불러올지 결정한다. 사용자가 /playwright를 입력할 필요가 없다. "E2E 테스트 작성해줘"라고 말하는 순간, 관련 스킬이 자동 활성화된다.
2026년 스킬 생태계의 규모: 337+개 검증 스킬, 277,000+번 설치된 최다 스킬(frontend-design), 18개 비즈니스 카테고리, 10개 이상의 에이전트 플랫폼 호환. 같은 SKILL.md 파일이 Claude Code, Cursor, Codex, Gemini CLI에서 모두 작동한다.
- 스킬이 일반 프롬프트와 어떻게 다른지 설명할 수 있다
- SKILL.md의 description 필드가 트리거 조건을 어떻게 결정하는지 이해한다
- ~/.claude/skills/ vs .claude/skills/ 차이를 적용 상황에 맞게 선택할 수 있다
- npx skills find, add, update 명령어를 능숙하게 사용할 수 있다
Sections
스킬의 해부학 — SKILL.md 구조
스킬 파일은 단순하다. YAML frontmatter에 name, description, when_to_use를 정의하고, 마크다운 본문에 Claude에게 줄 지시사항을 쓴다.
description 필드가 트리거의 전부다. "Use when the user asks to create E2E tests" vs "Use for testing" — 전자는 정확히 E2E 테스트 요청에서만 트리거되고, 후자는 '테스트'가 언급되는 모든 상황에서 트리거될 수 있다. 좋은 스킬은 좋은 설명에서 시작한다.
글로벌 vs 프로젝트 스코프
~/.claude/skills/ — 모든 프로젝트에서 사용 가능한 글로벌 스킬. Playwright, TypeScript 전문가처럼 어디서나 쓰이는 범용 스킬에 적합.
.claude/skills/ (프로젝트 루트) — 해당 레포에서만 활성화. 팀 코딩 컨벤션, 프로젝트별 배포 절차, 도메인 특화 규칙. git에 커밋하면 팀 전체가 공유한다.
고수들의 원칙: 범용 능력은 글로벌, 팀 지식은 프로젝트 스코프.
npx skills CLI 실전
스킬 생태계의 패키지 매니저다. npm처럼 한 줄로 설치하고, 업데이트하고, 검색한다.
npx skills find testing — 테스팅 관련 스킬 검색
npx skills add vercel-labs/agent-skills --list — 패키지 내 전체 스킬 목록 확인
npx skills add [패키지] -g -y — 글로벌 설치, 확인 없이
npx skills update — 설치된 스킬 전부 업데이트
npx skills check — 업데이트 가능한 스킬 확인
skills.sh — 중앙 디렉토리
skills.sh는 스킬 생태계의 공식 디렉토리다. 설치 수, 소스 평판, 업데이트 빈도를 기준으로 스킬을 검색하고 평가할 수 있다.
품질 기준: 설치 1,000+ (신뢰 가능), 출처 vercel-labs/anthropics/microsoft (공식 검증). 100 미만은 검토 필요.
평범한 주방 보조는 매번 '어떻게 스파게티를 만들지?' 생각한다. 미슐랭 셰프는 레시피 북 하나로 동일한 고품질을 반복한다. Claude Code 스킬은 그 레시피 북이다. 한 번 완성된 레시피(스킬)는 매번 실행될 때마다 동일한 전문가 수준의 결과를 보장한다. 당신이 자리를 비워도.
간단한 커스텀 스킬 SKILL.md 예시 — 팀 배포 체크리스트
---
name: team-deploy-checklist
description: Use when the user is about to deploy to production or asks about deployment
when_to_use: Before any production deployment, when user mentions 'deploy', 'release', or 'ship'
---
# Team Deploy Checklist
Before any production deployment, execute these steps IN ORDER:
1. **Environment Variables** — run `! env | grep -E 'DATABASE|API|SECRET' | wc -l` and confirm count matches .env.example
2. **Migration Status** — run `! npx prisma migrate status` and confirm no pending migrations
3. **Test Suite** — run `! npm test -- --passWithNoTests` and confirm 0 failures
4. **Bundle Size** — run `! npx bundlesize` if configured
5. **Security Headers** — confirm Content-Security-Policy and X-Frame-Options are set
6. **Rollback Plan** — document the rollback command before proceeding
Do NOT proceed if any step fails. Report each step's result as ✅/❌.description 필드가 '배포', 'deploy', 'ship' 등이 언급될 때 자동 트리거한다. 스킬 내용은 순서대로 실행되는 체크리스트로 구성되어 있으며, ! 명령어로 실제 시스템 상태를 확인한다.
✅ 시니어가 보는 것
- .claude/skills/ 디렉토리가 git에 커밋되어 있는가
- 스킬 description이 트리거 조건을 명확히 정의하고 있는가
- 글로벌/프로젝트 스코프를 의도에 맞게 사용하는가
- 팀 고유 워크플로가 스킬로 자산화되어 있는가
Key Takeaways
스킬 = 재사용 가능한 에이전트 워크플로
저장된 프롬프트가 아니다. description이 일치하면 자동 트리거되는 전문가 역할이다.
description = 트리거 설계
스킬의 품질은 코드 품질보다 description의 정밀도로 결정된다.
글로벌 vs 프로젝트 스코프
범용 능력(Playwright)은 글로벌, 팀 지식(배포 절차)은 프로젝트 스코프.
npx skills는 npm과 동일한 UX
find, add, update, check — 학습 비용이 거의 없다.
.claude/를 git에 커밋하라
스킬, 메모리, 설정이 팀 자산이 되는 순간이다.