Study/skills/self-improve-skill/analysis/documentation-analysis.md

문서 분석 가이드

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

분석 대상

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

Frontmatter 검증

필수 필드

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

권장 필드

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

description 패턴 검증

양호한 예시:

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

부적절한 예시:

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 누락

현재:

# My Skill

이 스킬은 ...

개선:

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

# My Skill

이 스킬은 ...

패턴 2: description 패턴 부재

현재:

description: "스킬 설명"

개선:

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

패턴 3: 섹션 구조 부실

현재:

# Skill
## 설정
...

개선:

# Skill
한 문단 요약

## When to Use
...

## Workflow
...

## Error Handling
...