skill-reviewer

name

skill-reviewer

description

Score and improve a SKILL.md or CLAUDE.md file. Rates four criteria — purpose clarity, persona orchestration, role fit, token efficiency — each 0–10, reports the average as the final score, then writes an improved copy as a NEW file (never overwrites the original). Use when the user wants to evaluate, audit, rate, score, grade, critique, or improve a SKILL.md / CLAUDE.md — e.g. "내 SKILL.md 검토해줘", "이 CLAUDE.md 10점 만점으로 점수 매겨줘", "SKILL.md 어디가 약해?", "rate my CLAUDE.md", "/skill-review". Fires even if only one of the two file types is mentioned. Do NOT use to create a SKILL.md from scratch (→ skill-creator), to edit a CLAUDE.md in place (→ claude-md-improver), to review a plain README/markdown, or to fix typos.

Markdown Doc Reviewer (SKILL.md / CLAUDE.md)

이 skill은 SKILL.md·CLAUDE.md 파일 하나를 4개 항목 × 10점으로 채점하고, 평균을 최종 점수로 보고한 뒤, 같은 디렉토리에 개선된 새 파일(*.improved.md)을 만든다(새 파일 규칙의 근거·예외는 4단계 참고).

왜 점수를 매기는가: SKILL.md의 품질은 "발동하는가 + 발동 후 일관되게 동작하는가"로 갈린다. 4개 항목은 이 두 가지를 분해한 것이고, 루브릭 앵커는 사람마다 점수가 흔들리지 않도록 고정한다.

워크플로우 (순서 고정)

0. 라우팅 — 대상이 맞는지 먼저 거른다

아래에 해당하면 채점하지 말고 해당 skill로 안내한 뒤 종료한다.

요청 형태	보낼 곳
새 SKILL.md를 처음부터 작성	skill-creator
CLAUDE.md를 in-place로 즉시 수정	claude-md-improver
README 등 일반 markdown 검토	대상 외 — 일반 도구로
단순 오타·문법 교정	대상 외

1. 대상 파일 확정

• 사용자가 경로를 주면 그 파일만 본다.
• 아니면 탐색: **/SKILL.md(대소문자 무관), ./CLAUDE.md, ./.claude.local.md, ~/.claude/CLAUDE.md, **/CLAUDE.md.
• 여러 개면 목록을 보여주고 어느 것을 볼지 묻는다. 여러 파일을 한 번에 채점하지 않는다 — 한 번에 하나.
• 파일을 끝까지 읽는다. 200줄을 넘어도 전부 읽고 채점한다(길이 자체는 4번 항목의 감점 신호일 뿐, 읽기를 생략할 이유가 아니다).

2. 4개 항목 채점 (1→2→3→4, 순서 중요)

순서가 고정된 이유: 1번(목적)을 모르면 3번(역할이 목적에 맞는지)을 채점할 수 없다.

항목	무엇을 보는가	채점 전 필수 행동
1. 목적 (Purpose)	description·첫 문단·헤더에서 왜 존재하는지를 한 문장으로 뽑을 수 있는가, 스코프 경계가 단단한가	한 문장 요약을 적는다
2. 오케스트레이션 (Orchestration)	파일이 Claude에게 부여하는 여러 역할(탐색자·채점자·작성자 등)을 하나의 흐름으로 묶는 상위 구조가 있는가	페르소나를 (a)(b)(c)… 로 명시 열거
3. 역할 배정 (Role Fit)	각 페르소나가 목적의 어느 조각에 직접 기여하는가, 잉여·누락이 있는가	페르소나마다 "→ 목적의 X 담당" 매핑
4. 토큰 효율·구체성 (Concreteness)	같은 효과를 더 적은 토큰으로 낼 수 있는가, 들인 토큰만큼 실행 가능한가	아래 감점 신호 체크리스트 적용

위 표의 "채점 전 필수 행동"은 선택이 아니다. 적지 않고 매긴 1·2·3번 점수는 무효다.

작업 노트는 어디에 적는가: 채점 전 필수 행동(1번 한 문장 요약, 2번 페르소나 열거, 3번 매핑)을 채점하기 전에 답변 안에 임시 "작업 노트" 블록으로 먼저 쓴다. 이 노트가 없으면 점수를 매기지 않는다 — 점수가 근거 없이 미정 상태로 남는 것을 막기 위함이다. 노트의 내용은 최종적으로 리포트의 1·2·3번 항목(한 문장 요약, 식별된 페르소나, 역할 배정 표)에 그대로 흘러가므로 별도 보관은 필요 없다. 즉 작업 노트는 리포트의 초안이고, 리포트는 작업 노트를 정리한 결과다.

항목별 점수 앵커 (4개 항목 공통)

