스킬 리뷰 및 검증
프로세스
1단계: 스킬 파일 찾기
입력을 다음 중 하나로 받습니다:
- 스킬 디렉토리 경로
- 스킬 이름 (
~/.claude/skills/에서 검색) - GitHub 저장소 URL
모든 .md 파일, 스크립트, 에셋 파일을 읽습니다.
2단계: 구조 검증
프로그래매틱 검사를 위해 python scripts/validate_skill.py <path>를 실행합니다.
수동 확인:
- SKILL.md 파일 존재 (정확한 대소문자)
- 스킬 폴더 내에 README.md 없음
- 폴더 이름이
name필드와 일치 - 유효한 케밥-케이스 이름 (1~64자)
- 이름에 "claude" 또는 "anthropic" 없음
3단계: 프론트매터 감사
| 검사 항목 | 통과 기준 |
|---|---|
| 이름 형식 | 케밥-케이스, 1~64자, 선행/후행 하이픈 없음 |
| 설명 존재 | 비어 있지 않음, 1~1024자 |
| 설명에 WHAT 포함 | 기능 설명 |
| 설명에 WHEN 포함 | 트리거 구문 포함 |
| 설명에 키워드 포함 | 도메인 특화 용어 포함 |
| XML 태그 없음 | < 또는 > 문자 없음 |
| 선택적 필드 유효 | license, compatibility (500자 미만), metadata |
4단계: 트리거링 분석
활성화 품질에 대한 설명 평가:
언더트리거링 위험:
- 너무 일반적임 ("프로젝트 도움")
- 일반적인 의역 누락
- 도메인 키워드 없음
- 파일 형식 언급 누락 (해당되는 경우)
오버트리거링 위험:
- 너무 광범위함 ("문서 처리")
- 내장된 Claude 기능과 겹침
- 명확성을 위한 부정 트리거 누락
테스트 쿼리 생성:
- 스킬이 트리거되어야 하는 쿼리 5개
- 스킬이 트리거되지 않아야 하는 쿼리 5개
- 에지 케이스 3개 (모호한 쿼리)
5단계: 명령어 품질
| 기준 | 점수 (0~10) |
|---|---|
| 구체성 | 명령이 실행 가능한가? ("적절히 검증"이 아님) |
| 완전성 | 모든 워크플로우가 다루어졌는가? |
| 오류 처리 | 일반적인 오류가 처리되었는가? |
| 예시 | 구체적인 예시가 제공되었는가? |
| 점진적 공개 | 상세 문서는 SKILL.md가 아닌 references/에 있는가? |
| 길이 | 500줄 / 5000 토큰 미만인가? |
| 상호 참조 | references/scripts/에 대한 명확한 링크? |
6단계: 아키텍처 리뷰 (멀티 스킬)
서브 스킬이 있는 경우:
- 메인 스킬에 명확한 라우팅 테이블이 있음
- 서브 스킬에 집중된 책임이 있음
- 상호 참조가 유효함 (파일 존재)
- 이름이
부모-자식규칙을 따름 - 공유 참조는 부모에 있으며, 중복되지 않음
- 에이전트에 명확한 역할이 있음 (Tier 4인 경우)
7단계: 스크립트 품질 (있는 경우)
- 목적, 입력, 출력에 대한 독스트링
- CLI 인터페이스 (argparse 또는 유사)
- 구조화된 출력 (JSON)
- 오류 처리 (try/except와 명확한 메시지)
- 하드코딩된 경로나 비밀 정보 없음
- 최소한의 종속성
8단계: 스킬 건강 점수 생성
점수 매기기 방법론 (0~100):
| 카테고리 | 가중치 | 검사 항목 |
|---|---|---|
| 프론트매터 품질 | 25% | 이름, 설명, 형식 |
| 트리거 정확도 | 20% | WHAT + WHEN + 키워드 |
| 명령어 품질 | 25% | 구체성, 완전성, 예시 |
| 구조 준수 | 15% | 파일 이름 지정, 조직, 참조 |
| 스크립트 품질 | 10% | 해당되는 경우 (스크립트가 필요 없는 경우 만점) |
| 점진적 공개 | 5% | 3단계 시스템의 적절한 사용 |
9단계: 트리거 평가 세트 생성
리뷰 후, 지속적인 테스트를 위한 구조화된 트리거 평가 세트를 생성합니다:
python scripts/generate_eval_set.py <path>를 실행하여 시작 세트를 자동 생성합니다.- 생성된 쿼리를 검토하고 개선합니다:
- 8~10개의 트리거되어야 하는 쿼리가 다양한 표현과 에지 케이스를 다루어야 함
- 8~10개의 트리거되지 않아야 하는 쿼리는 명백히 관련 없는 것이 아니라 거의 맞는 쿼리여야 함
- 트리거 세트에 일상적인 표현, 오타, 일반적이지 않은 도메인 사용을 포함
- 평가 세트를 스킬 디렉토리의
evals/evals.json에 저장합니다.
좋은 쿼리는 현실적이고 구체적입니다 (파일 경로, 컨텍스트, 도메인 세부 정보 포함). 나쁜 쿼리는 지나치게 일반적이거나 ("이 데이터 형식 지정") 명백히 관련이 없습니다.
python scripts/optimize_description.py <path> --eval-set evals/evals.json을 실행하여 현재 설명을 점수화하고 개선 제안을 얻습니다.- 전체 기능 평가를 위해
/skill-forge eval <path>를 실행할 것을 권장합니다.
10단계: 보고서 생성
# 스킬 리뷰: [이름]
## 건강 점수: [X]/100
## 요약
[2~3문장 평가]
## 카테고리별 점수
| 카테고리 | 점수 | 비고 |
|----------|-------|-------|
| 프론트매터 | X/25 | [이슈] |
| 트리거링 | X/20 | [이슈] |
| 명령어 | X/25 | [이슈] |
| 구조 | X/15 | [이슈] |
| 스크립트 | X/10 | [이슈] |
| 공개 | X/5 | [이슈] |
## 중요 이슈 (즉시 수정)
- [이슈 1]
- [이슈 2]
## 높은 우선순위 (1주 이내 수정)
- [이슈 1]
## 권장 사항
- [제안 1]
- [제안 2]
## 제안된 테스트 쿼리
### 트리거되어야 함
1. [쿼리]
2. [쿼리]
3. [쿼리]
### 트리거되지 않아야 함
1. [쿼리]
2. [쿼리]
3. [쿼리]