skills.sh 완전 정복 — 설치부터 나만의 SKILL.md 만들기까지 실습 가이드

Claude Code, Cursor, GitHub Copilot에서 매번 같은 프롬프트를 반복 입력하고 있다면, skills.sh를 쓸 때가 됐습니다. 한 번 만들면 어떤 AI 에이전트에서든 재사용할 수 있는 스킬 패키지 생태계, 설치부터 직접 만들기까지 이 글 하나로 끝냅니다.

 

skills.sh가 뭔가요?

Vercel이 2026년 1월에 공개한 AI 에이전트 스킬 디렉토리 & CLI입니다. "GitHub Trending의 AI 버전"으로 이해하면 됩니다.

기존 방식의 문제는 이렇습니다. "React 파일 성능 리뷰해줘"라는 맥락을 매번 복붙하고, 팀원에게도 다시 설명하고, 다른 도구로 옮기면 또 처음부터 시작해야 합니다. skills.sh는 이 지식을 SKILL.md라는 재사용 가능한 패키지로 만들어 설치 한 줄로 해결합니다.

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -y

현재 Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Windsurf 등 39개 이상의 AI 에이전트를 지원합니다.

 

SKILL.md의 3단계 로딩 구조 이해하기

스킬을 잘 쓰려면 내부 동작 원리를 알아야 합니다. 스킬은 Progressive Disclosure(단계적 로딩) 방식으로 동작합니다.

단계로딩 시점내용토큰 비용

Level 1	세션 시작 시 항상	frontmatter의 name + description	스킬당 ~100 토큰
Level 2	스킬 트리거 시	SKILL.md 전체 본문	5,000 토큰 이하 권장
Level 3	필요할 때만	references/, scripts/ 등 참조 파일	사실상 무제한

이 구조 덕분에 스킬을 수십 개 설치해도 유휴 상태의 토큰 비용은 거의 0입니다. 에이전트가 관련 요청을 감지할 때만 해당 스킬의 전체 내용을 읽어들입니다.

 

Step 1. skills CLI 설치 및 기본 명령어

Node.js가 설치되어 있다면 별도 설치 없이 npx로 바로 사용할 수 있습니다.

자주 쓰는 명령어 전체 정리

# 스킬 검색 (키워드 또는 인터랙티브)
npx skills find [키워드]

# 스킬 설치 (기본: 프로젝트 범위)
npx skills add <owner/repo>

# 특정 스킬만 선택해서 설치
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

# 여러 스킬 동시 설치
npx skills add vercel-labs/agent-skills \
  --skill vercel-react-best-practices \
  --skill web-design-guidelines \
  --skill frontend-design

# 특정 에이전트에만 설치
npx skills add vercel-labs/agent-skills -a claude-code -a cursor

# 글로벌 범위로 설치 (모든 프로젝트에서 사용)
npx skills add vercel-labs/agent-skills -g

# 리포지토리에서 사용 가능한 스킬 목록만 확인 (설치 안 함)
npx skills add vercel-labs/agent-skills --list

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

# 업데이트 확인 및 업데이트
npx skills check
npx skills update

# 스킬 제거
npx skills remove web-design-guidelines
npx skills remove --all   # 전체 제거

# 새 SKILL.md 템플릿 생성
npx skills init my-skill

프로젝트 범위 vs 글로벌 범위

• 프로젝트 범위 (기본): .claude/skills/, .cursor/skills/ 등 — 팀원과 git으로 공유 가능
• 글로벌 범위 (-g): ~/.claude/skills/, ~/.cursor/skills/ 등 — 내 모든 프로젝트에서 사용

 

Step 2. 지금 당장 써볼 인기 스킬 TOP 5

skills.sh 전체 설치 순위 기준 상위권 스킬입니다. 처음이라면 이것부터 시작하세요.

• vercel-react-best-practices (vercel-labs/agent-skills): React & Next.js 성능, 서버 컴포넌트, 데이터 페칭 등 Vercel 공식 베스트 프랙티스. 각 규칙에 Bad/Good 예시 포함. npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -y
• web-design-guidelines (vercel-labs/agent-skills): Vercel 공식 UI 가이드라인. 레이아웃, 타이포그래피, 접근성, UX 규칙을 파일/라인 단위로 리뷰. npx skills add vercel-labs/agent-skills --skill web-design-guidelines -y
• frontend-design (anthropics/skills): Anthropic이 직접 만든 UI 심미성 스킬. 컬러, 여백, 모션, 시각적 위계에 대한 구체적 Do/Don't 포함. npx skills add anthropics/skills --skill frontend-design -y
• skill-creator (anthropics/skills): "좋은 스킬을 만드는 방법"을 담은 메타 스킬. 직접 SKILL.md를 만들 계획이라면 필수. npx skills add anthropics/skills --skill skill-creator -y
• find-skills (vercel-labs/skills): 에이전트가 skills.sh 생태계를 탐색하고 설치할 스킬을 스스로 제안하는 메타 스킬. npx skills add vercel-labs/skills --skill find-skills -y

 