점수	1. 목적	2. 오케스트레이션	3. 역할 배정	4. 토큰 효율
9–10	description만으로 한 문장에 즉시 잡힘, 경계 단단	모든 페르소나가 단일 워크플로우에 종속, 진입·종료 조건 명시	모든 섹션이 목적 조각에 직접 대응, 잉여 0·누락 0	잉여 표현 0, 모든 지시가 실행 가능(명령·포맷·임계값·예시)
7–8	목적 있으나 두세 번 읽어야 정리됨, 경계 약간 흐림	페르소나는 식별되나 전환 규칙 일부 모호	1~2개 섹션이 목적과 약하게 연결·부분 중복	한두 문단 압축 가능, 또는 일부 지시가 추상적
4–6	목적 분산, 다른 skill과 구분 모호	페르소나가 병렬 나열만, 발동 시점 불분명	상당수 섹션이 목적과 무관한 일반 조언	자명한 조언·페르소나 선언·장식 문장이 과반
1–3	목적 추출 불가	페르소나끼리 충돌·모순	역할 배정 자체가 안 됨	토큰만 먹고 행동 변화 없음

채점 절차(반드시 이 순서):

1. 앵커 표로 구간을 먼저 고정한다(9–10 / 7–8 / 4–6 / 1–3).
2. 4번 항목에 한해, 아래 즉시 감점 신호를 적용해 절차 1번에서 4번 앵커로 고른 점수에서 깎는다.
3. 한 항목 안에서 9와 10은 "사소한 흠 1개 = 9, 흠 0개 = 10"으로 가른다.
4. 경계가 애매하면 아래 타이브레이크로만 해소한다.

타이브레이크(위에서부터 우선 적용):

• 두 구간 사이에 걸치면 → 낮은 구간.
• 4번에서 감점 신호가 하나라도 걸리면 → 9–10 구간 불가(최대 8). 앵커가 9–10을 가리켜도 감점 신호가 있으면 8로 내린다. 앵커와 감점 신호가 충돌할 때 정답은 항상 이쪽이다.
• 평균이 등급 경계(예: 8.9 vs 9.0)에 정확히 걸치면 → 낮은 등급.

4번 즉시 감점 신호 (4번 앵커로 고른 점수에서 해당마다 −1, 최저 1점)

• 200줄 초과이고, 의미 손실 없이 잘라낼 수 있는 줄이 전체의 15% 이상이다(중복 문장·같은 말 반복·장식 헤더를 합산해 어림). 200줄 이하면 이 신호는 적용하지 않는다.
• 코드·명령·포맷 예시가 0개다
• 동일 규칙이 두 군데 이상 토씨까지 거의 같게 반복된다(요약·재진술이 아니라 복붙 수준)

"페르소나 선언만 있고 행동 규칙 없음"은 4번이 아니라 2·3번에서 본다. 페르소나를 선언만 하고 전환·진입·종료 규칙이 없으면 2번 앵커(병렬 나열·발동 시점 불분명, 4–6), 목적에 매핑되지 않으면 3번 앵커에서 깎는다. 4번은 그런 선언이 파일 토큰의 과반을 차지해 분량 낭비가 될 때만 4번 앵커(4–6: 페르소나 선언·장식 문장이 과반)로 잡는다. 같은 결함을 2·3번과 4번에서 이중으로 깎지 않는다.

채점 자기검증 (보고 전 1회)

• 네 항목 모두 앵커 표의 한 행을 근거로 댈 수 있는가
• 작업 노트(1번 한 문장 요약, 2번 페르소나 열거, 3번 매핑)를 점수보다 먼저 적었는가
• 4번 점수가 감점 신호 개수와 모순되지 않는가(신호 ≥1인데 9·10은 무효)
• 평균 산식 (1+2+3+4)/4를 다시 계산했는가
• 핵심 개선점이 점수를 깎은 항목과 연결되는가(엉뚱한 칭찬·트집 금지)

3. 리포트 출력

## 📋 검토 결과: <파일 경로>

**평균 점수: X.X / 10** (등급: ★★★★)
( 목적 X + 오케스트레이션 X + 역할배정 X + 토큰효율 X ) / 4 = X.X

### 1️⃣ 목적 파악: X/10
> 한 문장 요약: "..."
- 근거(앵커 어느 구간인지) + 코멘트

### 2️⃣ 페르소나 오케스트레이션: X/10
**식별된 페르소나:** (a) … (b) … (c) …
**오케스트레이션 평가:** …

### 3️⃣ 역할 배정: X/10
| 페르소나 | 담당 목적 조각 | 적합도 |
|----------|---------------|--------|
| (a) … | … | ◎/○/△/× |

### 4️⃣ 토큰 효율 & 구체성: X/10
- 즉시 감점: … (−X)
- 코멘트

### 🔴 핵심 개선점 (영향 큰 순)
1. …

### ✅ 잘된 점
- …

등급 척도

평균	등급	의미
9.0–10.0	★★★★★	즉시 사용
7.5–8.9	★★★★	사용 가능, 개선 권장
6.0–7.4	★★★	작동하지만 손볼 필요
4.0–5.9	★★	큰 폭 개정 필요
0–3.9	★	처음부터 재설계 권장

4. 개선 파일 생성 — 항상 새 파일, 원본 절대 미수정

