liuchunming033/skill-doctor

Skill Doctor — Skill 건강 진단 도구

프로세스

1. 지정된 Skill 디렉토리를 읽습니다.
2. 핵심 파일(SKILL.md, gotchas.md 등) 존재 여부를 확인합니다.
3. 스크립트를 호출하여 구조화된 보고서를 생성합니다: python scripts/analyze_skill.py <skill_path> --output json — 각 검사 항목의 점수, 문제점, 제안 사항을 얻습니다.
4. 각 낮은 점수 항목(<70점)에 대해 스크립트 보고서를 기반으로 구체적인 최적화 제안 + 예상 향상 점수 + 작업량 평가를 추가합니다.
5. 최적화 가능한 모든 항목을 나열하고 사용자가 수락할 항목을 선택하도록 합니다.
6. 사용자가 수락한 항목을 하나씩 최적화합니다(파일 직접 수정).
7. 최적화 완료 후 다시 스크립트를 호출하여 재진단하고 전후 비교 보고서를 출력합니다.

에이전트는 지능 계층(최적화 제안, 사용자 상호 작용, 수정 실행)을 담당하고, 스크립트는 안정 계층(점수 계산, 구조화된 출력)을 담당합니다. 스크립트 사용법은 scripts/analyze_skill.py를 참조하세요.

9대 건강 검사 항목

검사 항목	검사 내용	통과 기준
description 검사	트리거 조건으로 작성되었는지, 기능 설명이 아닌지	트리거 키워드 포함, 길이 <100자
gotchas 검사	함정 기록이 있는지	gotchas.md가 존재하고 비어 있지 않음
파일 구성 검사	3분류 표준에 따라 구성되었는지	루트 디렉토리에 SKILL.md + gotchas.md + examples.md만 존재, 참고 자료는 reference/, 스크립트는 scripts/, 설정은 config/
과도한 제약 검사	경로가 과도하게 제약되었는지	"첫 번째 단계", "두 번째 단계" 등의 경직된 흐름이 없음
중복 지식 검사	에이전트가 이미 알고 있는 내용을 반복하는지	"X란 무엇인가", "Y 사용 방법" 등의 튜토리얼이 없음
메모리 설정 검사	config.json이 있는지	config.json이 존재하고 합리적인 설정이 있음
스크립트 검사	스크립트가 필요한데 누락되었는지	안정적인 기능이 필요한 경우 scripts 디렉토리가 있음
hooks 검사	hooks 설정이 올바른지	PreToolUse/PostToolUse 형식이 올바름
markdown 형식 검사	형식이 표준을 따르는지	YAML, 표, 코드 블록 형식이 올바름

건강 검진 보고서 형식

{
  "skill_name": "xxx",
  "overall_score": 55,
  "grade": "D",
  "check_results": {
    "description": {"score": 50, "issues": ["기능 설명으로 작성됨"], "suggestions": ["트리거 조건 문장으로 변경"], "expected_gain": 40},
    "gotchas": {"score": 40, "issues": ["gotchas.md가 빈 껍데기임"], "suggestions": ["3개 이상의 실제 함정 추가"], "expected_gain": 50}
  },
  "optimization_options": [
    {"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
     "effort": "낮음", "action": "description을 트리거 조건 문장으로 다시 작성",
     "token_saved_per_call": 50, "time_saved_per_call_sec": 0},
    {"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
     "effort": "중간", "action": "실제 함정 추가",
     "token_saved_per_call": 0, "time_saved_per_call_sec": 180}
  ],
  "overall_after_accept_all": 85,
  "total_benefits": {
    "token_saved_per_call": 200,
    "time_saved_per_call_sec": 300
  }
}

이점 추정 규칙

최적화 유형	Token 절약(호출당)	시간 절약(호출당)	설명
description 단축	초과 문자당 ×1 token	—	컨텍스트 로드량 감소
gotchas 보충	—	함정당 2-5분	반복적인 함정 디버깅 방지
파일 분할	(원래 줄 수 - 새 줄 수)×3 tokens	—	참고 자료를 reference/로 이동, 필요할 때만 로드하여 컨텍스트에 포함되지 않음
과도한 제약 → 의사 결정 프레임워크	경직된 단계당 ×20 tokens	단계당 10-30초	불필요한 단계 실행 감소
중복 지식 삭제	튜토리얼 단락 길이 tokens	—	에이전트가 이미 알고 있는 내용을 반복하지 않음
스크립트 캡슐화	—	1-3분/회	에이전트가 매번 동일한 코드를 다시 작성하지 않도록 방지

이점은 단일 호출 기준 추정치이며, 실제 값은 Skill 내용 및 사용 방식에 따라 다릅니다.

"시간 소요"에 대한 설명: 보고서의 "시간 소요"는 설계 결함으로 인한 추가 낭비를 의미하며, Skill 실행 총 시간이 아닙니다. 구체적으로는 다음과 같습니다.

