Add self-improve-skill: 기존 스킬 종합 분석 및 개선 스킬

2026-06-12 19:15:14 +09:00
parent 6e21501331
commit 9afc5f4491
7 changed files with 945 additions and 0 deletions
@@ -0,0 +1,187 @@
+# 완전성 분석 가이드
+
+대상 스킬의 에러 핸들링, 교차참조, 메타데이터 완전성을 분석하는 가이드입니다.
+
+## 분석 대상
+
+| 항목 | 검사 내용 |
+|------|----------|
+| 에러 핸들링 | 에러 처리 테이블 존재, 시나리오 커버리지, 해결책 명시 |
+| 교차참조 | 다른 스킬과의 연결, 링크 유효성 |
+| 메타데이터 | 버전, 작성자, 라이센스, 의존성 |
+| 스크립트 경로 | 참조된 스크립트의 실제 존재 여부 |
+
+## 에러 핸들링 검증
+
+### 필수 요소
+
+| 요소 | 검사 내용 | 필수 |
+|------|----------|------|
+| 에러 테이블 | "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]
+```
@@ -0,0 +1,154 @@
+# 문서 분석 가이드
+
+대상 스킬의 문서 품질을 분석하는 가이드입니다.
+
+## 분석 대상
+
+| 항목 | 검사 내용 |
+|------|----------|
+| 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
+...
+```
@@ -0,0 +1,117 @@
+# 구조 분석 가이드
+
+대상 스킬의 디렉토리 구조와 리소스를 분석하는 가이드입니다.
+
+## 분석 대상
+
+| 항목 | 검사 내용 |
+|------|----------|
+| 디렉토리 존재 | 스킬 루트 디렉토리 존재 여부 |
+| 파일 naming | lowercase + hyphenated 일관성 |
+| 리소스 디렉토리 | references/, scripts/, templates/, workflows/ 존재 여부 |
+| 리소스 파일 | 참조된 파일의 실제 존재 여부 |
+
+## 디렉토리 구조 점검
+
+### 필수 구조
+
+```
+skill-name/
+├── SKILL.md              # 필수
+└── config.yaml           # 선택 (파라미터가 있는 경우)
+```
+
+### 권장 리소스 디렉토리
+
+| 디렉토리 | 용도 | 필수 여부 |
+|----------|------|-----------|
+| `references/` | 상세 참고 문서 | 선택 |
+| `scripts/` | 실행 가능한 스크립트 | 선택 |
+| `templates/` | Mustache/Handlebars 템플릿 | 선택 |
+| `workflows/` | 단계별 워크플로우 가이드 | 선택 |
+| `analysis/` | 분석 가이드 문서 | 선택 |
+| `pipeline/` | 파이프라인 단계 문서 | 선택 |
+| `feedback/` | 피드백 관련 문서 | 선택 |
+
+### 파일 naming 규칙
+
+| 유형 | 규칙 | 예시 |
+|------|------|------|
+| 디렉토리 | lowercase, hyphenated | `self-study-agent/` |
+| 마크다운 | lowercase, hyphenated | `analysis-checklist.md` |
+| 스크립트 | snake_case | `query_capacity.sh` |
+| 설정 파일 | camelCase 또는 snake_case | `config.yaml` |
+
+## 리소스 존재 여부 검사
+
+### 검사 방법
+
+1. SKILL.md에서 파일 참조 검색
+   - 마크다운 링크: `[text](path/to/file.md)`
+   - 코드 블록 참조: `` `scripts/example.sh` ``
+   - 테이블 참조: `| 파일 | path/to/file |`
+
+2. 참조된 파일의 실제 존재 여부 확인
+
+3. 존재하지 않는 파일 목록 생성
+
+### 검사 항목
+
+| 항목 | 검사 내용 | 기준 |
+|------|----------|------|
+| 스크립트 파일 | scripts/ 디렉토리 내 존재 | 참조 대비 100% 존재 |
+| 템플릿 파일 | templates/ 디렉토리 내 존재 | 참조 대비 100% 존재 |
+| 참조 문서 | references/ 디렉토리 내 존재 | 참조 대비 100% 존재 |
+| 파이프라인 문서 | pipeline/ 디렉토리 내 존재 | 참조 대비 100% 존재 |
+
+## 점수 산출
+
+| 항목 | 배점 | 감점 기준 |
+|------|------|----------|
+| SKILL.md 존재 | 30점 | 없으면 0점 |
+| 디렉토리 naming | 10점 | 비일관적 -5점 |
+| 파일 naming | 10점 | 비일관적 -5점 |
+| 리소스 디렉토리 | 20점 | 누락당 -5점 |
+| 리소스 파일 존재 | 30점 | 누락당 -10점 |
+
+## 개선 패턴
+
+### 패턴 1: 리소스 디렉토리 누락
+
+**현재:**
+```
+skill-name/
+└── SKILL.md
+```
+
+**개선:**
+```
+skill-name/
+├── SKILL.md
+├── references/
+│   └── detailed-guide.md
+└── templates/
+    └── output-template.md
+```
+
+### 패턴 2: 파일 naming 비일관성
+
+**현재:**
+```
+scripts/MyScript.sh
+scripts/another_script.py
+references/SomeDoc.md
+```
+
+**개선:**
+```
+scripts/my_script.sh
+scripts/another_script.py
+references/some-doc.md
+```
+
+### 패턴 3: 참조된 파일 누락
+
+**현재:** SKILL.md에서 `scripts/process.sh` 참조하지만 파일 없음
+
+**개선:** 해당 스크립트 파일 생성 또는 참조 제거
@@ -0,0 +1,163 @@
+# 워크플로우 분석 가이드
+
+대상 스킬의 워크플로우 완성도를 분석하는 가이드입니다.
+
+## 분석 대상
+
+| 항목 | 검사 내용 |
+|------|----------|
+| 단계 명확성 | 각 단계가 명확하게 정의되어 있는지 |
+| 분기 처리 | 조건 분기가 적절히 처리되어 있는지 |
+| 실행 가능성 | 제시된 단계가 실제로 실행 가능한지 |
+| 테스트 시나리오 | 검증 가능한 시나리오가 있는지 |
+
+## 단계 명확성 검증
+
+### 양호한 워크플로우 예시
+
+```markdown
+## Workflow
+
+### Phase 1: 주제 선택
+- 사용자 입력 파싱
+- 범위 분석
+- 너무 넓으면 → 사용자에게 초점 요청
+
+### Phase 2: 소스 발견
+- 각 하위 주제에 대해:
+  1. 권위 있는 소스 검색
+  2. 신뢰도 점수 산출
+  3. 임계값 미달 시 재검색
+```
+
+### 부적절한 워크플로우 예시
+
+```markdown
+## Workflow
+1. 분석한다
+2. 개선한다
+3. 완료한다
+```
+
+### 검사 기준
+
+| 기준 | 양호 | 부적절 |
+|------|------|--------|
+| 단계 이름 | "주제 선택", "소스 발견" | "1단계", "분석" |
+| 단계 설명 | 구체적 행동 명시 | 추상적 표현 |
+| 입출력 | 명시됨 | 미명시 |
+| 조건 분기 | if/then 명시 | 분기 없음 |
+
+## 분기 처리 검증
+
+### 분기 유형
+
+| 유형 | 설명 | 예시 |
+|------|------|------|
+| 조건 분기 | 특정 조건에 따른 경로 분기 | "주제가 너무 넓으면 → 초점 요청" |
+| 반복 분기 | 루프 처리 | "임계값 미달 시 → 재검색" |
+| 예외 분기 | 오류/예외 상황 처리 | "파일 없음 → 에러 메시지" |
+
+### 검사 항목
+
+| 항목 | 검사 내용 |
+|------|----------|
+| 분기 존재 | 필수적인 분기가 명시되어 있는지 |
+| 분기 조건 | 조건이 명확하게 정의되어 있는지 |
+| 분기 결과 | 각 분기의 결과가 명시되어 있는지 |
+| 루프 처리 | 반복 작업의 종료 조건이 있는지 |
+
+## 실행 가능성 검증
+
+### 검사 기준
+
+| 기준 | 설명 |
+|------|------|
+| 도구 가용성 | 제시된 도구/명령어가 실제로 존재하는지 |
+| 환경 요구사항 | 필요한 환경이 명시되어 있는지 |
+| 권한 | 필요한 권한이 명시되어 있는지 |
+| 데이터 가용성 | 필요한 데이터/입력이 확보 가능한지 |
+
+### 일반적인 실행 불가 사례
+
+| 사례 | 설명 |
+|------|------|
+| 존재하지 않는 명령어 | `git push --force-with-lease --all` (실제로는 `--force`) |
+| 잘못된 경로 | `./scripts/old-name.sh` (실제로는 `./scripts/new-name.sh`) |
+| 미구현 기능 | "LLM이 자동으로 판단한다" (구체적 로직 없음) |
+| 환경 미명시 | "API 키가 필요하다" (어디서 obtained?)
+
+## 테스트 시나리오 검증
+
+### 검사 항목
+
+| 항목 | 검사 내용 |
+|------|----------|
+| 테스트 존재 | 테스트 시나리오/예시가 있는지 |
+| 시나리오 다양성 | 정상/예외/경계값 시나리오 포함 |
+| 기대 결과 | 각 시나리오의 기대 결과가 명시 |
+| 검증 가능 | 결과를 검증할 수 있는 기준이 있는지 |
+
+## 점수 산출
+
+| 항목 | 배점 | 감점 기준 |
+|------|------|----------|
+| 단계 명확성 | 30점 | 추상적 표현당 -5점 |
+| 분기 처리 | 25점 | 필수 분기 누락 -10점 |
+| 실행 가능성 | 25점 | 실행 불가 항목당 -10점 |
+| 테스트 시나리오 | 20점 | 없음 -20점, 부족함 -10점 |
+
+## 개선 패턴
+
+### 패턴 1: 단계 추상화 개선
+
+**현재:**
+```markdown
+### Phase 1: 분석
+대상을 분석한다.
+```
+
+**개선:**
+```markdown
+### Phase 1: 대상 분석
+1. SKILL.md 파일 읽기
+2. Frontmatter 파싱
+3. 섹션 구조 매핑
+4. 참조 파일 목록 추출
+```
+
+### 패턴 2: 분기 처리 추가
+
+**현재:**
+```markdown
+### Phase 2: 소스 발견
+소스를 검색한다.
+```
+
+**개선:**
+```markdown
+### Phase 2: 소스 발견
+1. 소스 검색
+2. 신뢰도 점수 산출
+3. 임계값(0.6) 이상 → 채택
+4. 임계값 미달 → 대체 키워드로 재검색 (최대 3회)
+5. 3회 미달 시 → 사용자에게 소스 부족 알림
+```
+
+### 패턴 3: 테스트 시나리오 추가
+
+**현재:**
+```markdown
+## 사용 예시
+```
+
+**개선:**
+```markdown
+## 테스트 시나리오
+
+| 시나리오 | 입력 | 기대 결과 |
+|----------|------|-----------|
+| 정상 | 유효한 SKILL.md 경로 | 개선 보고서 생성 |
+| 예외 | 잘못된 경로 | 에러 메시지 + 경로 재요청 |
+| 경계값 | 빈 SKILL.md | "파일이 비어 있습니다" 안내 |
+```