Step 3. 나만의 SKILL.md 처음부터 만들기

스킬의 핵심은 단 하나의 파일, SKILL.md입니다. 폴더 구조는 다음과 같습니다.

my-skill-name/
├── SKILL.md          # 필수: 메타데이터 + 지침
├── references/       # 선택: 세부 참조 문서 (Level 3 로딩)
│   └── criteria.md
├── scripts/          # 선택: 에이전트가 실행할 스크립트
│   └── validate.sh
└── assets/           # 선택: 템플릿, 이미지 등

SKILL.md 기본 구조

---
name: skill-name        # 필수. 소문자, 하이픈만 허용. 최대 64자
description: |          # 필수. 최대 1024자.
  [이 스킬이 무엇을 하는지] + [언제 트리거되는지 + 구체적인 트리거 문구]
---

# 스킬 제목

에이전트가 실행할 단계별 지침을 여기에 작성합니다.

## Step 1: ...
## Step 2: ...
## Step 3: ...

 

Step 4. 실습 — 한국어 커밋 메시지 생성기 만들기

실제로 만들어보겠습니다. git diff --staged를 분석해서 Conventional Commits 형식의 한국어 커밋 메시지를 자동 생성하는 스킬입니다.

① 스킬 디렉토리 생성

# Claude Code용 글로벌 스킬로 생성
mkdir -p ~/.claude/skills/kr-commit-writer

# 또는 프로젝트 스킬로 생성
mkdir -p .claude/skills/kr-commit-writer

② SKILL.md 작성

---
name: kr-commit-writer
description: |
  git diff를 분석해 Conventional Commits 형식의 한국어 커밋 메시지를 생성합니다.
  사용자가 "커밋 메시지 작성", "커밋 써줘", "변경사항 요약해줘", "commit message",
  "staged 변경사항 커밋" 등을 요청할 때 자동으로 활성화됩니다.
---

# 한국어 커밋 메시지 생성기

Conventional Commits 형식을 따르되, 본문은 한국어로 작성합니다.

## 커밋 메시지 형식

```
타입(범위): 제목 (영문, 72자 이내)

- 변경 내용 요약 1 (한국어)
- 변경 내용 요약 2 (한국어)
```

허용 타입: feat, fix, docs, style, refactor, test, chore, perf, ci, build

## Step 1: 변경사항 확인

```bash
git diff --staged
```

스테이징된 파일이 없으면 사용자에게 알립니다:
"스테이징된 변경사항이 없습니다. `git add` 후 다시 시도해주세요."

## Step 2: 변경사항 분석

- 어떤 파일이 변경됐는지, 어떤 카테고리인지 파악
- 신규 기능(feat), 버그 수정(fix), 리팩토링(refactor) 등 타입 결정
- 영향받은 모듈/컴포넌트 = 범위(scope)

## Step 3: 커밋 메시지 작성

- 제목(첫 줄): 영문, 명령형, 72자 이내, 마침표 없음
- 본문: 한국어로 변경 이유와 내용 요약

## Step 4: 품질 체크

- [ ] 타입이 허용 목록 내에 있는가
- [ ] 제목이 72자 이내인가
- [ ] 명령형 시제인가 (add, fix, update — added, fixed 아님)
- [ ] 본문이 한국어로 작성됐는가

## 작성 예시

```
feat(auth): add Google OAuth2 login

- 기존 세션 관리 시스템을 재사용하여 Google OAuth2 로그인 플로우 구현
- 사용자가 Google 계정으로 로그인할 수 있는 버튼 추가

fix(api): handle null response from payment provider

- 결제 제공업체에서 null 응답 수신 시 앱이 크래시되는 버그 수정
- 응답 검증 로직 추가 및 에러 메시지 개선
```

③ 정상 로딩 확인

# 설치된 스킬 목록에 표시되는지 확인
npx skills ls

# Claude Code에서 직접 호출 테스트
# /kr-commit-writer

