# 완전성 분석 가이드

대상 스킬의 에러 핸들링, 교차참조, 메타데이터 완전성을 분석하는 가이드입니다.

## 분석 대상

| 항목 | 검사 내용 |
|------|----------|
| 에러 핸들링 | 에러 처리 테이블 존재, 시나리오 커버리지, 해결책 명시 |
| 교차참조 | 다른 스킬과의 연결, 링크 유효성 |
| 메타데이터 | 버전, 작성자, 라이센스, 의존성 |
| 스크립트 경로 | 참조된 스크립트의 실제 존재 여부 |

## 에러 핸들링 검증

### 필수 요소

| 요소 | 검사 내용 | 필수 |
|------|----------|------|
| 에러 테이블 | "Error Handling" 또는 "에러 처리" 섹션 | 예 |
| 시나리오 | 최소 3개 이상의 에러 시나리오 | 예 |
| 해결책 | 각 시나리오별 해결 방법 명시 | 예 |

### 양호한 에러 핸들링 예시

```markdown
## Error Handling

| 상황 | 대응 |
|------|------|
| 경로 없음 | 사용자에게 SKILL.md 경로 요청 |
| 파일 없음 | 해당 경로에 SKILL.md가 없음 안내 |
| 읽기 실패 | 파일 권한 확인, 대체 경로 제안 |
```

### 부적절한 에러 핸들링 예시

```markdown
## Error Handling
에러가 발생하면 사용자에게 알립니다.
```

### 시나리오 커버리지 검사

| 카테고리 | 필수 시나리오 |
|----------|-------------|
| 입력 에러 | 잘못된 경로, 없는 파일, 빈 파일 |
| 권한 에러 | 읽기 불가, 쓰기 불가 |
| 환경 에러 | 필수 도구 미설치, 네트워크 불가 |
| 논리 에러 | 분석 불가, 형식 비표준 |

## 교차참조 검증

### 검사 항목

| 항목 | 검사 내용 |
|------|----------|
| 내부 링크 | 같은 스킬 내 다른 파일 참조 유효성 |
| 외부 링크 | 다른 스킬로의 참조 유효성 |
| 관련 스킬 | "Related Skills" 또는 "관련 스킬" 섹션 존재 |

### 내부 링크 검증

1. SKILL.md에서 마크다운 링크 추출
   - `[text](path/to/file.md)` 패턴
   - `| 경로 | path/to/file |` 테이블 패턴

2. 참조된 파일의 실제 존재 여부 확인

3. 존재하지 않는 파일 목록 생성

### 외부 링크 검증

1. 다른 스킬 디렉토리로의 참조 검색
2. 참조된 스킬이 실제로 존재하는지 확인
3. 스킬 이름 변경/이전에 따른 깨진 링크 탐지

## 메타데이터 검증

### 필수 메타데이터

| 필드 | 검사 내용 | 필수 |
|------|----------|------|
| `version` | SemVer 형식 (x.y.z) | 예 |
| `author` | 작성자 명시 | 예 |
| `tags` | 분류 태그 | 권장 |
| `dependencies` | 의존성 목록 | 권장 |
| `license` | 라이센스 | 선택 |

### 버전 검증

| 항목 | 검사 내용 |
|------|----------|
| 형식 | SemVer (major.minor.patch) |
| 일관성 | 같은 프로젝트 내 버전 체계 일관 |
| 의미 | 버전 번호가 의미 있게 증가 |

## 스크립트 경로 검증

### 검사 방법

1. SKILL.md에서 코드 블록/테이블 내 스크립트 참조 추출
   - `./scripts/example.sh`
   - `scripts/example.py`
   - `` `scripts/example.sh` ``

2. 참조된 스크립트의 실제 존재 여부 확인

3. 스크립트 실행 권한 확인 (선택)

### 일반적인 문제

| 문제 | 설명 |
|------|------|
| 경로 변경 | 스크립트 이전 후 경로 미갱신 |
| 파일명 변경 | 스크립트 이름 변경 후 참조 미갱신 |
| 삭제된 스크립트 | 스크립트 삭제 후 참조 유지 |
| 권한 부재 | 스크립트 존재하나 실행 권한 없음 |

## 점수 산출

| 항목 | 배점 | 감점 기준 |
|------|------|----------|
| 에러 핸들링 테이블 | 30점 | 없음 -30점, 부족함 -15점 |
| 시나리오 커버리지 | 20점 | 카테고리당 -5점 |
| 교차참조 유효성 | 20점 | 깨진 링크당 -10점 |
| 메타데이터 | 15점 | 필수 필드 누락당 -8점 |
| 스크립트 경로 | 15점 | 누락당 -10점 |

## 개선 패턴

### 패턴 1: 에러 핸들링 추가

**현재:**
```markdown
## Error Handling
에러가 발생하면 알립니다.
```

**개선:**
```markdown
## Error Handling

| 상황 | 대응 |
|------|------|
| 경로 없음 | 사용자에게 SKILL.md 경로 요청 |
| 파일 없음 | 해당 경로에 SKILL.md가 없음 안내 |
| 읽기 실패 | 파일 권한 확인, 대체 경로 제안 |
| 백업 실패 | 수정 전 사용자에게 경고 |
| 분석 불가 | 스킬 형식이 비표준인 경우 분석 범위 제한 안내 |
```

### 패턴 2: 교차참조 추가

**현재:**
```markdown
## Related Skills
- deploy-model
```

**개선:**
```markdown
## Related Skills

| 스킬 | 관계 | 경로 |
|------|------|------|
| deploy-model | 배포 후 검증 | [deploy-model](../deploy-model/SKILL.md) |
| capacity | 배포 전 용량 확인 | [capacity](../capacity/SKILL.md) |
```

### 패턴 3: 메타데이터 보강

**현재:**
```yaml
name: my-skill
description: "설명"
```

**개선:**
```yaml
name: my-skill
description: "설명. Use for: ... DO NOT USE FOR: ..."
version: 1.0.0
author: User
tags: [tag1, tag2]
dependencies: [tool1, tool2]
```