Skill Doctor
SKILL.md를 진단하고 개선하세요. 매뉴얼이 아닌 나침반 — 구체적인 기준은 references/에 있으며, 필요 시 읽어서 사용합니다.
트리거 후 진단 흐름 (각 단계는 반드시 눈에 보이는 출력을 생성해야 함)
눈에 보이는 출력이 없는 단계는 조용히 건너뜁니다(Seleznov 실험, 2026). 단계당 한 줄의 확인 메시지를 출력하세요. 자체 검토 플래그: 이 세션에서 대상 SKILL.md를 이미 편집/작성한 경우, 모든 의사 출력 줄 앞에
[self-review]를 접두사로 추가하고, 3단계 끝에 한 줄을 추가하세요: "결론은 자체 평가되었으므로, 새 하위 에이전트와 함께 재검토를 권장합니다."
1단계: 대상 SKILL.md 읽기, 진단 시작 알림
편집 중인 SKILL.md의 전체 텍스트를 읽고, python3 <이-스킬-디렉토리>/scripts/check_listing_budget.py "<프로젝트_루트>"를 실행한 후(경로를 따옴표로 묶으세요 — 공백이 흔함), 다음 두 줄을 출력합니다:
[skill-doctor] 감사 중: <경로> 본문=<N> 줄 description=<M> 문자
[skill-doctor] 예산 (<플랫폼>): <K> 스킬, <T> 문자 vs 약<B> → <적합 | 오버플로 ×N.N>
플랫폼을 자동 감지합니다(CC / Codex / Hermes / OpenClaw). 종료 코드: 0 = 적합; 1 = 오버플로; 2 = 사용 불가 (플랫폼 없음 / 컨텍스트를 알 수 없음 → 사용자에게 플랫폼 + 창 크기 물어보기). 오버플로는 전체 수준의 주의사항(NOTICE)이지, 감사 대상 스킬에 대한 결함이 아닙니다: 사용자가 알 수 있도록 숫자를 출력하되, 예산 문제로 이 스킬의 설명을 줄이지 마세요 — 슬리밍은 전체 패스 작업이지, 단일 스킬 수정이 아닙니다.
2단계: 차원 기준에 따라 판단
참조 색인(차원 섹션)에서 로드할 차원을 선택하세요 — 읽기 시점(when-to-read) 조건이 발동하는 항목만 읽습니다. 로드 후 한 줄을 출력합니다:
[skill-doctor] 로드됨: <목록>; 건너뜀: <목록: 한 단어 이유>
2.5단계: 드라이런 워크스루 (본문에 워크플로우가 있는 경우에만)
references/effect-dry-run.md에 따라, 가장 일반적인 프롬프트 1개를 가져와 본문 단계를 따라 실행하며 입력/명령어/출력이 연결되는지 확인합니다.
끊어진 링크나 모호함이 발견되면 P0(효과 문제)으로 표시하고 3단계의 ❌ 섹션에 넣습니다.
한 줄을 출력합니다:
[skill-doctor] 드라이런 프롬프트: "<프롬프트>" 끊어진 링크=<N>
본문에 워크플로우가 없는 경우(순수 규칙/참조형 스킬), 다음을 출력합니다:
[skill-doctor] 드라이런: 건너뜀 (워크플로우 없음)
2.6단계: 실시간 주입 확인 (대상 스킬이 현재 세션 범위 내에 있는 경우에만)
대상 스킬이 이 세션의 사용 가능한 스킬 목록에 설명과 함께(이름만이 아닌) 나타나는지 확인합니다. 3가지 경우(주입됨 / 이름만 예산 드롭 / 범위 밖 건너뜀)와 전체 주의사항 규칙은 references/live-injection-check.md에 있습니다. 한 줄을 출력합니다:
[skill-doctor] 실시간 주입: <주입됨 | 드롭됨 (이름만) | 건너뜀 (<이유>)>
3단계: 진단 보고서 출력
아래 형식을 엄격히 준수하여 대화에 출력합니다:
[skill-doctor] 진단
❌ 반드시 수정 (P0→P3 순서로 정렬, 정의는 references/priority-tiers.md 참조)
[P0 효과 중단] <문제>: <이유> → <수정>
[P1 구조] <문제>: <이유> → <수정>
[P2 구체성] <문제>: <이유> → <수정>
[P3 실행 영향] <문제>: <이유> → <수정>
⚠️ 개선 제안 (순수 미관상/장황한 P3 포함)
- <문제>: <이유> → <수정>
✅ 통과한 검사
- <목록>
P3 배치 규칙: "수정하지 않으면, 다음에 이 스킬을 실행하는 LLM이 잘못된 작업을 수행할 것인가?"라고 물어보세요 — 예 → ❌; 단순히 보기 안 좋거나 장황한 경우 → ⚠️. references/priority-tiers.md를 참조하세요.
각 문제는 구체적인 줄 번호 또는 필드를 제공해야 합니다 — 모호함 금지. 동일한 종류의 위반이 여러 곳에서 발생하는 경우, 각각 별도로 나열하세요 — 예를 들어, 세 개의 하위 디렉토리에 잘못 분류된 콘텐츠는 1개의 병합된 항목이 아닌 3개의 문제여야 합니다.
해당되는 경우 실패 모드 이름을 지정하세요(references/predictability-glossary.md 참조): 발견 항목 앞에 [no-op] / [sediment] / [premature-completion] / [weak-leading-word] / [duplication] / [sprawl] 접두사를 붙입니다. 이름은 어떤 종류인지를 나타내고, P-등급은 여전히 얼마나 심각한지를 나타냅니다 — 이 둘은 직교하므로 접두사가 등급을 대체하지 않습니다.
4단계: 사용자 확인 후 편집 적용
확인 없이 편집하지 마세요. 사용자가 "수정해"라고 말할 때까지 기다리세요.
조치를 취하기 전에 크기 게이트와 삭제 전 검사를 적용하고, 이후 루프를 종료합니다 — 전체 절차는 references/apply-safety.md에 있습니다.
수정 후 한 줄을 출력합니다:
[skill-doctor] <N>개의 수정 사항을 <경로>에 적용함 본문: <이전>→<이후> 줄 (<+X%>)
하드 규칙 빠른 참조
정량화된 하드 규칙(위반은 제안이 아닌 오류)은 references/hard-rules.md에 있습니다 — 모든 감사 시 참조하세요.
예외 처리
경로가 없거나, YAML을 구문 분석할 수 없거나, 번들 스크립트(scripts/check_listing_budget.py + scripts/detect_platform.py / scripts/check_routes.py / scripts/eval_retrieval.py / scripts/check_desc_slim.py)가 없거나 종료 코드 2로 종료되는 경우 — references/exception-fallback.md에 따라 처리합니다. 예외를 먼저 사용자에게 알리고, 절대 조용히 건너뛰지 마세요.
출력 및 언어
보고서 산문은 references/output-style.md를 따릅니다(명확하고, 터미널 안전, 결론 우선). 본문/참조는 기본적으로 영어를 사용하며, 부당한 비영어 사용은 ⚠️로 표시합니다 — 정책 및 두 가지 정당한 예외는 references/language-policy.md에 있습니다.
이 스킬의 범위를 벗어난 항목
- 실제 기능의 정확성 여부 (이는 로직 버그이지 스킬 형식 문제가 아님)
- 프로젝트별 규칙 (이는 CLAUDE.md에 들어가야 하며, 스킬에 들어가지 않음)
- 일회성 수정 스크립트 (한 번 실행 후 폐기됨, 스킬이 아니어야 함)
이 스킬이 존재하는 이유
LLM이 SKILL.md를 매뉴얼처럼 잘못 작성하는 이유와, 이 스킬이 기계적 검사와 판단을 어떻게 분리하는지: references/rationale.md를 참조하세요.