이제 Claude Code에서 "커밋 메시지 써줘"라고만 입력하면 스킬이 자동으로 활성화됩니다.

 

스킬이 안 트리거될 때: 가장 많이 틀리는 부분

스킬을 만들고 나서 동작하지 않는 경우, 원인의 90%는 description 문제입니다. description은 사람이 읽는 설명문이 아니라, 에이전트가 활성화 여부를 판단하는 트리거 조건입니다.

❌ 잘못된 description (What만 있고 When이 없음)

description: 문서를 도와줍니다.

✅ 올바른 description (What + When + 구체적 트리거 문구)

description: |
  소프트웨어 프로젝트의 README.md를 생성합니다.
  사용자가 "README 작성해줘", "readme 만들어줘", "프로젝트 문서화해줘",
  "README.md 생성", "문서 만들어줘"라고 요청할 때 활성화됩니다.

트리거 문구는 실제 사용자가 입력할 법한 다양한 표현을 최대한 많이 포함하세요. 한국어와 영어 표현을 함께 넣는 것도 좋습니다.

 

그 외 체크리스트

• 파일 경로 확인: 파일명은 반드시 SKILL.md (대소문자 구분)
• YAML 문법 확인: frontmatter는 반드시 첫 줄 ---로 시작하고 ---로 닫아야 함
• 세션 재시작: 스킬 편집 후 반드시 Claude Code / Cursor 세션을 재시작
• 명시적 호출 테스트: "kr-commit-writer 스킬 사용해서 커밋 메시지 써줘"처럼 스킬 이름을 직접 언급해서 테스트

 

팀과 스킬 공유하기

팀 전체가 같은 스킬을 쓰려면 프로젝트 디렉토리에 저장하고 git으로 올리면 됩니다. 팀원이 pull받으면 바로 사용 가능합니다.

# 프로젝트 범위로 생성
mkdir -p .claude/skills/kr-commit-writer

# git에 커밋
git add .claude/skills/
git commit -m "chore: add kr-commit-writer skill for team"
git push

로컬 폴더를 직접 설치하는 것도 가능합니다.

npx skills add ./my-local-skills

 

⚠️ 보안 주의사항

스킬은 에이전트의 행동을 제어할 수 있는 강력한 도구인 만큼, 커뮤니티 스킬 설치 시 반드시 주의하세요.

• 설치 전 모든 파일을 직접 읽어보세요. 특히 scripts/ 폴더 안의 코드를 확인하세요.
• 외부 네트워크 호출을 요구하는 스킬은 경계하세요. 데이터 유출(exfiltration) 위험이 있습니다.
• 설치 전 채팅에 시크릿을 붙여넣도록 유도하는 스킬은 절대 설치하지 마세요.
• 신뢰할 수 있는 소스 우선: anthropics/skills, vercel-labs/agent-skills처럼 공식 조직이 배포한 스킬을 우선 사용하세요.

에이전트별 스킬 저장 경로 정리

에이전트프로젝트 경로글로벌 경로

Claude Code	.claude/skills/	~/.claude/skills/
Cursor	.cursor/skills/	~/.cursor/skills/
GitHub Copilot	.github/skills/	~/.copilot/skills/
Gemini CLI	.gemini/skills/	~/.gemini/skills/
Codex	.codex/skills/	~/.codex/skills/
OpenCode	.opencode/skills/	~/.config/opencode/skills/
Windsurf	.windsurf/skills/	~/.codeium/windsurf/skills/

같은 SKILL.md 파일이 모든 에이전트에서 동작합니다. 한 번 만들면 어디서든 쓸 수 있습니다.

 

마치며

skills.sh의 핵심은 단순합니다. "AI에게 매번 같은 걸 설명하지 말고, 한 번만 만들어두고 재사용하자"는 것입니다. 처음에는 git 커밋 메시지 생성기처럼 단순한 스킬부터 시작해서, 점점 팀 컨벤션과 도메인 지식을 담은 복잡한 스킬로 발전시켜 나가면 됩니다.

다음 글에서는 CLAUDE.md 실전 작성법을 다룰 예정입니다. 잘못 쓰면 AI 성능이 오히려 떨어진다는 연구 결과가 있는데, 어떻게 써야 효과적인지 정리해드리겠습니다.

 

 

---

2026.03.18 - [프롬프트 줍줍.zip] - AI 코딩 에이전트 시스템 프롬프트 공유: Antigravity Workflow

AI 코딩 에이전트 시스템 프롬프트 공유: Antigravity Workflow