# 문서 분석 가이드

대상 스킬의 문서 품질을 분석하는 가이드입니다.

## 분석 대상

| 항목 | 검사 내용 |
|------|----------|
| Frontmatter | 필수 필드, 형식, description 패턴 |
| 섹션 구조 | 헤딩 계층, 필수 섹션 존재 |
| 가독성 | 문장 길이, 단락 구조, 일관성 |

## Frontmatter 검증

### 필수 필드

| 필드 | 필수 | 형식 | 검사 내용 |
|------|------|------|----------|
| `name` | 예 | lowercase-hyphenated | 디렉토리명과 일치 |
| `description` | 예 | 문자열 | USE FOR/DO NOT USE FOR 패턴 |
| `version` | 예 | SemVer (x.y.z) | 형식 일치 |
| `author` | 예 | 문자열 | 존재 여부 |

### 권장 필드

| 필드 | 용도 |
|------|------|
| `tags` | 스킬 분류 태그 |
| `dependencies` | 필요한 도구/의존성 |
| `license` | 라이센스 |

### description 패턴 검증

양호한 예시:
```yaml
description: "기존 스킬을 종합 분석하고 개선안을 제시합니다. Use for skill improvement, 스킬 개선. DO NOT USE FOR: 새로운 스킬 생성."
```

부적절한 예시:
```yaml
description: "스킬을 분석합니다."  # USE FOR/DO NOT USE FOR 누락
```

## 섹션 구조 검증

### 필수 섹션

| 섹션 | 검사 내용 | 필수 |
|------|----------|------|
| H1 제목 | 스킬 이름 명시 | 예 |
| Purpose/목적 | 한 문단 요약 | 예 |

### 권장 섹션

| 섹션 | 검사 내용 | 권장 |
|------|----------|------|
| When to Use | 트리거 의도 명시 | 강력 권장 |
| Workflow/워크플로우 | 단계별 절차 | 강력 권장 |
| Error Handling | 에러 처리 테이블 | 권장 |
| Examples/사용 예시 | 구체적 사용법 | 권장 |
| Prerequisites | 사전 요구사항 | 선택 |

### 헤딩 계층 규칙

| 규칙 | 설명 |
|------|------|
| H1 1개만 | 파일당 H1은 1개 |
| 계층 순서 | H1 → H2 → H3 순서 |
| 최대 깊이 | H4 이상 지양 |
| 일관성 | 같은ឋ위의 섹션은 같은 헤딩 레벨 |

## 가독성 검증

### 검사 항목

| 항목 | 기준 | 감점 |
|------|------|------|
| 단락 길이 | 5줄 이하 | 초과 시 -2 |
| 문장 길이 | 100자 이하 | 초과 시 -1 |
| 표 사용 | 복잡한 설명은 표로 | 미사용 시 -2 |
| 코드 블록 | 명령어/코드는 코드 블록 | 미사용 시 -2 |
| 일관성 | 같은 패턴의 반복 | 비일관적 -3 |

## 점수 산출

| 항목 | 배점 | 감점 기준 |
|------|------|----------|
| Frontmatter 필수 필드 | 25점 | 누락당 -8점 |
| description 패턴 | 15점 | USE FOR 없음 -10점, DO NOT USE FOR 없음 -5점 |
| 필수 섹션 존재 | 20점 | 누락당 -10점 |
| 권장 섹션 존재 | 10점 | 누락당 -3점 |
| 헤딩 계층 | 10점 | 비일관적 -5점 |
| 가독성 | 20점 | 항목당 감점 |

## 개선 패턴

### 패턴 1: Frontmatter 누락

**현재:**
```markdown
# My Skill

이 스킬은 ...
```

**개선:**
```markdown
---
name: my-skill
description: "설명. Use for: ... DO NOT USE FOR: ..."
version: 1.0.0
author: User
---

# My Skill

이 스킬은 ...
```

### 패턴 2: description 패턴 부재

**현재:**
```yaml
description: "스킬 설명"
```

**개선:**
```yaml
description: "스킬 설명. Use for: 키워드1, 키워드2. DO NOT USE FOR: 다른 작업 (대체 스킬명)."
```

### 패턴 3: 섹션 구조 부실

**현재:**
```markdown
# Skill
## 설정
...
```

**개선:**
```markdown
# Skill
한 문단 요약

## When to Use
...

## Workflow
...

## Error Handling
...
```