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

완전성 분석 가이드

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

분석 대상

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

에러 핸들링 검증

필수 요소

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

양호한 에러 핸들링 예시

## Error Handling

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

부적절한 에러 핸들링 예시

## 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: 에러 핸들링 추가

현재:

## Error Handling
에러가 발생하면 알립니다.

개선:

## Error Handling

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

패턴 2: 교차참조 추가

현재:

## Related Skills
- deploy-model

개선:

## Related Skills

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

패턴 3: 메타데이터 보강

현재:

name: my-skill
description: "설명"

개선:

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