skill-installer

프로젝트별로 외부 skill을 탐색, 설치, 관리하는 워크플로우를 제공합니다.

Overview

이 skill은 다음 기능을 제공합니다:

• GitHub 저장소에서 사용 가능한 skill 탐색
• 개별 skill 또는 전체 저장소 설치
• 설치된 skill 관리 (목록, 업데이트, 제거)
• .registry.json을 통한 skill 출처 추적

Prerequisites

• 프로젝트가 git 저장소여야 함
• npx 명령어 사용 가능
• .claude/skills/ 디렉토리 존재

Workflows

Workflow 1: 원격 Skill 탐색

목적: GitHub 저장소에서 설치 가능한 skill 목록 확인

절차:

1. 저장소 skill 목록 조회:

   npx add-skill --list <repo-owner>/<repo-name>

   예시:

   npx add-skill --list vercel-labs/agent-skills

2. 출력 분석 및 사용자 제시:

   • 사용자에게 발견된 skill 목록 제시
   • 각 skill의 이름과 설명 포함
   • 설치 가능 여부 확인

3. 대체 방법 (명령어 실패 시):

   • GitHub 저장소 직접 브라우징 (WebFetch 또는 agent-browser skill 사용)
   • prompts/skills/ 디렉토리 구조 파악
   • 각 skill의 SKILL.md 파일에서 메타데이터 추출

출력: 설치 가능한 skill 목록 (이름, 설명, 경로)

---

Workflow 2: Skill 설치

목적: 특정 skill을 프로젝트에 설치하고 registry에 기록

절차:

1. 프로젝트 루트 확인:

   git rev-parse --show-toplevel

   • 현재 디렉토리가 git 저장소 내부인지 확인
   • 프로젝트 루트 경로 저장

2. Skill 설치 실행:

   npx add-skill <repo-owner>/<repo-name>/<skill-name>

   예시:

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

3. 설치 검증:

   • .claude/skills/<skill-name>/ 디렉토리 생성 확인
   • SKILL.md 파일 존재 확인
   • 필수 리소스 파일 확인

4. Registry 업데이트:

   • .claude/skills/.registry.json 파일 읽기 (없으면 생성)
   • 새 skill 정보 추가:

     {
       "<skill-name>": {
         "source": "<repo-owner>/<repo-name>",
         "installedAt": "<ISO-8601-timestamp>",
         "method": "npx add-skill",
         "version": "<commit-hash-or-version>"
       }
     }

   • 파일 저장

5. 설치 완료 보고:

   • 사용자에게 설치 성공 알림
   • Skill 사용법 간단 안내 (SKILL.md의 주요 workflow 요약)

에러 처리:

• 네트워크 오류: 재시도 또는 수동 다운로드 안내
• 이미 설치됨: 덮어쓰기 또는 건너뛰기 옵션 제공
• 권한 오류: sudo 필요 여부 확인

---

Workflow 3: 전체 저장소 설치

목적: 저장소의 모든 skill을 한 번에 설치

절차:

1. 전체 저장소 설치 명령:

   npx add-skill <repo-owner>/<repo-name>

   예시:

   npx add-skill vercel-labs/agent-skills

2. 설치 가능 skill 목록 확인:

   • Workflow 1 사용하여 전체 skill 목록 조회
   • 사용자에게 확인 요청: "총 N개 skill을 설치하시겠습니까?"

3. 개별 설치 반복:

   • 각 skill에 대해 Workflow 2 실행
   • 진행 상황 표시 (예: "3/10 설치 중...")
   • 실패한 skill은 기록하고 계속 진행

4. 설치 요약 보고:

   • 성공: N개
   • 실패: M개 (실패 목록 및 이유)
   • 건너뜀: K개 (이미 설치됨)

최적화:

• 병렬 설치 가능 여부 확인 (의존성 없는 경우)
• 사용자 선택적 설치 옵션 제공 (대화형 모드)

---

Workflow 4: Skill 관리

4.1 설치된 Skill 목록 조회

# .registry.json 읽기
cat .claude/skills/.registry.json | jq '.'

출력 형식:

설치된 Skills:
1. react-best-practices (vercel-labs/agent-skills) - 2026-01-19
2. tdd-practices (local) - 2026-01-10
3. docker-setup (awesome-claude-skills/devops) - 2026-01-15

---

4.2 Skill 업데이트

1. Registry에서 출처 확인:

   {
     "source": "vercel-labs/agent-skills",
     "installedAt": "2026-01-10T10:30:00Z"
   }

2. 최신 버전 확인:

   • GitHub API로 최신 커밋 해시 조회
   • 현재 버전과 비교

3. 업데이트 실행:

   # 기존 skill 백업 (선택 사항)
   mv .claude/skills/<skill-name> .claude/skills/<skill-name>.bak
   
   # 재설치
   npx add-skill <source>/<skill-name>