• gotchas 누락 → 에이전트가 반복적으로 함정에 빠져 디버깅(2-5분/회)
• 과도한 제약 → 에이전트가 의미 없는 경직된 단계 실행(10-30초/단계)
• 스크립트 누락 → 에이전트가 매번 동일한 코드 재작성(1-3분/회)

비교 논리: 최적화 전 값 = 이러한 낭비의 합계; 최적화 후 낭비가 0으로 감소 → ~0; "절약" = 제거된 낭비량. 최적화 후에도 Skill 실행 자체에는 시간이 필요하지만 이러한 추가 손실은 더 이상 발생하지 않습니다.

최적화 제안 표시

보고서를 생성한 후, 최적화 가능한 항목을 사용자에게 목록 형식으로 표시합니다. 각 항목에는 다음이 포함됩니다:

### 🔧 최적화 가능 항목

| # | 검사 항목 | 현재 점수 | 예상 점수 | 향상 | 작업량 | Token/회 | 시간/회 | 작업 |
|---|-------|--------|--------|------|--------|---------|---------|------|
| 1 | description | 50 | 90 | +40 | 낮음 | ~50 | — | 트리거 조건으로 다시 작성 |
| 2 | gotchas | 40 | 90 | +50 | 중간 | — | ~3분 | 실제 함정 추가 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

**모든 최적화 수락 후**: 55점(D) → 85점(B), 30점 향상

### 📈 종합 이점(단일 호출)
- Token 절약: ~200/회
- 시간 절약: ~5분/회
- 함정 방지: gotchas 보충으로 일반적인 오류 방지 가능

> **시간 통계 기준**: 여기서 "시간 절약"은 **설계 결함으로 인한 추가 낭비**를 의미하며, Skill 실행 총 시간이 아닙니다:
> - gotchas 누락 → 에이전트가 반복적으로 함정에 빠져 디버깅(2-5분/회)
> - 과도한 제약 → 에이전트가 의미 없는 경직된 단계 실행(10-30초/단계)
> - 스크립트 누락 → 에이전트가 매번 동일한 코드 재작성(1-3분/회)
> - 최적화 전 값 = 낭비 합계, 최적화 후 낭비는 0, "절약" = 제거된 낭비량

선택하세요:
- **"모두 수락"** — 모든 항목을 한 번에 최적화
- **"1,3 수락"** — 지정된 항목만 최적화
- **"건너뛰기"** — 보고서만 확인하고 최적화하지 않음

사용자 확인 후 실행

1. 사용자가 선택하면, 해당 파일을 하나씩 수정합니다.
2. 각 항목이 완료될 때마다 상태를 표시합니다.
3. 모든 항목이 완료되면, 재진단을 실행하여 비교 보고서를 생성합니다.

전후 비교 보고서 형식

## 📊 최적화 전후 비교

| 검사 항목 | 최적화 전 | 최적화 후 | 변화 |
|-------|--------|--------|------|
| description | 50 (기능 설명) | 90 (트리거 조건) | +40 ⬆️ |
| gotchas | 40 (빈 껍데기) | 90 (충실) | +50 ⬆️ |
| ... | ... | ... | ... |
| **총점** | **55 (D)** | **85 (B)** | **+30 ⬆️** |

### 📈 종합 이점(단일 호출)
| 차원 | 최적화 전 | 최적화 후 | 절약 |
|------|--------|--------|---------|
| Token | ~800/회 | ~600/회 | ~200/회 |
| 시간 낭비 | ~5분 | ~0 | ~5분 |
| 메인 파일 | 466줄 | 75줄 | -84% |

> 시간 낭비 = 설계 결함으로 인한 추가 오버헤드(함정 디버깅, 중복 단계 등), Skill 실행 총 시간이 아님. [이점 추정 규칙](#이점-추정-규칙) 참조.

### 수정된 파일
- `SKILL.md` — description 다시 작성
- `gotchas.md` — 실제 함점 5개 추가

전체 상호 작용 예시

examples.md 예시 9 참조

점수 등급

• A(90-100점): 우수, 모든 모범 사례 준수
• B(75-89점): 양호, 약간의 최적화 여지 있음
• C(60-74점): 보통, 명확한 개선점 있음
• D(<60점): 불량, 재구성 필요

상세 검사 목록

checklists.md 참조

일반적인 함정

gotchas.md 참조

최적화 예시

examples.md 참조

스크립트

건강 검진 핵심 로직은 scripts/analyze_skill.py에 캡슐화되어 있으며, 에이전트가 이 스크립트를 호출하여 구조화된 점수를 얻습니다:

python scripts/analyze_skill.py <skill_path> --output json    # 단계 3: 점수 보고서 얻기
python scripts/analyze_skill.py <skill_path> --output markdown # 선택 사항: 사람이 읽을 수 있는 보고서 생성

스크립트 담당: 점수 계산, 문제 감지, 등급 판정(안정 계층) 에이전트 담당: 최적화 제안 생성, 사용자 상호 작용, 파일 수정 실행(지능 계층)