skill-doctor은(는) 무엇을 하나요?
스킬 라이브러리를 진단하세요. 동일한 프롬프트를 경쟁하는 설명을 가진 스킬을 찾고, 라우팅을 수정하세요.
실행 시점
- 여러 스킬을 설치했는데 "잘못된 스킬이 계속 실행될 때"
- 스킬 팩을 출시하기 전에 (리뷰어가 겪을 충돌을 잡기 위해)
- 스킬을 추가한 후 (기존 스킬과 충돌하는가?)
- 스킬 라이브러리가 커질 때 정기적인 건강 검진
입력
엔진에 다음 중 하나를 지정하세요:
- 스킬 디렉토리 (
<root>/<name>/SKILL.md), 또는 - Claude Code manifest.json (
skills-plugin/.../manifest.json)
실행 방법
엔진은 이 파일과 같은 디렉토리의 scripts/ 안에 있습니다. 의존성 제로 (Python 3.8+ 표준 라이브러리).
# 이 SKILL.md 파일이 있는 디렉토리에서:
python3 -m scripts <skills-또는-manifest-경로> # Markdown 보고서
python3 -m scripts <경로> --format json --out report.json # 기계 출력
python3 -m scripts <경로> --fail-on critical # CI 게이트 (종료 코드 1)
일반 옵션:
--merge-at 0.55— MERGE 권장을 트리거하는 충돌 점수--disambig-at 0.30— DISAMBIGUATE 권장을 트리거하는 점수--vague-threshold 0.5— 이보다 모호한 설명을 플래그--top 12— 표시할 상위 충돌 개수--format md|json|both
감지 항목 (이슈 코드)
| 코드 | 심각도 | 의미 |
|---|---|---|
DUPLICATE_TRIGGER | 🔴 | 동일한 트리거 문구를 2개 이상의 스킬이 사용 (잘못된 라우팅의 주요 원인) |
DUPLICATE_NAME | 🔴 | 두 스킬이 같은 이름 공유 |
MISSING_DESCRIPTION | 🔴 | 스킬이 안정적으로 트리거될 수 없음 |
HIGH_OVERLAP | 🔴/🟠 | 두 설명이 의미상 너무 가까움 |
VAGUE_DESCRIPTION | 🟠 | 불필요한 내용이 많고, "이런 경우 사용", 트리거 없음 |
NAME_DIR_MISMATCH | 🟠 | 이름 ≠ 디렉토리 (스펙 위반) |
BAD_NAME_FORMAT | 🟠 | 이름이 소문자/하이픈 규칙을 위반 |
DESC_TOO_SHORT / DESC_TOO_LONG | 🟠/🟡 | 40–1024자 범위 밖 |
NO_BOUNDARY | 🟡 | "X의 경우 <다른 스킬>을 참조"와 같은 상호 참조 없음 |
BODY_TOO_LONG | 🔵 | SKILL.md 본문이 500줄 초과 |
점수 계산 방식 (한 줄 요약)
충돌 = 0.50·코사인(설명의 TF-IDF)
+ 0.35·자카드(트리거 문구)
+ 0.15·자카드(도메인 키워드)
구간: <0.22 낮음 · 0.22 중간 · 0.38 높음 · 0.55 심각.
전체 설명은 references/scoring.md를 참조.
에이전트 워크플로우
- 사용자의 스킬 경로에서 엔진 실행 → Markdown 보고서 읽기.
- 건강 점수, 최악의 클러스터, 중복 트리거 요약.
- 각 상위 권장 사항에 대해 구체적인 수정 제안:
MERGE→ 결합된 설명 초안, 유지할 이름 제안.ABSORB→ 삭제할 스킬과 트리거가 이동할 위치 지정.DISAMBIGUATE→ 두 개의 경계 줄 작성 ("X의 경우 Y를 참조").
- 설명 다시 쓰기 적용 제안 (각 SKILL.md 프론트매터 편집).
- 재실행하여 건강 점수 개선 확인.
출력
- Markdown 보고서: 건강 점수, 상위 충돌, 혼동 가능한 클러스터, 중복 트리거 표, 권장 사항, 전체 이슈 목록, ASCII 히트맵.
- 필요시 JSON (
--format json) (CI 게이트나 다른 도구용).
규칙
- 엔진은 읽기 전용입니다 — 스킬을 편집하지 않습니다. 재작성은 에이전트(사용자)가 승인한 후에만 적용됩니다.
- 명시적 확인 없이 스킬을 삭제하지 마세요.
- 설명을 다시 쓸 때 사용자가 의존하는 모든 실제 트리거 문구는 보존하고, 이동/명확화만 수행하며 제거하지 마세요.
알고리즘은 references/methodology.md, 각 이슈 유형 수정 방법은 references/issue-catalog.md를 참조.