155 lines
3.4 KiB
Markdown
155 lines
3.4 KiB
Markdown
# 문서 분석 가이드
|
|
|
|
대상 스킬의 문서 품질을 분석하는 가이드입니다.
|
|
|
|
## 분석 대상
|
|
|
|
| 항목 | 검사 내용 |
|
|
|------|----------|
|
|
| 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
|
|
...
|
|
```
|