원본은 어떤 경우에도 덮어쓰지 않는다(사용자가 diff로 비교 후 직접 교체). 사용자 확인 후(또는 "바로 만들어줘"면 즉시) 같은 디렉토리에 저장한다.

• foo/SKILL.md → foo/SKILL.improved.md
• ./CLAUDE.md → ./CLAUDE.improved.md
• 이미 있으면 .improved.2.md, .improved.3.md …로 충돌을 피한다(원본·기존 개선본 모두 보존).

작성 규칙:

1. 원본의 좋은 부분은 유지하고, 점수를 깎은 항목만 손댄다.
2. 섹션 순서·헤더를 보존한다(사용자가 diff 보기 쉽게).
3. 추가가 아니라 교체 — 빠진 항목은 채우고, 장황한 항목은 줄인다.
4. 모르는 명령·경로는 <!-- TODO: 확인 필요 --> 주석으로 남긴다(상상으로 채우지 않는다).
5. 파일 맨 위에 변경 요약 HTML 주석 한 블록:

<!--
skill-reviewer 개선본 (원본 평균 X.X → 예상 Y.Y)
주요 변경:
- 목적: …
- 오케스트레이션: …
- 역할배정: …
- 토큰효율: …
-->

마지막으로 안내한다:

"원본과 비교해 좋으면 mv <원본>.improved.md <원본>으로 교체하세요."

엣지 케이스

• 둘 중 한 종류만 다룬 파일: SKILL.md는 페르소나가 풍부하고 CLAUDE.md는 섹션별 역할(명령 안내자·구조 가이드·함정 경고자)로 본다. 둘 다 2·3번 항목을 동일하게 적용하되, CLAUDE.md에서 "페르소나"는 "섹션 역할"로 읽는다.
• 아주 긴 파일(>500줄): 전부 읽되, 4번에서 압축 가능 구간을 구체적으로 지목한다("X~Y절 중복").
• frontmatter 누락·name/description 없음: 1번에서 자동 4점 이하, 2번 채점은 본문으로 진행한다. name이 폴더명과 다르면 1번에 −1(발동 신뢰성 결함).

채점 중단 조건 (채점하지 않고 종료)

다음에 해당하면 점수를 매기지 말고, 명시한 출력만 내고 멈춘다.

• 빈 파일·헤더만 있음(본문 < 1줄): 리포트 포맷을 쓰지 않는다. 대신 "채점 불가: 내용 없음"을 한 줄로 보고하고, 4단계 새-파일 규칙에 따라 *.improved.md에 스켈레톤(frontmatter + 빈 4섹션)만 제안한다.
• 잘못 발동(README·일반 markdown·SKILL/CLAUDE 아님): 0단계 라우팅으로 돌려보낸다.
• 새 SKILL 작성·in-place 수정 요청: 0단계 라우팅 표대로 안내 후 종료.
• 읽기 실패(경로 없음·권한 없음): 점수 0이 아니라 "파일 접근 불가"로 보고하고 멈춘다(0점과 구분).

채점 예시 (보정용 — 점수 분포를 잡기 위한 두 개의 닻)

높은 예시와 낮은 예시를 둘 다 둔다. 새 파일이 이 사이 어디에 놓이는지로 절대 점수가 흔들리지 않게 한다.

높은 닻 (잘 만든 SKILL):

목적 10 + 오케스트레이션 9 + 역할배정 9 + 토큰효율 9 = 9.25 / ★★★★★ 식별 페르소나: (a) 라우터 (b) 파일 탐색자 (c) 채점자 (d) 보고자 (e) 개선본 작성자 — 모두 4단계 워크플로우에 종속, 잉여 0. 토큰효율이 9인 이유: 즉시 감점 신호 0개지만 헤더 한두 곳 더 압축 여지(흠 1개) → 10 아님.

낮은 닻 (약한 SKILL):

목적 5 + 오케스트레이션 4 + 역할배정 4 + 토큰효율 4 = 4.25 / ★★ "당신은 전문가입니다" 페르소나 선언만 있고 전환 규칙 없음(2번 4–6), 섹션이 목적과 느슨(3번 4–6), 명령·예시 0개 → 토큰효율 −1 적용.

새 파일을 채점할 때 두 닻 사이 어디에 떨어지는지 먼저 가늠하면 인플레이션·디플레이션을 동시에 막는다. 닻 점수 자체를 천장·바닥으로 오해하지 않는다 — 새 파일이 더 높거나 더 낮을 수 있다.

트리거 / 안티 트리거

트리거 O

• "내 SKILL.md 검토해줘" / "이 CLAUDE.md 어디가 약해?"
• "10점 만점으로 채점하고 개선본 만들어줘"
• "rate my SKILL.md" / "/skill-review"

트리거 X (→ 0단계 라우팅)

• "SKILL.md 새로 만들어줘" → skill-creator
• "README.md 평가해줘" → 대상 외
• "CLAUDE.md 바로 수정해줘" → claude-md-improver