Agent Skills 설치
학습 후 할 수 있는 것
- 단일 명령어로 Agent Skills 빠르게 설치(권장)
- 스킬을 Claude Code 로컬 디렉토리에 수동 복사
- claude.ai에서 스킬 활성화 및 네트워크 권한 구성
- 설치 시 일반적인 오류 해결
현재 당면한 문제
Agent Skills을 사용하여 Claude가 프로젝트를 배포하고 코드를 감사하게 하고 싶지만, Claude Code나 claude.ai에 어떻게 설치할지 모릅니다. 또는 설치를 시도했지만 스킬이 활성화되지 않거나 배포 시 "Network Egress Error"가 표시됩니다.
언제 이 기술 사용
- ✓ 첫 번째 Agent Skills 사용
- ✓ Claude Code 사용(터미널 명령행 도구)
- ✓ claude.ai 사용(웹 버전 Claude)
- ✓ 스킬이 네트워크에 액세스해야 함(배포 기능)
🎒 시작 전 준비
시작하기 전에 이미 다음을 완료했는지 확인하세요:
- [ ] Node.js 20+ 버전 설치
- [ ] 사용 중인 Claude Code 또는 claude.ai 계정 존재
팁
아직 Agent Skills가 무엇인지 모르는 경우, 먼저 Agent Skills 소개을 읽어 보는 것을 추천합니다.
핵심 아이디어
Agent Skills 설치에는 두 가지 방법이 있습니다:
- npx 설치(권장): Claude Code에 한 번의 클릭으로 설치, 모든 단계 자동화
- 수동 설치: 지정된 디렉토리에 파일 복사, claude.ai 또는 사용자 정의 설치 위치에 적합
설치 후, 스킬은 Claude에서 자동으로 활성화됩니다—트리거 키워드(예: "Deploy my app")를 입력하기만 하면 Claude가 해당 스킬을 자동으로 호출합니다.
방법 1: npx 빠르게 설치(권장)
이것은 가장 간단한 설치 방법으로, Claude Code 사용자에 적합합니다.
1단계: 설치 명령 실행
터미널에서 다음을 실행합니다:
npx add-skill vercel-labs/agent-skills왜add-skill은 npm 패키지로, Agent Skills를 자동으로 다운로드하고 올바른 디렉토리에 설치합니다.
예상 결과:
Skills successfully installed.2단계: 설치 확인
Claude Code에서 다음을 입력합니다:
List available skills예상 결과: Claude가 반환한 스킬 목록에 다음이 포함:
react-best-practicesweb-design-guidelinesvercel-deploy
검사점 ✅: 3개 스킬이 보이면 설치 성공.
방법 2: Claude Code에 수동 설치
npx를 사용하지 않거나 설치 위치를 제어해야 하는 경우 수동 설치를 사용할 수 있습니다.
1단계: 프로젝트 클론 또는 다운로드
git clone https://github.com/vercel-labs/agent-skills.git
cd agent-skills왜 수동 설치를 위해서는 먼저 프로젝트 소스 코드를 가져와야 합니다.
2단계: 스킬을 Claude Code 디렉토리에 복사
cp -r skills/react-best-practices ~/.claude/skills/
cp -r skills/web-design-guidelines ~/.claude/skills/
cp -r skills/claude.ai/vercel-deploy-claimable ~/.claude/skills/vercel-deploy왜 Claude Code의 스킬은 ~/.claude/skills/ 디렉토리에 저장됩니다. 복사 후 Claude는 이 스킬들을 인식할 수 있습니다.
예상 결과: 명령이 완료된 후 오류 출력 없음.
검사점 ✅: ls ~/.claude/skills/를 확인하여 3개 스킬 디렉토리가 보여야 합니다: react-best-practices, web-design-guidelines, vercel-deploy.
3단계: Claude Code 재시작
Claude Code를 강제 종료한 후 다시 엽니다.
왜 Claude Code는 시작할 때만 스킬 목록을 로드하므로, 새로 설치된 스킬을 인식하려면 재시작해야 합니다.
방법 3: claude.ai에서 스킬 사용
claude.ai(웹 버전 Claude)를 사용하는 경우 설치 방법이 다릅니다.
방법 3.1: 프로젝트 지식 베이스에 추가
1단계: 스킬 파일 선택
skills/react-best-practices, skills/web-design-guidelines, skills/claude.ai/vercel-deploy-claimable 이 세 디렉토리의 모든 파일을 패키징합니다.
왜 claude.ai는 스킬 파일을 프로젝트의 "지식 베이스"로 추가해야 합니다.
2단계: 프로젝트에 업로드
claude.ai에서:
- 새 프로젝트를 만들거나 엽니다
- "Knowledge" → "Add Files" 클릭
- 스킬 파일 업로드(또는 전체 디렉토리)
예상 결과: 지식 베이스에 프로젝트 파일 목록이 표시됩니다.
방법 3.2: SKILL.md 내용 붙여넣기
전체 디렉토리를 업로드하지 않으려면 SKILL.md의 내용을 직접 복사할 수 있습니다.
1단계: 스킬 정의 복사
skills/react-best-practices/SKILL.md을 열고 전체 내용을 복사합니다.
왜SKILL.md는 스킬의 완전 정의를 포함하며, Claude는 이 파일을 통해 스킬의 기능을 이해합니다.
2단계: 대화에 붙여넣기
claude.ai 대화에서 SKILL.md 내용을 붙여넣거나, 프로젝트의 "Instructions"에 추가합니다.
예상 결과: Claude가 스킬 정의를 수신했음을 확인합니다.
네트워크 권한 구성(중요)
vercel-deploy 스킬을 사용하여 프로젝트를 배포하려면 네트워크 권한을 구성해야 합니다.
중요
vercel-deploy 스킬은 파일을 업로드하기 위해 *.vercel.com 도메인에 액세스해야 합니다. 이 단계를 건너뛰면 배포가 실패합니다!
1단계: Claude 기능 설정 열기
브라우저에서 다음을 방문합니다:
https://claude.ai/settings/capabilities왜 여기에서 Claude가 액세스할 수 있는 도메인 목록을 제어할 수 있습니다.
2단계: Vercel 도메인 추가
"Add domain"을 클릭하고 다음을 입력합니다:
*.vercel.com"Save"를 클릭하여 저장합니다.
예상 결과: 도메인 목록에 *.vercel.com이 나타납니다.
검사점 ✅: 도메인이 추가되었으며 스킬은 이제 네트워크에 액세스할 수 있습니다.
일반적인 문제 해결
문제 1: 스킬 활성화 안 됨
현상: "Deploy my app"을 입력하지만 Claude가 무엇을 해야 할지 모릅니다.
가능한 원인:
- Claude Code가 재시작되지 않음(수동 설치 시)
- claude.ai 프로젝트 지식 베이스가 스킬을 올바르게 로드하지 않음
해결 방법:
- Claude Code: 앱 재시작
- claude.ai: 스킬 파일이 프로젝트 Knowledge에 업로드되었는지 확인
문제 2: 배포 실패(Network Egress Error)
현상:
Deployment failed due to network restrictions해결 방법: *.vercel.com이 네트워크 권한에 추가되었는지 확인:
https://claude.ai/settings/capabilities 방문
*.vercel.com 포함 확인문제 3: ~/.claude/skills/ 디렉토리를 찾을 수 없음
현상: 수동 설치 시 디렉토리가 없다는 메시지가 표시됩니다.
해결 방법:
# 디렉토리 수동 생성
mkdir -p ~/.claude/skills
# 스킬 팩 복사
cp -r agent-skills/* ~/.claude/skills/
# 권한 확인
ls -la ~/.claude/skills/예상 결과:
drwxr-xr-x user group size date react-best-practices/
drwxr-xr-x user group size date web-design-guidelines/
drwxr-xr-x user group size date vercel-deploy-claimable/문제 4: npx 설치 실패
현상:
npx: command not found해결 방법:
# Node.js 및 npm 설치 확인
node -v
npm -v
# 설치되지 않은 경우 https://nodejs.org/에서 LTS 버전 설치이 과정 요약
이 과정은 Agent Skills 설치를 위한 세 가지 방법을 소개합니다:
- npx 빠르게 설치: Claude Code에 권장, 한 번의 클릭으로 완료
- 수동 설치:
~/.claude/skills/에 파일 복사, 설치 위치 제어 필요 시 적합 - claude.ai 설치: 프로젝트 지식 베이스에 파일 업로드 또는
SKILL.md붙여넣기
vercel-deploy 스킬을 사용하는 경우, https://claude.ai/settings/capabilities에서 *.vercel.com 네트워크 권한 추가를 잊지 마세요.
설치 완료 후, Claude가 코드 감사, 접근성 확인 및 프로젝트 배포를 위해 이 스킬들을 자동으로 사용할 수 있습니다.
다음 과정 예고
다음 과정에서는 **React/Next.js 성능 최적화 베스트 프랙티스**을 학습합니다.
배우게 될 것:
- 57개 React 성능 최적화 규칙 사용 방법
- 워터폴 제거, 번들 최적화, Re-render 감소
- AI가 코드를 자동으로 감사하고 수정 제안을 제공하는 방법
부록: 소스 참고
클릭하여 소스 코드 위치 펼치기
업데이트 날짜: 2026-01-25
| 기능 | 파일 경로 | 행번호 |
|---|---|---|
| npx 설치 방법 | README.md:83-86 | 83-86 |
| Claude Code 수동 설치 | AGENTS.md:98-105 | 98-105 |
| claude.ai 설치 방법 | AGENTS.md:106-109 | 106-109 |
| 네트워크 권한 구성 | skills/claude.ai/vercel-deploy-claimable/SKILL.md:104-112 | 104-112 |
핵심 스킬 팩:
react-best-practices: 57개 React 성능 최적화 규칙(실제 규칙 파일 수)web-design-guidelines: 100+ 개 웹 디자인 가이드 규칙vercel-deploy: Vercel 원클릭 배포(40+ 프레임워크 지원)