4. Registry 업데이트:

   • installedAt 갱신
   • version 업데이트

---

4.3 Skill 제거

1. Registry 확인:

   • 제거할 skill이 registry에 등록되어 있는지 확인

2. Skill 디렉토리 삭제:

   rm -rf .claude/skills/<skill-name>

3. Registry 갱신:

   • .registry.json에서 해당 항목 제거
   • 파일 저장

4. 확인 메시지:

   Skill '<skill-name>' 제거 완료
   - 디렉토리 삭제: .claude/skills/<skill-name>
   - Registry 갱신: .registry.json

---

Workflow 5: 알려진 Registry

목적: 추천 skill 저장소 목록 제공

절차:

1. Registry 리소스 파일 읽기:

   # 이 skill의 리소스 디렉토리에서
   cat .claude/skills/skill-installer/resources/01-registries.md

2. 사용자에게 제시:

   • 저장소 이름, URL, 설명
   • 포함된 주요 skill 목록
   • 추천 사용 케이스

3. 선택 및 설치 연계:

   • 사용자가 저장소 선택 시 Workflow 1 또는 3으로 연결

추천 Registry 예시:

## Vercel Labs Agent Skills
- URL: https://github.com/vercel-labs/agent-skills
- Skills: react-best-practices, nextjs-routing, typescript-patterns
- 추천 대상: React/Next.js 프로젝트

## Awesome Claude Skills - DevOps
- URL: https://github.com/awesome-claude/devops-skills
- Skills: docker-setup, kubernetes-deploy, ci-cd-pipelines
- 추천 대상: DevOps/인프라 작업

---

Key Commands Reference

설치 관련

# 개별 skill 설치
npx add-skill <repo-owner>/<repo-name>/<skill-name>

# 전체 저장소 설치
npx add-skill <repo-owner>/<repo-name>

# 설치 가능 목록 조회
npx add-skill --list <repo-owner>/<repo-name>

Registry 관리

# Registry 내용 확인
cat .claude/skills/.registry.json | jq '.'

# 특정 skill 정보 조회
cat .claude/skills/.registry.json | jq '."<skill-name>"'

# 모든 skill 출처 목록
cat .claude/skills/.registry.json | jq 'to_entries | .[] | .key + " (" + .value.source + ")"'

---

.registry.json 구조

{
  "react-best-practices": {
    "source": "vercel-labs/agent-skills",
    "installedAt": "2026-01-19T10:30:00Z",
    "method": "npx add-skill",
    "version": "abc123def456"
  },
  "tdd-practices": {
    "source": "local",
    "installedAt": "2026-01-10T08:00:00Z",
    "method": "manual",
    "notes": "Custom skill for project-specific TDD workflow"
  },
  "docker-setup": {
    "source": "awesome-claude-skills/devops",
    "installedAt": "2026-01-15T14:20:00Z",
    "method": "npx add-skill",
    "version": "xyz789abc012"
  }
}

필드 설명:

• source: 원본 저장소 경로 또는 "local"
• installedAt: ISO-8601 형식 설치 시각
• method: 설치 방법 (npx add-skill, manual, git clone 등)
• version: 커밋 해시 또는 버전 태그 (선택 사항)
• notes: 추가 메모 (선택 사항)

---

Best Practices

1. 설치 전 확인:

   • 프로젝트 루트에서 실행
   • 기존 skill과 이름 충돌 확인

2. Registry 유지 관리:

   • 모든 설치/제거 작업 후 registry 업데이트
   • 정기적으로 출처 확인 (보안)

3. 업데이트 주기:

   • 월 1회 또는 주요 프로젝트 마일스톤 전
   • 변경 사항 확인 후 적용

4. 로컬 커스터마이징:

   • 외부 skill 수정 시 registry에 customized: true 추가
   • 업데이트 시 덮어쓰기 주의

---

Troubleshooting

npx add-skill 명령어가 없는 경우

• 수동 설치 방법:

  git clone https://github.com/<repo> /tmp/skills
  cp -r /tmp/skills/prompts/skills/<skill-name> .claude/skills/

Registry 파일 손상

• 백업에서 복구 또는 재생성:

  # 설치된 skill 목록에서 재구성
  ls .claude/skills/ | jq -R -s 'split("\n") | map(select(length > 0)) | map({(.): {source: "unknown", installedAt: now | todate, method: "recovered"}}) | add'

권한 오류

• 프로젝트 디렉토리 쓰기 권한 확인
• .claude/skills/ 디렉토리 소유자 확인

---

Related Skills

• skill-creator: 새 skill 제작 시 사용
• agent-creator: Skill을 agent로 변환
• claude-guide: Claude Code 프로젝트 초기 설정

---

Resources

• resources/01-registries.md: 추천 skill 저장소 목록
• .registry.json: 현재 프로젝트의 설치된 skill 기록